O CLAUDE.md que de fato muda o comportamento

Meus primeiros arquivos CLAUDE.md não mudaram em nada o comportamento do Claude.

O instinto que falha

Quando você abre um CLAUDE.md em branco pela primeira vez, o instinto é descrever o projeto. Stack, pastas, comandos de build, gerenciador de pacotes, deploy target.

Stack: Next.js + Postgres
Folders: src/, app/, lib/
Build: npm run build
Tests: npm test

Parece produtivo. Não é. O Claude consegue derivar quase tudo do repo com dois ls e uma leitura do package.json. O arquivo descreve o que o modelo já vê, o que significa que não muda nada no output. Você não ajustou o assistente; você escreveu um README.

Os arquivos CLAUDE.md que realmente deslocam comportamento têm três sabores de regra, e quase nenhuma descrição de projeto.

O que funciona: três tipos de regra

1. Regras negativas

Regras no formato "não faça X." Estas são estruturais porque o modo de falha padrão de qualquer assistente é excesso de ação: você pede uma correção de bug e ganha um refactor, ou pede uma função e ganha uma abstração nova.

Exemplos que compensam ao longo de uma codebase:

• "Não adicione comentários a menos que o WHY não seja óbvio."
• "Sem shims de retrocompatibilidade. Mude o código."
• "Não adicione error handling para casos que não podem acontecer — valide só nas fronteiras do sistema."
• "Pergunte antes de comandos git destrutivos."

Cada regra negativa cerca um excesso comum. O efeito cumulativo é o equivalente a um revisor de contenção, aplicado silenciosamente em cada turno.

2. Regras enraizadas em incidente

Regras que existem porque algo específico deu errado, e você não quer que aconteça de novo. Estas têm um porquê, e o porquê é o ponto todo.

• "Testes de integração devem bater num banco real, não em mocks. Razão: divergência mock/prod no Q3 escondeu uma migration quebrada."
• "Nunca delete arquivos em /migrations/ mesmo que pareçam obsoletos. Razão: suporte a rollback depende do histórico completo."
• "Use o logger existente, não console.log. Razão: output de console é descartado pelo log shipper de produção."

A razão importa tanto quanto a regra. Sem um porquê, uma regra enraizada em incidente parece arbitrária nos edge cases, e o modelo ou super-aplica ou silenciosamente pula. Com um porquê, o modelo pode exercitar julgamento quando o edge case aparece.

3. Regras de gosto com um porquê

Decisões de preferência sobre como você gosta que o trabalho seja feito — mas nunca preferências secas. Toda regra de gosto precisa da razão.

• "Prefira um PR único para refactors nesta área. Razão: revisores pediram."
• "Default para descrições de PR curtas. Razão: as longas não são lidas."
• "Evite abstrações prematuras. Três linhas parecidas é melhor que um helper usado uma vez."

O padrão regra-de-gosto + razão é a diferença entre um assistente que espelha seu estilo e um que volta aos defaults do training data no momento em que seu prompt fica curto.

O teste do cheiro

Para cada linha do seu CLAUDE.md, pergunte:

Se eu removesse essa linha, o output do Claude seria mensuravelmente pior?

Se a resposta for não, a linha é decoração. Decoração é cara — consome sua janela de contexto a cada turno, e dilui o sinal das linhas que importam. Corte.

Linhas que passam no teste do cheiro são quase sempre um dos três tipos acima. Linhas que falham são quase sempre descrição de projeto.

A regra que você deveria remover

Uma prática contraintuitiva: a cada poucas semanas, olhe seu CLAUDE.md e ache a uma regra que deu contraproducente. Talvez seja muito rígida e o modelo começou a fazer coisas erradas para obedecer. Talvez seja muito vaga e o modelo interpretou diferente do que você quis dizer. Talvez a codebase tenha mudado e a regra não se aplique mais.

Corte.

Um CLAUDE.md que só cresce é um CLAUDE.md que acumulou regras mortas — e regras mortas são piores que regra nenhuma, porque o modelo as trata com o mesmo peso das vivas. A disciplina de remover uma regra obsoleta por revisão mantém o sinal do arquivo alto.

Por que isso importa mais do que você imagina

CLAUDE.md é um dos 30 minutos de maior alavancagem que você vai gastar em ferramentas de IA. Diferente de prompts — que aplicam uma vez e são esquecidos — CLAUDE.md aplica a cada turno, em cada conversa, até você mudar. Uma boa regra te paga de volta centenas de vezes. Uma má regra te leva ao erro centenas de vezes.

O formato do arquivo importa menos que o conteúdo. Markdown, texto puro, bullets, prosa — Claude lida com todos. O que importa é se o arquivo restringe ou descreve. Descrever é confortável e inútil. Restringir é desconfortável e é o ponto inteiro.

A regra

Se uma linha do CLAUDE.md não muda o que é escrito, ela não pertence ali. Regras negativas, regras enraizadas em incidente com um porquê, regras de gosto com um porquê — essas conquistam seu lugar. Descrição de projeto não.

O modelo consegue ler sua codebase. Ele não consegue ler seus incidentes.