O estudo da ETH Zurich mediu o preço do seu CLAUDE.md, e a conclusão que viralizou é a errada

14/09/2026

O Dani Geek — arte original

Arquivo de contexto para agente de código custa mais de 20% a mais por tarefa e não melhora o resultado medido. A leitura que virou manchete (“joga fora seu AGENTS.md”) ignora o que o paper de fato encontrou.

O que foi medido, com os números certos

Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev e Martin Vechev, do SRI Lab da ETH Zurich, publicaram em 12 de fevereiro de 2026 o “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?” (arXiv:2602.11988, v2 em 23 de junho). O trabalho foi aceito no workshop MemAgents do ICLR 2026, como Oral e Runner-up Best Paper, com código e benchmark abertos em eth-sri/agentbench. A motivação é boa: escrever AGENTS.md e CLAUDE.md é recomendação dos próprios fabricantes dos agentes, e ninguém tinha medido com rigor.

O desenho tem duas metades, e quase todo mundo cita só a primeira. Uma é o SWE-bench Lite: 300 tarefas de 11 repositórios populares, com arquivos de contexto gerados por LLM. A outra é o CTXbench, benchmark novo que eles montaram: 138 issues de 12 repositórios menos populares que já tinham arquivo de contexto commitado pelo desenvolvedor. Quatro agentes rodaram tudo: Claude Code (Sonnet-4.5), Codex (GPT-5.2 e GPT-5.1 mini) e Qwen Code (Qwen3-30b-coder).

Os resultados, para o argumento não descolar do dado (v2 do paper):

• Arquivos gerados por LLM: 0,5 ponto percentual abaixo do baseline no SWE-bench Lite, 2 pontos abaixo no CTXbench, com p = 0,87 e p = 0,37. Nenhum efeito detectável.
• Arquivos escritos por desenvolvedor: 2,4 pontos acima no CTXbench, p = 0,21. Também sem significância, porém significativamente melhores que os gerados por máquina (p = 0,038).
• Custo: 20 a 23% a mais para os gerados por LLM, até 19% para os escritos à mão. O custo vem de passos extras: 2,45 passos a mais no SWE-bench e 3,92 no CTXbench.

Duas observações antes de seguir. A leitura honesta desses números é “indistinguível de zero”, nunca “piora”. E se você viu a figura de “queda de 3%” em algum resumo, ela não está no paper. É boato de agregador.

Os autores não pediram para você apagar o arquivo

A recomendação deles, na página do SRI Lab, é específica: não gere o arquivo com LLM, e limite a instrução escrita à mão ao que o agente não consegue inferir sozinho, tipo comando de build custom ou ferramenta específica do projeto. Isso é bem diferente de “não escreva regra para o agente”, que foi o que circulou no Hacker News e no X.

Então o alvo da discordância aqui não é o paper. É o resumo de 280 caracteres que o substituiu.

O agente obedece. É esse o problema.

A hipótese mais confortável para quem escreve regra é “o agente ignorou”. Os autores testaram e descartaram. Quando o arquivo menciona uma ferramenta, o agente usa: uv apareceu 1,6 vez por instância nos casos em que estava mencionado, contra menos de 0,01 vez quando não estava. A frase do paper é direta: a ausência de ganho “is not due to a lack of instruction-following capabilities”.

O que não funciona é a parte do arquivo que a maioria escreve primeiro. Entre 95% e 100% dos arquivos gerados por LLM traziam um “overview” do projeto, e ele não reduziu de forma relevante os passos até o agente abrir o arquivo certo. “Context files do not provide effective overviews”. Nenhuma categoria isolada de conteúdo mostrou ganho significativo.

Junte isso a um segundo achado, de um estudo independente de Damon McMillan publicado em 11 de maio de 2026 (arXiv:2605.10039): em 1.650 sessões de Claude Code CLI e 16.050 observações, cada função a mais que o agente gera está associada a cerca de 5,6% menos chance de conformidade por passo. Formato, ordem e tamanho do arquivo não tiveram efeito detectável. A adesão apodrece dentro da própria sessão, e mexer na diagramação do texto não segura.

Ou seja: a obediência é comprada com tokens a cada rodada, e o recibo vence antes do fim da sessão.

Aqui a regra estava escrita, era obedecida, e falhou duas vezes em seis dias

Eu tenho um repositório em produção onde isso aconteceu documentado, com data.

O contexto: sessões paralelas do agente compartilham a mesma working tree deste checkout. A regra no CLAUDE.md diz para estagiar arquivo por arquivo e nunca usar git add -A. Está escrita desde 14 de agosto, com o porquê junto.

No dia 14 de agosto, uma sessão que trabalhava no site do ODG commitou uma mensagem docs(040): … e levou junto cerca de 360 linhas da migração de outra lane. No dia 20, o commit 8aae414 levou junto a opção --validado do roadmap, que outra sessão estava escrevendo no cli.py naquele momento. Nada se perdeu nos dois casos. O que quebrou foi o histórico: git log <arquivo> passou a atribuir a mudança ao trabalho errado, e mentira em git log só é descoberta quando alguém precisa dela.

Duas vezes em seis dias, com a regra clara no arquivo, num agente que o paper mostra ser obediente. A conclusão que ficou commitada na doutrina da casa foi: regra que depende de memória é convenção, e convenção sem enforcement é decoração.

A mesma regra, escrita como código

O que existe hoje no lugar do parágrafo sozinho é um hook PreToolUse que recusa o comando antes de ele rodar. Recorte real de src/zero_crew_studio/git_guard.py:

_ADD_MASSIVO = frozenset({"-A", "--all", "-u", "--update", ".", "*", ":/"})

def avalia(comando: str) -> str | None:<br>    """O motivo da recusa, ou `None` se o comando pode passar."""<br>    for linha in _linhas_de_comando(comando):   # pula o corpo dos heredocs<br>        for tokens in _segmentos(linha):        # shlex, não substring<br>            if tokens[0] != "git" or "-C" in tokens:<br>                continue<br>            resto = [t for t in tokens[1:] if not t.startswith("-")]<br>            sub = resto[0] if resto else ""<br>            if sub == "add" and _ADD_MASSIVO.intersection(tokens[1:]):<br>                return "`git add -A` leva junto o que outra sessao POSSA estar editando…"<br>            if sub == "commit" and "--" not in tokens:<br>                return "`git commit` sem pathspec commita o indice INTEIRO…"<br>    return None<br>```

Dois detalhes valem mais que o resto do arquivo. O `_linhas_de_comando` pula o corpo dos heredocs porque as mensagens de commit desta casa citam a própria regra, e um scan por substring acusaria justamente os commits que estão obedecendo. E o `git -C` passa de propósito: quando o repositório é só seu e você quer mesmo varrer tudo, `git -C . add -A` funciona. O guarda é anti engano, não anti adversário, e hook que tranca o caminho legítimo vira hook desligado.

O registro em `.claude/settings.json`:

{

}

O `$CLAUDE_PROJECT_DIR` não é enfeite: caminho relativo colado por quem está lendo isso não funciona.

O que mudou na conta: essa checagem custa zero token de inferência, roda no passo 200 exatamente como roda no passo 1, e a recusa já vem com o comando certo dentro. Ela não tem opinião.

## A régua que eu tirei disso

Eu mantive o parágrafo no `CLAUDE.md` e movi a cobrança para fora do prompt. O parágrafo continua explicando o porquê para o humano que abre o repo. Quem cobra é código.

Três formas da mesma regra convivendo aqui, com preços diferentes: parágrafo no arquivo de contexto (paga pedágio toda rodada, adesão decai dentro da sessão), lint no `pre-push` (0,4s, pega quem editou por fora do agente), check no CI (sha256 no cabeçalho do arquivo gerado, sem contorno). Só a primeira aparece na conta da API.

A régua prática: se sua regra pode virar hook, ela não devia estar apenas no `CLAUDE.md`. O que sobra lá é exatamente o que os autores do paper recomendam, o não-inferível.

## O que ninguém mediu ainda

Preciso dizer com todas as letras: o paper não testou isso. Nenhum braço do experimento comparou regra como texto contra regra como enforcement determinístico. Os números do estudo sustentam a primeira metade do meu argumento (o parágrafo custa e não rende), e a segunda metade é hipótese minha, apoiada em dois incidentes de um repositório só.

Tem outro buraco, e ele é grande. Os dois benchmarks usam repositório público de código aberto, onde o agente infere quase tudo lendo o próprio código. Repositório privado, com convenção interna, domínio fechado e decisão que não está escrita em lugar nenhum, é justamente o caso em que o arquivo deveria pesar mais. Ninguém mediu esse.

É o que eu ia querer ler em seguida: alguém rodando o CTXbench contra um monorepo privado, e alguém comparando hook contra parágrafo na mesma tarefa. Se você tiver um repositório fechado e um fim de semana, o benchmark deles está no ar e aceita fork. Se rodar, me manda no [@odanigeek](https://x.com/odanigeek) no X ou no [Threads](https://www.threads.net/@odanigeek) que eu leio e comento.