Seu AGENTS.md pode estar sendo cortado no meio, e nada avisa

Todo token que o agente carrega antes do seu primeiro prompt disputa a atenção dele. Isso já se sabe. O que quase ninguém mede é quanto ele carrega, e o que acontece quando essa camada cresce demais.

Auditei três repositórios reais nas últimas semanas, todos meus. Em dois deles encontrei a mesma falha, e ela não é de tamanho. É de silêncio.

O teto que ninguém conhece

O Codex tem um parâmetro chamado project_doc_max_bytes. O padrão é 32 KiB, ou seja 32.768 bytes. Tudo que passa disso é descartado em silêncio: nenhum erro, nenhum aviso na tela, nada em log nenhum.

Num repositório grande que auditei, o AGENTS.md tinha chegado a 349 KB. Fazendo a conta, o agente recebia mais ou menos o primeiro décimo do arquivo. Meses de instrução escrita para um agente que nunca recebeu.

Em outro repositório o mesmo teto cortou o arquivo em 19,1%, no meio de uma frase. O agente continuou respondendo normalmente, porque um arquivo truncado não parece truncado: ele parece um arquivo menor.

A ferramenta que eu uso para medir isso é aberta e tem licença MIT: github.com/fabianmartinelli-fm/harness-audit. Ela roda em Claude Code, Codex, Cursor e Antigravity. O resto deste texto explica como medir na mão, o que muda depois de arrumar, e onde eu errei no processo.

O outro lado: o arquivo que impede a sessão de abrir

No mesmo repositório, o CLAUDE.md tinha chegado a 603.471 bytes. Na proporção que medi ali, isso dá em torno de 279 mil tokens, antes de qualquer prompt do sistema, ferramenta ou pergunta.

O efeito prático: nenhum modelo de janela 200k conseguia abrir aquele projeto. Não para trabalhar, não para responder uma pergunta trivial. A regra de custo do próprio time, usar modelo barato para trabalho mecânico, estava morta havia meses e ninguém tinha percebido, porque a falha não é "passou do orçamento". É "não inicia".

Como medir o seu em cinco minutos

1. Abra uma sessão nova e leia o /context

   No Claude Code, comece uma sessão limpa no repositório e rode /context antes de digitar qualquer coisa. O número que aparece ali é o que a sessão já gastou só para existir. Num projeto que auditei era 555,8 mil tokens, 56% de uma janela de 1M.

2. Meça o tamanho dos arquivos de entrada

   Copiar

   wc -c CLAUDE.md AGENTS.md GEMINI.md 2>/dev/null
   

   Qualquer valor acima de 32.768 bytes no AGENTS.md significa que o Codex está cortando. Compare com o teto e você sabe a porcentagem que chega.

3. Veja o que é cópia

   Num dos repositórios, 92,5% do AGENTS.md era cópia literal do CLAUDE.md: 3.031 das 3.276 linhas não vazias apareciam iguais no outro arquivo. Duas fontes de verdade mantidas na mão, uma delas lida pela metade.

4. Desconfie do que não está no repositório

   Num projeto, os arquivos do repositório eram só um décimo do que a sessão realmente carregava. O resto vinha da conta: plugins, conectores, hooks de início de sessão, subagentes e servidores MCP. Nada disso aparece para quem olha só o repositório, e dois desenvolvedores no mesmo código podem começar com quantidades bem diferentes de janela livre.

A armadilha nova do Claude Code

Desde a versão 2.1.277, o Claude Code passou a ler o AGENTS.md direto quando não existe CLAUDE.md. É uma boa mudança, e traz uma pegadinha.

A tabela de resolução

A regra oficial é esta:

Repare na segunda linha. O CLAUDE.local.md conta. Então num projeto cujas instruções vivem no AGENTS.md, um desenvolvedor que mantenha um CLAUDE.local.md pessoal e não versionado para de receber as instruções do time, só na máquina dele, sem nada reportando isso. O repositório continua configurado corretamente, e está, para todo mundo menos para ele.

Dois detalhes que mordem depois

• O Claude Code não lê AGENTS.local.md, AGENTS.override.md nem nada dentro de .agents/. O Codex lê o AGENTS.override.md com preferência sobre o AGENTS.md. Um repositório que use esse arquivo alimenta os dois agentes com instruções diferentes, e nenhum dos dois avisa.
• No Amazon Bedrock, ou com telemetria desligada, o Claude Code não consegue ler o AGENTS.md de jeito nenhum. Mesmo repositório, instruções efetivas diferentes conforme onde a sessão roda.

O que muda quando você arruma, e o que não muda

Depois da auditoria, o início de sessão dos dois repositórios ficou assim:

O que não melhorou

Agora a parte que costuma ficar de fora desse tipo de texto.

O agente acertou 8 de 8 tarefas antes da auditoria e 8 de 8 depois. Arrumar o contexto não deixa o agente mais inteligente, e nunca vai deixar. O contexto gasto por tarefa caiu só 8%.

O que mudou foi outra coisa: tempo total de quatro tarefas caiu de 40 para 7 minutos, as vezes em que precisei intervir no meio caíram de 2 para 0, e os efeitos colaterais de 6 para 0. Na primeira rodada o agente escreveu cinco arquivos onde não devia, commitou no meio de uma tarefa e deixou um servidor rodando. Na segunda, perguntou antes e não escreveu nada fora do lugar.

Onde eu errei nesse processo

Duas coisas, porque elas mudam como você deve ler os números acima.

O estimador de tokens estava errado por 1,9x. A regra de 4 caracteres por token vale para prosa corrida, e nenhum arquivo de instrução é prosa corrida. Medindo markdown técnico denso, com caminho, identificador em crase e tabela, deu 2,10. Por isso todo número deste texto é leitura direta de /context ou contagem de bytes, nunca estimativa.

Um dos meus benchmarks "depois" era inválido. Eu mandava o agente rodar as tarefas de novo em sessões novas, mas um subagente herda o retrato de contexto da sessão que o chamou. Ou seja: ele media o harness que o pai tinha carregado, não o que estava no disco. Cinco veredictos confiantes e falsos. Publiquei isso por extenso, porque medição errada com número bonito é pior que não medir.

A ferramenta

Empacotei esse processo numa skill aberta, com licença MIT, porque eu ia precisar de novo. Ela mede o que cada agente carrega antes do primeiro prompt separado por origem, pontua, escreve um plano de mudança agrupado por risco, aplica só o que você aprovar numa branch, e mede de novo.

Nada é apagado: as regras vão para documentos com escopo e frontmatter, o conteúdo superado fica marcado, o sha256 é conferido antes de tocar nos arquivos de entrada, e onde dois arquivos discordam ela se recusa a juntar e deixa a decisão para uma pessoa.

Funciona com Claude Code, Codex, Cursor e Antigravity, com ou sem Obsidian. Roda em Python 3.9+, só biblioteca padrão.

github.com/fabianmartinelli-fm/harness-audit

Se você rodar no seu projeto, abra uma issue com o número antes e depois. Os três pilotos que eu tenho são todos meus, e isso limita tudo que eu posso afirmar aqui.

Fontes

• Claude Code: how Claude remembers your project — tabela de resolução do AGENTS.md e as exceções
• Claude Code changelog — versão 2.1.277
• Documentação do Codex em developers.openai.com/codex — project_doc_max_bytes, conferida em setembro de 2026
• Relatórios dos três pilotos, com o que quebrou em cada um