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

CLAUDE.md e AGENTS.md foram pensados como um jeito rápido de explicar ao agente as regras do projeto, mas um novo estudo mostra que contexto longo costuma prejudicar mais do que ajudar. Em uma amostra de 138 repositórios Python, os pesquisadores da ETH Zurich viram queda na taxa de sucesso e aumento de custos, principalmente nos arquivos gerados automaticamente.

O que o estudo mostrou

Os autores de Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? pegaram 138 repositórios reais, reuniram 5694 pull requests e rodaram as tarefas em quatro modelos: Claude Sonnet 4.5, Codex GPT-5.2, GPT-5.1 Mini e Qwen3-30B. Eles compararam três cenários: sem arquivos especiais, com instruções geradas por LLM e com AGENTS.md mantidos por pessoas. Isso é relevante: o estudo não olhou para demos abstratas, mas para tarefas reais de bases de código em uso.

O principal resultado para os arquivos criados automaticamente foi desfavorável. A taxa de sucesso caiu em média 3%, enquanto o custo de inferência subiu mais de 20%. Os arquivos escritos por humanos se saíram melhor: elevaram o sucesso em cerca de 4%, mas o custo também subiu quase 19%. Ou seja, o arquivo de contexto não se mostrou um acelerador gratuito. Mesmo quando ajuda, o ganho de qualidade é modesto diante do gasto extra constante com tokens e passos desnecessários do agente.

Por que um arquivo longo atrapalha

A observação mais contraintuitiva do artigo: descrições da estrutura do projeto quase não ajudam o agente a se orientar. Seções sobre pastas, arquitetura e stack parecem úteis para uma pessoa, mas o agente costuma encontrar tudo de qualquer forma com grep, glob e leitura de arquivos. Se a informação já está no pyproject.toml, no package.json, na configuração do linter ou na própria estrutura do repositório, uma explicação longa apenas duplica o que o modelo consegue descobrir rapidamente sozinho.

Se o agente consegue descobrir isso sozinho a partir do código, é

melhor remover das instruções.

Os pesquisadores também notaram que modelos com arquivos de contexto fazem mais ações do que a tarefa exige. Eles releem as instruções com mais frequência, rodam testes uma vez a mais e chamam com mais disposição as ferramentas mencionadas no arquivo. O artigo registra à parte um aumento de reasoning tokens nos modelos GPT. Em outras palavras, a instrução não só adiciona conhecimento, como muda o comportamento do agente: ele passa a seguir regras mesmo onde elas não ajudam a resolver a tarefa atual.

O que vale manter

O estudo não leva à conclusão de abandonar por completo o CLAUDE.md ou o AGENTS.md. A conclusão é outra: esses arquivos devem ser curtos e conter apenas o que o agente não consegue deduzir com segurança a partir do código ou das configurações. Quanto menos texto decorativo, menor o risco de o modelo se prender a rituais desnecessários em vez de cumprir o pedido concreto.

• Um comando não padrão para rodar os testes
• O gerenciador de pacotes, se não for óbvio
• Scripts customizados, ferramentas e particularidades de deploy
• Regras de nomenclatura, se não puderem ser deduzidas rapidamente do código
• Uma referência ao .env.example ou a outro arquivo de entrada crítico

Outro estudo complica o quadro: nele, o Codex com AGENTS.md apresentou aceleração e menor consumo de tokens. Mas a amostra era bem menor, e a correção dos resultados foi avaliada de forma limitada. Por isso, a conclusão geral por ora é cautelosa: um contexto curto e prático às vezes ajuda, enquanto um arquivo longo com visão geral de arquitetura, stack e regras gerais vira facilmente um lastro caro. A ETH Zurich também quase não aborda a manutenibilidade do código nem a aderência ao estilo do projeto, então a discussão sobre a utilidade desses arquivos ainda não está encerrada.

O que isso significa

A conclusão prática é simples: trate o CLAUDE.md como uma lista de erros corrigidos do agente, não como a enciclopédia do projeto. Se uma instrução não ajuda a evitar uma falha específica, não descreve um comando não padrão e não acrescenta contexto único, é melhor removê-la. Para equipes que usam muito agentes de código, é um motivo direto para enxugar os arquivos de contexto, reduzir o gasto com tokens e verificar, nas próprias tarefas, quais linhas realmente melhoram o resultado e quais só criam ruído caro.