A qualidade de um agente de programação geralmente diminui não porque o modelo se tornou menos capaz, mas porque o projeto carece de um sistema operacional claro que controle o que o agente lê, o que faz e como suas alterações são revisadas. À medida que o trabalho se estende por semanas e milhares de modificações, o agente pode redescobrir os mesmos arquivos, contradizer uma decisão anterior, adivinhar o comando de teste ou parar de escrever testes se essas etapas não forem impostas a ele.
Na sexta parte da série «Operando sistemas LLM em produção», o Stack Overflow Blog propõe construir uma camada de organização ao redor do modelo, incluindo uma constituição resumida do projeto, limites de autonomia, contexto em vários níveis, memória permanente, um comitê de revisão e um gancho executado após cada alteração. Ao executar vários agentes no mesmo repositório, acrescentam-se um mapa de propriedade dos arquivos e registros de prompts e decisões compartilhadas.
O problema está no cinturão operacional, não apenas no modelo
O artigo define o agente como o modelo acrescido de instruções, ferramentas, políticas de contexto, ganchos, isolamento, subagentes e mecanismos de monitoramento. Ele cita um resultado geral do benchmark Terminal-Bench 2.0, no qual a LangChain levou um agente de fora dos 30 primeiros para os 5 primeiros apenas alterando o cinturão operacional, elevando a pontuação de 52,8% para 66,5%, um aumento de 13,7 pontos, mantendo o mesmo modelo.
A lição prática é que ferramentas incompletas, regras ambíguas ou contexto excessivamente carregado podem ser a causa de falha mais fácil de corrigir. Ao contrário do modelo, a equipe de desenvolvimento pode modificar essa camada e alinhá-la ao seu repositório.
Seis elementos para um agente único disciplinado
- Constituição do projeto: um arquivo como CLAUDE.md ou AGENTS.md define o ciclo de trabalho: planejamento, documentação, implementação, testes, revisão e, depois, commit. Ele deve incluir critérios de qualidade e limites para o uso de pacotes de fornecedores, mantendo-se curto porque é lido em todas as sessões.
- Limites de autonomia: o agente pode executar operações reversíveis, como leitura, edição, testes e criação de commits, enquanto operações de push, implantação e aplicação de alterações de infraestrutura exigem aprovação. É necessário verificar a semântica da correspondência dos comandos para que regras amplas, como npm:*, não permitam uma implantação acidentalmente.
- Contexto em vários níveis: o CONTEXT.md da raiz inclui o mapa do projeto e a forma de executá-lo e testá-lo, enquanto o arquivo de cada módulo explica sua responsabilidade, seus arquivos e suas dependências. O DECISIONS.md registra as decisões, seus motivos e as alternativas rejeitadas. Contexto desatualizado é um erro que deve ser corrigido na própria alteração.
- Memória permanente: o material propõe arquivos de memória separados para cada fato, um índice resumido e um arquivo graph.jsonl que conecta módulos e decisões por meio de relações como depende de ou substitui.
- Comitê de revisão por múltiplas perspectivas: subagentes revisam a alteração sob as perspectivas de produto, engenharia, infraestrutura, segurança e testes. A alteração só deve ser impedida por um bloqueio ou por um problema grave com alta confiança.
- Gancho pós-alteração: o PostToolUse é executado após cada Edit, Write ou MultiEdit e emite uma lista que lembra de atualizar o contexto, a memória e o registro de decisões na própria alteração, em vez de reescrever os arquivos silenciosamente.
Ao executar uma frota de agentes
Surge um novo problema quando vários agentes trabalham no mesmo repositório: a alteração dos mesmos arquivos ou a reversão das decisões de outros agentes. O artigo não recomenda depender de conversas diretas entre eles, mas de um estado compartilhado, escrito e auditável, que inclua um mapa de propriedade dos caminhos, registros de CLAIM e RELEASE, um registro de progresso e uma ramificação independente para cada tarefa, com merge humano.
Essas reivindicações não são um bloqueio real; dois agentes podem ler o mesmo estado e reivindicar o mesmo caminho ao mesmo tempo. Quando for necessário um isolamento efetivo, o artigo recomenda um mecanismo atômico, como uma ramificação do Git com nome exclusivo ou uma escrita condicional em um armazenamento de coordenação.
Por que essa abordagem é importante?
A verdadeira mudança aqui é transferir o foco da capacidade do agente de escrever uma função para a capacidade do sistema ao seu redor de mantê-lo orientado e auditável ao longo do tempo. O registro de decisões desempenha um papel contratual, não apenas documental: as decisões antigas não são modificadas; novas decisões são adicionadas para substituí-las, com a explicação do motivo e das alternativas rejeitadas. Assim, o histórico do design permanece visível e pode ser associado a verificações automatizadas, como a proibição de determinadas importações.
Essa abordagem continua sendo uma orientação organizacional, não uma garantia da correção dos resultados. O artigo também reconhece que as reivindicações baseadas em arquivos são consultivas quando há colisões simultâneas e que a revisão humana continua sendo o ponto de controle no merge, no push e na implantação. A conclusão do material é que conter o modelo e construir rastros auditáveis podem ter mais impacto sobre a confiabilidade do trabalho de longo prazo do que esperar por um modelo mais inteligente.