Como Prevenir o Apodrecimento do CLAUDE.md: Trate Regras Como Código

Após executar o Claude Code em projetos de produção por 18 meses, u/mm_cm_m_km identificou o ponto de falha mais comum: o arquivo CLAUDE.md apodrece. Não porque Claude o ignora, mas porque os desenvolvedores continuam adicionando regras sem nunca limpá-las. O resultado é um arquivo inflado de 500 linhas que custa tokens a cada turno e fica fora de sincronia com a base de código real.

1. CLAUDE.md como um Índice, Não um Manual

Mantenha CLAUDE.md com 30 a 50 linhas. Ele deve atuar como um sumário apontando para arquivos específicos para preocupações específicas — não uma parede de todas as preferências que você já definiu. Claude relê o arquivo a cada turno; arquivos curtos são baratos, arquivos longos desperdiçam tokens e atenção.

2. Cada Seção Responde a Uma de Duas Perguntas

• Qual comportamento você deseja? (a regra) — pertence ao CLAUDE.md.
• Onde você encontra a verdade atual? (a fonte) — pertence como uma URL ou caminho de arquivo buscável que Claude pode reler no momento da tarefa.

Misturar regras e fontes é como os arquivos crescem sem limites. Mantenha a regra curta, a fonte externa.

3. Audite Antes do Merge, Não Depois

As regras silenciosamente se desviam à medida que você renomeia coisas, refatora hooks ou elimina recursos. A correção não é "ser mais cuidadoso" — é uma etapa de CI. O autor construiu um aplicativo GitHub chamado agentlint (agentlint.net) que audita a superfície das regras a cada PR: contradições entre arquivos, referências a caminhos deletados, regras descrevendo recursos de harness que sua versão não suporta.

4. Delete Mais do Que Adiciona

Quase todo CLAUDE.md ganha uma nova regra por semana e deleta zero. Depois de seis meses, você tem um Frankenstein. A disciplina: para cada nova regra, encontre uma para deletar. Isso manteve o arquivo do autor abaixo de 100 linhas.

O padrão central: trate sua superfície de regras como código. Código tem testes, revisão e detecção de desvios. Regras precisam do mesmo.