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.
O mais doido é que esse sujeito claramente não usa LLM e fica opinando sem fazer absolutamente a menor ideia do que está falando. Esse sim é um papagaio de inteligência artificial.
Tudo bem termos nossas opiniões, mas falar de algo técnico pro grande público sem ter uma mínima noção do assunto é mais do que constrangedor, é danoso.
Enquanto esses ditos céticos de inteligência artifical ficam repetindo esse monte de bobagem sem fundamento, um universo de coisas revolucionárias está acontecendo no mundo do software e, por consequência, na sociedade como um todo.
Note que ele não disse nada, apenas repercutiu uma análise de terceiros.
Bastante? O artigo menciona aumento médio de 20%, o que ainda assim é questionável porque depende:
1. da maneira como foi escrito
2. do modelo (os utilizados no estudo não são padrão da indústria — o Sonnet, único da Anthropic no estudo, é considerado um dos piores custo/benefício; fonte: https://deepswe.datacurve.ai/)
3. do tipo de plano do serviço
4. da forma que se usa o harness (quantas vezes se reseta a sessão, por exemplo)
Culpar o recurso por mau uso me parece um argumento fraco.
O artigo explica o porquê mas parece que o autor não leu: as instruções são bem seguidas — daí o custo –, mas coisas como listar a estrutura de arquivos não ajuda em nada. Ou seja, é o que e como se escreve que faz diferença.
É verdade que o Copilot vende essa ideia, mas, sinceramente, quem em sã consciência ainda usa esse troço? E é verdade que o Codex no comando /init manda listar a estrutura de arquivos, e isso me reforça mais uma vez o quão atrás a OpenAI está nesse jogo.
Na documentação oficial do Claude vemos o oposto: não inclua File-by-file descriptions of the codebase nem Anything Claude can figure out by reading code. Tem até o comando /doctor, que cuts content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews. Fonte: https://code.claude.com/docs/en/best-practices#write-an-effective-claude-md
Não é só isso. Como o autor não sabe do que fala, ele só tenta interpretar de maneira tendenciosa um artigo que ele acha que entendeu — e artigo esse que, embora mais ponderado que o tal David Gerard, tem seus problemas de metodologia, como inclusive apontou o Rafa Brovko abaixo. Adiciono que o experimento só avaliou a taxa de resolução, sem medir critérios como eficiência, segurança, qualidade de código, uso de infra de build, etc.
Os arquivos AGENTS/CLAUDE nada mais são do que pedaços de texto inseridos no contexto quando se inicia uma sessão. Pra LLM tudo é texto — não existe nada especial, nem mesmo as tais skills.
Esses arquivos idealmente contêm guidelines específicos do projeto. Por exemplo, eu prefiro mensagem curta de commit e em bullet points, e que o harness não faça push pro servidor (gosto de dar uma passada por alto antes pra ver se não tem nada gritante, e às vezes tem). Também não gosto de comentários verbosos por todos os cantos (uma tendência desses modelos), então defino que comentário é só pra algo crítico e com poucas palavras. E a lista segue. Nada disso aparece na métrica do estudo.
Fonte? Dica: é uma afirmação obviamente inválida, e qualquer pessoa que efetivamente desenvolve usando o Claude sabe disso empiricamente. Aliás, a parte abaixo (quando ele decide citar o artigo) já invalida a afirmação acima:
Essa recomendação não é novidade e está na documentação oficial do Claude: ‘bloated CLAUDE.md files cause Claude to ignore your actual instructions’.
Enfim, no final das contas esse autor aí que você tanto posta aqui é só um fanfarrão que fala um monte de bobagem sobre um tema que, por algum motivo, ele decidiu ser implicante, mesmo que ele não tenha domínio a respeito. E quem efetivamente usa a tecnologia fica constrangido de ler essas bobagens.
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!