ADR-0023 – Agente de Desenvolvimento "Gleam Architect"

• *Status:* Aceito
• *Data:* 2026-06-10

Contexto

As ferramentas de agentes LLM autônomos de códigos oferecem aos desenvolvedores o poder de automatizar tarefas repetitivas e tediosas. O projeto gbr_gleam_ai é um exemplo disso. Contudo, precisamos melhorar a arquitetura e organização do projeto para termos uma ferramenta poderosa e livre de alucinações de código para o desenvolvimento em Gleam.

O objetivo é eliminar qualquer alucinação, ou uso incorreto de sintaxe Gleam, em códigos gerados ou utilizados como exemplo no diálogo AI. Alguns exemplos de códigos Gleam incorretos gerados por LLMs são: - mcp_client:start_link ao invés de mcp_client.start_link, o operador de acesso é . e não : (sintaxe Erlang). - gbr_ets:new("arquivo", [public], read_only) ao invés de gbr_ets:new("arquivo", [Public], ReadOnly), os argumentos devem usar PascalCase (sintaxe Gleam CustomTypes).

Decisão

Com base na fundação estabelecida pelo ADR-0026 (separação do ecossistema de IA em gbr_ai_sdk e gbr_ai_harness), o *Gleam Architect* (gbr_gleam_ai) será estruturado como um conjunto especializado de ferramentas rodando sobre o gbr_ai_harness.

1. *Hospedagem no Harness:* O gbr_gleam_ai utilizará a base do gbr_ai_sdk e poderá ser inicializado através do executor padrão gbr_ai_harness.
2. *Ferramentas Especialistas via MCP:* Todas as ferramentas focadas em edição segura e inspeção de AST em Gleam (ex: ferramentas baseadas em glance, linters, ou AST builders) serão construídas e operadas como *Servidores MCP rigorosos*.
3. *Restrição Cognitiva:* O LLM do Gleam Architect atuará estritamente através dessas APIs MCP fornecidas, que validam a construção de código e impedem a introdução de falhas sintáticas ou misturas de dialeto Erlang/Gleam direto na árvore do projeto.

Consequências

• *Positivas:* - Garantia estrutural contra erros sintáticos primários induzidos pelo LLM. - Adoção reforçada do padrão "Read-Before-Write" e "Baby Steps", forçando o agente a consultar o contexto MCP e a validar compilações constantemente. - Consistência total com o design do ADR-0026, evitando sobreposições de responsabilidades.
• *Negativas / Desafios:* - Aumento da complexidade inicial: construir ferramentas de AST/Parser robustas em Gleam (ou via NIFs/Erlang) que sirvam de barreira MCP contra código malformado demandará esforço considerável.