AGENTS.md: Por que humanos devem escrever o contexto dos agentes (e não a IA)
O estudo da ETH Zurich mostra que agentes escrevendo seus próprios arquivos de contexto reduzem a performance em 3% e aumentam os custos em 20%. Veja o template testado da Autenticare.
Fabiano Brito
CTO, Autenticare
AGENTS.md para o próprio LLM parece eficiente, mas custa caro em previsibilidade. Dados recentes da ETH Zurich (Gloaguen et al.) comprovam: um arquivo de contexto mantido rigorosamente por humanos supera a auto-geração em performance e economia de tokens.
A orquestração de agentes autônomos em repositórios complexos exige regras claras. Quando você deixa os agentes soltos no código, eles precisam de um mapa geográfico do projeto, limites arquiteturais e anti-patterns locais. A solução mais comum para isso na comunidade é o arquivo AGENTS.md.
Mas quem deve escrever esse arquivo?
Muitos times automatizam a criação do contexto via LLMs (“leia este repo e resuma as regras”). Contudo, a pesquisa e a nossa experiência prática na Autenticare mostram que isso é uma falha arquitetural.
O Custo da Auto-Geração
taxa de sucesso na resolução
aumento no consumo de tokens
modelo ideal testado
De acordo com o estudo recente da ETH Zurich, permitir que agentes infiram e documentem sozinhos as regras do projeto leva a um decréscimo de 3% no sucesso da execução das tarefas e um aumento de 20% nos custos.
A razão é simples: o LLM foca no “o que” o código faz (que já está óbvio lendo os arquivos), mas não tem a intencionalidade de “por que” foi feito assim. Um agente gerando AGENTS.md cria descrições técnicas vazias em vez de restrições de negócio (constraints).
O Template Autenticare Testado
Defina o comportamento esperado, tom de voz (como o uso obrigatório de respostas diretas) e os limites do que o agente pode ou não fazer no repo.
Em vez de descrever o que é a pasta src/, estabeleça ONDE coisas novas devem ir (ex: "Nunca crie componentes genéricos fora de ui/").
A parte mais valiosa: liste as soluções que parecem corretas mas que foram banidas na sua empresa (ex: "Nunca use lodash, temos helpers nativos").
AGENTS.md é o seu contrato com a IA. Se a IA escreve o próprio contrato, ela naturalmente molda as regras para caminhos de menor resistência, ignorando dívida técnica a longo prazo.
Para engenharia agêntica escalável, escreva o contexto estratégico na mão e deixe o LLM automatizar apenas a execução tática.
Seu AGENTS.md não é uma wiki; é uma cerca elétrica comportamental. Trate-o como tal.
Para estruturar a base da sua orquestração de IA com as melhores práticas da Autenticare, conheça nossa Fábrica de Agentes. Precisa de ajuda com a governança da sua plataforma? Entre em contato com nosso time.