Era Preguiçoso Demais para Escrever o CLAUDE.md — E Parece Que Foi a Decisão Certa

Toda vez que aparecia um post sobre CLAUDE.md (ou AGENTS.md) no meu feed, eu pensava “vou configurar isso depois” e passava reto. Ver as pessoas construindo configurações elaboradas de AGENTS.md me deixava um pouco ansioso. Será que eu estava ficando para trás?

Aí saíram dados recentes de benchmark, e essa ansiedade foi embora de uma vez. Descobri que minha preguiça era uma decisão de engenharia bastante racional.

Arquivos de contexto gerados por LLM pioram as coisas

“Certamente dar mais contexto ao agente ajuda, não é?” Eu também pensava assim.

Quando pesquisadores testaram contexto gerado automaticamente por LLM no SWE-bench Lite, a taxa de sucesso caiu 0,5%. No AgentBench, caiu mais 2%. Até arquivos escritos cuidadosamente à mão conseguiram apenas uma melhora de 4%. Eu chamaria isso de “overfitting de contexto”.

• Queda de 0,5% na taxa de sucesso com contexto gerado por LLM no SWE-bench Lite
• Queda adicional de 2% no AgentBench
• Aumento de 20–23% nos custos de inferência
• Efeito positivo (2,7%) observado apenas em repositórios sem nenhuma documentação

O artigo “Evaluating AGENTS.md”, de Gloaguen et al., confirmou: arquivos de contexto tendem a reduzir as taxas de sucesso em tarefas quando comparados a não fornecer contexto de repositório algum.

Agentes seguem instruções bem demais — e aí está o problema

O problema não é que os agentes ignoram suas instruções. É o contrário.

Escreva uma linha no seu arquivo de contexto mandando o agente usar uv, e ele vai instalar e executar uv mesmo em situações onde é completamente desnecessário, adicionando passos extras em toda execução.

Com o GPT-5.2, os tokens de inferência aumentaram 14–22% quando havia arquivos de contexto presentes. O agente estava tão ocupado cumprindo as instruções que perdeu o foco em resolver o problema de fato.

• Execuções desnecessárias de pytest aumentaram
• Uso das ferramentas grep e read foi além do necessário

”Não faça X” faz o agente pensar mais em X

Num post anterior, comentei sobre como o conteúdo do SKILL.md é lido em momentos específicos — o AGENTS.md tem um problema parecido.

Ele fica na camada de “mensagem do desenvolvedor”, entre o prompt do sistema e o prompt do usuário. Essa posição restringe bastante o raciocínio do agente.

Escreva “não mexa neste arquivo” e o agente vai pensar nesse arquivo uma vez a mais. Os pesquisadores chamaram isso de “efeito do elefante rosa”. Mande alguém não pensar num elefante rosa, e é exatamente isso que vai aparecer na cabeça dele.

• Ordem de prioridade: instruções do provedor → prompt do sistema → AGENTS.md → prompt do usuário
• Arquivos mantidos manualmente não acompanham as mudanças no código, então a informação fica desatualizada rápido

Se você precisar escrever um, mantenha o mínimo

Se o seu repositório não tem absolutamente nenhuma documentação, arquivos de contexto podem ajudar — os dados mostraram um efeito positivo de 2,7% nesses casos. Mas se você for escrever um, mantenha o volume no mínimo possível.

Uma linha para indicar a ferramenta de build específica do repositório. Uma linha para corrigir um padrão que o agente continua errando.

Adicione um truque do tipo “se encontrar algo estruturalmente estranho, sinalize imediatamente” e o agente vira uma ferramenta que fica reportando vulnerabilidades na base de código. Fora isso, tornar a estrutura do código mais intuitiva é muito mais eficaz do que escrever instruções sobre ela.

• Fortalecer testes unitários e checagens de tipo supera qualquer arquivo de contexto
• Se a localização dos arquivos está confusa, mova os arquivos em vez de escrever um guia

Escrever bons arquivos de contexto não é necessariamente sinal de habilidade. Entender a estrutura dos arquivos de contexto e projetar metassistemas em torno deles — isso sim é habilidade. E às vezes, “ser preguiçoso” é a melhor decisão de engenharia que você pode tomar.