Seu arquivo AGENTS.md não serve para nada
Os fornecedores de robôs de programação com IA dizem a você para usar um arquivo de contexto com instruções para auxiliar o chatbot. O Claude Code quer um CLAUDE.md, ou tem o AGENTS.md, que é mais genérico.
Mas será que o seu AGENTS.md faz alguma diferença? Uma equipe da ETH Zurich testou arquivos do tipo (vídeo). Eles rodaram os robôs em projetos de teste, com e sem AGENTS.md:
Surpreendentemente, descobrimos que fornecer arquivos de contexto não melhora, de modo geral, as taxas de sucesso nas tarefas — e ainda aumenta o custo de inferência em mais de 20% em média. Essa observação se mantém em diferentes LLMs, agentes de programação, e tanto para arquivos de contexto gerados por LLM quanto escritos por desenvolvedores.
Um arquivo AGENTS gerado por chatbot faz o agente de programação ter um desempenho parecido com o de não ter arquivo AGENTS nenhum — ou até um pouco pior. Um arquivo AGENTS escrito por humano tem taxas de sucesso um pouco melhores, mas nada absurdo.
Ter um AGENTS.md aumenta bastante o custo em tokens — seja o arquivo gerado por chatbot ou escrito por humano. (A Anthropic provavelmente considera isso uma vantagem.) O robô processa mais coisas, mas não fica mais capaz de terminar sua tarefa com sucesso.
Visões gerais da estrutura de arquivos do repositório de código não ajudam o agente. Elas não fazem o robô editar os arquivos listados mais rápido.
Afinal, o arquivo AGENTS faz alguma coisa? Se você menciona ferramentas específicas nele, o agente de IA passa a usá-las com mais frequência. Só isso.
Quando a Anthropic recomenda o CLAUDE.md, eles não avaliaram se o arquivo de instruções realmente funciona. Só jogaram ali como uma espécie de palavras mágicas que você pode invocar na esperança de que o robô acerte. Desta vez. Pelo menos você tem a sensação de estar fazendo alguma coisa.
Isso é bem parecido com a forma como a Anthropic escreve o Claude Code, que é basicamente uma pilha de palavras mágicas pedindo ao robô para não fazer besteira de novo. A Anthropic não conhece outro jeito de guiar o robô.
A recomendação dos pesquisadores: mantenha as instruções curtas. Seja breve. Ou, claro, você pode escrever um arquivão enorme e queimar muitos tokens!
A coisa mais próxima de uma utilidade real para o AGENTS.md é te forçar a organizar o próprio raciocínio acerca do funcionamento do projeto. Um desenvolvedor disse no Reddit:
O contexto em nível de token que ele fornece importa menos do que o fato de que escrevê-lo te obriga a colocar em palavras coisas sobre sua base de código que antes estavam só na sua cabeça.
Pois é, isso a gente costumava chamar de “escrever”. Já volto, vou começar a wiki do projeto. Chamo-a de HUMANS.md.
Publicado originalmente no Pivot to AI em 27/8/2026.
Depende… Entendo o ponto do estudo e concordo em partes. De fato, incluir em seus .md diretivas como “atue como um cientista de dados experiente em analisar dados de vendas”, modelar processos abertos de raciocínio como o “PDCA” ou coisas assim, que aparecem em muitos templates .md da moda, realmente são pouco úteis e efetivas. O mesmo vale para configurações de orquestração de multi-agentes, a medida que boa parte do trabalho fundamental (não me refiro a coisas laterais) assistido por agentes não é paralelizável (não de forma útil). Contudo, o agents/claude.md pode ser muito útil como espaço de formalização de processo do trabalho (em nível determinístico), atuando como trilho processual que controla, limita ou guia o trabalho probabilístico do agente. O estudo joga luz sobre toda pataquada e esoterismo que existe na indústria de “engenharia de harness”, mas generaliza a não utilidade real dos arquivos de configuração.
Interessante. Vou ler o estudo com atenção. Pelo que vi, eles buscaram projetos open source que usam esse tipo de instruções pros agentes e fizeram algumas coisas nesses projetos ignorando o que estava nesses agentes. Acho que pra demonstrar isso, teria que se testar partindo-se do zero, pois tudo que é produzido a partir de instruções declaradas em arquivos .md reflete as decisões desses arquivos, então se o projeto é feito até uma determinada versão usando-se esses arquivos, e a partir de determinado momento esses arquivos são apagados ou ignorados, qualquer agente que ler o código desses projetos vai poder derivar essas decisões legadas a partir do próprio código, independente das instruções de arquivos .md.
Mas posso estar errado, vou ler o artigo com atenção.
Boa sexta a todos!