Não gere automaticamente o AGENTS.md com `/init` — isso só aumenta os custos em 20%

Argumento central

• Se o arquivo de contexto para agentes de codificação com IA (AGENTS.md) for gerado automaticamente com o comando /init, o desempenho do agente piora e o custo aumenta em mais de 20%
• O problema central é fornecer de forma redundante informações que o agente já consegue descobrir por conta própria
• O AGENTS.md deve conter apenas informações que o agente não consegue saber apenas lendo o código

Resultado das pesquisas: o AGENTS.md ajuda ou atrapalha?

• Lulla et al. (ICSE JAWs 2026): experimento pareado com 124 PRs do GitHub, variando apenas a presença ou ausência de AGENTS.md
  • Quando havia AGENTS.md, o tempo de execução caiu 28,64% e os tokens de saída diminuíram 16,58%
  • O arquivo usado nesse estudo era mantido de fato pelos desenvolvedores e continha conhecimento específico do projeto
• Pesquisa da ETH Zurich: 4 agentes foram testados em SWE-bench e afins, distinguindo entre arquivos gerados automaticamente por LLM e arquivos escritos por desenvolvedores
  • Contexto gerado automaticamente por LLM: queda de 2% a 3% na taxa de sucesso, com aumento de custo de mais de 20%
    • Em um ambiente em que documentos existentes, como o README, foram todos removidos, o arquivo gerado por LLM chegou a melhorar o desempenho em 2,7%
  • Arquivos escritos diretamente por desenvolvedores: melhora de cerca de 4% na taxa de sucesso, com aumento de custo de até 19%
• Conclusão: o problema não é o conteúdo gerado automaticamente em si, mas a redundância
  • Dar a mesma informação duas vezes só adiciona ruído, e apenas o conhecimento impossível de descobrir escrito por desenvolvedores ajuda de forma concreta

Por que a geração automática faz mal

• O AGENTS.md gerado automaticamente quase sempre inclui informações que o agente já descobre sozinho
  • Visão geral do codebase (incluída em 100% das saídas do Sonnet 4.5 e em 99% das saídas do GPT-5.2)
  • Estrutura de diretórios, stack tecnológica, descrição de módulos
• Refornecer algo que o agente já sabe só consome tokens e não agrega valor
• Efeito de ancoragem: ao mencionar padrões legados, o agente tende a ficar preso a eles mesmo quando existem alternativas melhores
  • Isso está alinhado com o estudo "Lost in the Middle" (Liu et al., 2024) — contextos longos dispersam a atenção e pioram o desempenho

O que deve entrar no AGENTS.md vs. o que não deve

• Deve entrar (informações impossíveis de descobrir pelo agente)
  • Definição de ferramenta: "usar uv para gerenciamento de pacotes"
  • Regras não intuitivas: "os testes devem sempre rodar com --no-cache; caso contrário, os fixtures geram falso positivo"
  • Restrições do sistema: "o módulo auth usa middleware customizado; não refatorar para o Express padrão"
  • Quando uma ferramenta é mencionada na documentação, o agente a usa 1,6 a 2,5 vezes por tarefa; sem documentação, esse número cai para menos de 0,05 vez
• Não deve entrar (o que o agente já consegue descobrir sozinho)
  • Estrutura de diretórios, layout de monorepo
  • Visão geral da stack tecnológica, padrões arquiteturais padrão

Limitações estruturais de arquivos estáticos

• Mesmo um AGENTS.md bem escrito tem uma fraqueza fundamental — o arquivo é estático, mas a tarefa é dinâmica
• Instruções em um único arquivo não conseguem se ramificar conforme o tipo de tarefa
  • Até em tarefas de edição de documentação se aplica a instrução de "rodar toda a suíte de testes antes do commit", desperdiçando tokens e tempo
  • Um refactor de CSS acaba carregando alertas de migração de banco de dados, e uma correção de segurança vem acompanhada de dicas de otimização de desempenho
• Framework ACE (ICLR 2026): em vez de arquivo estático, a abordagem Agentic Context Engineering, com pipeline de generator/reflector/curator para evoluir o contexto dinamicamente, registrou desempenho 12,3% superior ao método estático

Uma estrutura melhor, ainda não construída

• Em relação ao AGENTS.md, várias pessoas chegaram de forma independente à mesma conclusão
  • A estrutura correta não é um arquivo único, mas uma camada de roteamento + contexto focalizado carregado sob demanda
• Camada 1 - arquivo de protocolo: não é uma visão geral do codebase nem um guia de estilo, e sim um documento de roteamento
  • Define personas disponíveis e condições de invocação, skills e tipos de tarefa sob sua responsabilidade, conexões MCP e seus usos
  • Deve incluir apenas o mínimo de fatos sobre o repositório que o agente não consegue descobrir, e nada além disso
• Camada 2 - arquivos de persona/skill: carregados seletivamente conforme o tipo de tarefa
  • Um agente de UX e um agente de backend carregam contextos diferentes, e não carregam o contexto um do outro
• Camada 3 - subagente de manutenção: agente dedicado a manter a precisão do arquivo de protocolo
  • Documentação apodrece — até no estudo da ETH Zurich houve queda de desempenho mesmo com arquivos recém-gerados
  • Se um AGENTS.md abandonado por 6 meses descreve dependências já substituídas ou uma estrutura de diretórios que mudou, o problema é muito mais grave
• Hoje, nenhum dos principais agentes de codificação oferece hooks de ciclo de vida que permitam implementar facilmente essa arquitetura — dá para aproximar isso com subagentes e contexto com escopo, mas ainda existe uma lacuna de tooling

Otimização automática

• Arize AI usa um loop de otimização automática em vez de escrever manualmente as instruções do CLAUDE.md
  • Executa o agente em tarefas de treinamento → avalia o resultado → gera feedback via LLM sobre a causa da falha → melhora as instruções por meio de metaprompting → repete
  • Em testes cross-repo, obteve +5,19%; em testes in-repo, +10,87% de melhora na acurácia
• Um fato incômodo revelado pelo otimizador: o que ajuda humanos a entender um codebase não é igual ao que um LLM precisa para navegar nele
  • Informações como "este serviço usa o padrão repository" parecem obviamente úteis para desenvolvedores, mas podem ser ruído para o modelo
  • Por outro lado, coisas de que o modelo realmente precisa (como distinguir caminhos de import específicos ou convenções não intuitivas de nomenclatura de arquivos) são tão internalizadas por desenvolvedores que eles nem pensam em escrevê-las
• Escrever o AGENTS.md manualmente pressupõe que o desenvolvedor sabe do que o agente precisa
  • As evidências empíricas sugerem que provavelmente não sabe
  • O otimizador encontra a diferença entre "o que parece importante" e "o que realmente muda o resultado"
• Isso não significa abandonar a escrita — 5% é relevante, mas não transformador. Significa segurar a intuição com menos força e testar de verdade

A mentalidade correta para encarar o AGENTS.md

• Veja o AGENTS.md como um registro de processos que você ainda não conseguiu corrigir
• Cada linha adicionada é um sinal de que existe alguma ambiguidade no codebase suficiente para confundir agentes de IA — e, pelo mesmo motivo, novos contribuintes humanos provavelmente também vão se perder
• A resposta correta não é aumentar o arquivo de contexto, mas corrigir a causa raiz
  • O agente coloca uma utility em um diretório aleatório → a própria estrutura de diretórios é confusa, então reorganize-a
  • O agente continua usando uma dependência obsoleta → a estrutura de imports facilita demais capturar a coisa errada, então corrija isso
  • O agente deixa passar checagem de tipos → em vez de depender de instruções, faça isso ser detectado automaticamente no pipeline de build
• O AGENTS.md é uma ferramenta de diagnóstico, não uma configuração permanente — adicione uma linha, investigue por que o agente continua cometendo esse erro, corrija a causa raiz e depois apague a linha
• Uma técnica para testar: começar com o AGENTS.md quase vazio e incluir apenas a instrução "se encontrar algo surpreendente ou confuso neste projeto, deixe um comentário". A maioria dos acréscimos sugeridos pelo agente não deve ser mantida para sempre, mas tratada como marcadores de pontos pouco claros no codebase

Recomendações práticas

• Pare de executar /init — a menos que o repositório não tenha documentação nenhuma, o resultado gerado automaticamente vai se sobrepor aos documentos já existentes
• Antes de adicionar uma linha ao AGENTS.md, pergunte: "o agente conseguiria saber isso lendo o código?". Se a resposta for sim, não escreva
• Quando o agente falhar repetidamente, corrija primeiro o próprio codebase antes de aumentar o arquivo de contexto
  • Melhore a estrutura do código, adicione regras de linter e amplie a cobertura de testes — só mexa no AGENTS.md se ainda assim não resolver
• Se você opera agentes em escala em pipelines de CI/CD ou revisão automática, tenha em mente que um overhead de custo de 15% a 20% se acumula de forma composta ao longo de milhares de execuções
• O impulso de fazer onboarding do agente como se fosse um funcionário novo (tour pelo escritório, organograma, explicação da arquitetura) é natural, mas agentes de codificação não são estagiários — antes mesmo de terminar de receber o prompt, eles já conseguem dar grep no codebase inteiro. O que o agente precisa não é de um mapa, mas da localização das minas terrestres

[lloydkwon]

No fim das contas, dizem que é uma briga de contexto...
Acho que não seria melhor fazer separar um md para o agent e outro md para o usuário?

[lukeio]

Concordo plenamente. A estrutura boa para humanos lerem (README) e a estrutura boa para um LLM fazer parsing (AGENTS.md) são completamente diferentes. Quando você simplesmente gera automaticamente todo o contexto e joga para o modelo, acaba só desperdiçando custo de tokens da API e, muitas vezes, até piorando as alucinações. No fim, por mais trabalhoso que seja, parece que o mais eficiente é a própria pessoa comprimir e refinar manualmente as instruções para o agente.

[sonnet]

No princípio, havia o README, e AGENTS.md é justamente o README feito para agentes.

[jaehar16]

Mas isso aí já não é o que o README faz?

[armila]

Mas o próprio modelo muda em questão de poucos meses,
então é preciso ajustar os agents de acordo com o modelo...
Não é o caso de a mudança do modelo ser mais rápida do que o tempo necessário para criar uma estrutura de agents adequada?
Antes mesmo de as pessoas se acostumarem com a ferramenta, a ferramenta já muda...

[jjw9512151]

No fim das contas, parece que o importante é manter sempre o contexto puro e com poucos tokens... Nessa perspectiva, dá até para pensar que os caracteres chineses são bastante úteis. kkk

[aliveornot]

Para o modelo, o inglês já é praticamente 1 palavra para 1 caractere (token), então na prática não seria como ideogramas chineses?

[eususu]

Oh, eu não tinha pensado nessa abordagem, mas acho que faz sentido!

[t7vonn]

Oh ..