Anthropic e ETH Zurich: um CLAUDE.md longo piora o desempenho do agente e aumenta os custos

CLAUDE.md e AGENTS.md foram planejados como uma forma rápida de explicar as regras do projeto a um agente, mas uma nova pesquisa mostra: contexto longo frequentemente prejudica mais do que ajuda. Em uma amostra de 138 repositórios Python, pesquisadores da ETH Zurich observaram queda na taxa de sucesso e aumento de custos, especialmente para arquivos gerados automaticamente.

O que a pesquisa mostrou

Os autores do artigo Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? pegaram 138 repositórios reais, coletaram 5694 pull requests e executaram tarefas através de quatro modelos: Claude Sonnet 4.5, Codex GPT-5.2, GPT-5.1 Mini e Qwen3-30B. Eles compararam cenários sem arquivos especiais, com instruções geradas por LLM e com AGENTS.md mantidos por humanos. Este é um ponto importante: a pesquisa olhou não para demos abstratos, mas para tarefas reais de bases de código ativas.

A conclusão principal para arquivos criados automaticamente acabou sendo desagradável. A taxa de sucesso caiu em média 3%, e o custo de inferência aumentou mais de 20%. Arquivos mantidos por humanos se saíram melhor: elevaram o sucesso aproximadamente 4%, mas o custo também subiu quase 19%. Em outras palavras, um arquivo de contexto não se revelou como um acelerador gratuito. Mesmo quando ajuda, o ganho de qualidade permanece modesto comparado ao pagamento excessivo constante por tokens e etapas extras do agente.

Por que arquivos longos prejudicam

A observação mais contraintuitiva do artigo: descrições da estrutura do projeto mal ajudam o agente a navegar. Seções sobre pastas, arquitetura e stack parecem úteis para humanos, mas agentes frequentemente encontram tudo sozinhos através de grep, glob e leitura de arquivos. Se a informação já está em pyproject.toml, package.json, config do linter ou na própria estrutura do repositório, uma explicação longa apenas duplica o que o modelo é capaz de descobrir rapidamente por si mesmo.

Se o agente pode aprender isso do código em si, é melhor remover da instrução.

Pesquisadores também notaram que modelos com arquivos de contexto realizam mais ações do que o necessário para a tarefa específica. Eles releem instruções com mais frequência, executam testes desnecessariamente e invocam mais ativamente ferramentas que foram mencionadas no arquivo. O artigo destaca separadamente o aumento de tokens de raciocínio em modelos GPT. Em outras palavras, a instrução não simplesmente adiciona conhecimento—muda o comportamento do agente: ele começa a seguir regras mesmo onde elas não ajudam a resolver a tarefa atual.

O que deve ser mantido

Uma rejeição completa de CLAUDE.md ou AGENTS.md não decorre desta pesquisa. Mais precisamente, a conclusão é diferente: tais arquivos devem ser curtos e conter apenas o que o agente não pode deduzir com confiança do código ou configs por conta própria. Quanto menos texto decorativo, menor o risco de o modelo ficar preso em rituais desnecessários em vez de executar o pedido específico.

• Comandos não padrão para executar testes
• Gerenciador de pacotes, se não for óbvio
• Scripts customizados, ferramentas e especificidades de deployment
• Convenções de nomenclatura, se não puderem ser rapidamente deduzidas do código
• Link para .env.example ou outro arquivo de entrada crítico

Outra pesquisa sobrepõe-se a este quadro, onde Codex com AGENTS.md mostrou aceleração e menor consumo de tokens. Mas lá a amostra era muito menor, e a correção dos resultados foi avaliada de forma limitada. Então a conclusão geral por enquanto é cautelosa: contexto curto e prático às vezes ajuda, enquanto um arquivo longo revisando arquitetura, tech stack e regras gerais facilmente se torna lastro caro. ETH Zurich também mal aborda manutenibilidade de código e adesão ao estilo do projeto, então a disputa sobre a utilidade de tais arquivos ainda não está fechada.

O que isto significa

A conclusão prática é simples: trate CLAUDE.md como uma lista de correções para erros do agente, não como uma enciclopédia do projeto. Se a instrução não ajuda a evitar uma falha específica, não descreve um comando não padrão e não adiciona contexto único, é melhor removê-la. Para equipes que usam ativamente agentes de codificação, esta é motivação direta para reduzir arquivos de contexto, reduzir gasto de tokens e verificar em suas próprias tarefas quais linhas realmente melhoram resultados e quais apenas criam ruído caro.