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 é um arquivo de contexto que estabelece regras, limites arquiteturais e o mapa de um repositório para a orquestração de agentes autônomos. Garantir que humanos escrevam esse documento, em vez de automatizá-lo via IA, é vital para evitar o aumento de 20% nos custos de tokens e a perda de performance nas tarefas.
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, conforme destacado na documentação oficial do Claude Code. 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”), como sugerido no guia de configuração do Codex. 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 a pesquisa 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.
Perguntas Frequentes sobre AGENTS.md: Por que humanos devem escrever o contexto dos agentes (e não a IA)
Qual é o problema de deixar a IA gerar o arquivo AGENTS.md? Deixar a IA gerar o AGENTS.md pode levar a um desempenho inferior e custos mais altos, pois a IA tende a focar no “o que” o código faz, em vez do “por que”, resultando em descrições técnicas vazias em vez de restrições de negócio.
O que devo incluir no arquivo AGENTS.md? O arquivo AGENTS.md deve incluir a identidade e o contrato operacional dos agentes, um mapa de arquitetura rígida e um catálogo de anti-patterns locais.
Qual é a importância do controle humano na criação do AGENTS.md? O controle humano na criação do AGENTS.md garante que o contexto estratégico seja definido manualmente, permitindo que a IA automatize apenas a execução tática, evitando que ela molde as regras para caminhos de menor resistência.
Quais são os benefícios de um AGENTS.md bem definido? Um AGENTS.md bem definido atua como uma cerca elétrica comportamental, guiando os agentes de IA e garantindo que eles sigam as restrições de negócio e evitem anti-patterns.