O CLAUDE.md global e o de projeto respondem a perguntas diferentes

Quem começa a usar Claude Code faz o que eu fiz: abre um arquivo chamado CLAUDE.md e coloca ali tudo que quer que o agente lembre sempre. Esse arquivo é o texto que o agente lê no início de toda sessão para saber como se comportar. Regra de git, regra de segurança, a porta do servidor local, o jeito de escrever commit. Tudo junto, sem separar o que é regra geral do que é regra daquele projeto. E funciona. O agente lê, segue, pronto.

Funciona no primeiro projeto. Funciona no segundo e no terceiro, porque copiar o arquivo do anterior é um copiar e colar. Hoje eu tenho 28 projetos, cada um com o seu CLAUDE.md. Se as regras que valem para todos eles morassem dentro de cada um, uma mudança numa regra de git seria 28 edições à mão, uma por repositório. E a regra de segurança que eu escrevesse num projeto só não protegeria nada nos outros 27.

Existem dois arquivos porque existem duas perguntas, e a decisão de onde cada regra mora tem preço nos dois sentidos.

Cada arquivo responde a uma pergunta diferente

O CLAUDE.md global mora em ~/.claude/CLAUDE.md e responde a "isso vale para todo projeto?". Ali ficam as regras que não mudam de repositório para repositório: segurança, convenção de git, padrão de escrita, padrões de código, como e quando usar hooks e skills. O agente lê esse arquivo em qualquer pasta que eu abrir.

O CLAUDE.md de projeto mora na raiz do repositório e responde a "isso é deste projeto?". Ali fica a identidade: nome do projeto, stack técnica, porta do servidor local, regras que só fazem sentido naquele domínio. Um site não precisa das regras de um bot, e o bot não precisa das regras do site.

Errar nos dois sentidos custa. Uma regra de segurança escrita só no arquivo de um projeto não existe nos outros 27; o agente vai quebrar a regra em qualquer pasta que não seja aquela. E uma regra de stack de um projeto só, colocada no arquivo global, vira ruído em todo projeto que não usa aquela stack. O agente carrega instrução sobre a interface de um site numa sessão que só mexe em banco de dados.

Regra duplicada envelhece em 28 lugares ao mesmo tempo

O problema de copiar não é o trabalho de copiar. É o que acontece depois, quando a regra muda. Regra que vale para todos os projetos muda com alguma frequência: eu aperto uma convenção de commit, proíbo um comando, mudo o formato de um documento. Se ela estiver duplicada, cada CLAUDE.md de projeto guarda a versão do dia em que foi copiada, e só a versão daquele dia.

O resultado é uma coleção de projetos com regras defasadas ou contraditórias entre si. Nenhum deles está errado por dentro; cada um está congelado numa versão diferente. Com a regra centralizada no global, a mudança é uma edição só, e os 28 projetos passam a segui-la na próxima sessão.

Procedimento não é comportamento

Separar global de projeto resolve a duplicação. Não resolve o peso. O arquivo global é carregado inteiro em toda sessão nova, em qualquer projeto, e cada token dentro dele é pago em toda sessão, inclusive nas que nunca vão precisar daquele trecho. O meu global foi acumulando passo a passo: os passos para reconstruir um container Docker, por exemplo, que só interessam à sessão que está mexendo em Docker. Numa tarde escrevendo texto, o agente carregava tudo aquilo do mesmo jeito.

Nada ali estava errado. Estava presente demais.

Quando medi, o CLAUDE.md global tinha inchado até 5.318 tokens, boa parte era procedimento. Tirei os procedimentos de lá e transformei em 7 skills, pacotes de instruções que o Claude Code carrega sob demanda, só quando são chamados. No arquivo global ficou um ponteiro de uma linha por skill. O peso residente caiu para 2.803 tokens. A regra que ficou desse exercício: um procedimento executável e pouco frequente merece virar skill justamente para sair do contexto padrão; enquanto ninguém chama, ele não custa nada.

settings.json muda na hora; CLAUDE.md espera a próxima sessão

Tem um terceiro arquivo nessa conversa, e ele se comporta diferente. O settings.json, que guarda entre outras coisas a lista de permissões do agente, é relido pela sessão em andamento poucos segundos depois de salvo. Você edita, e a permissão nova já vale.

O CLAUDE.md não faz isso. Ele vive dentro do cache de prompt da sessão aberta: é lido uma vez, no começo, e fica fixado enquanto a sessão durar. A regra nova só entra em vigor numa sessão nova ou depois de um /clear. Recomendo tratar toda edição no CLAUDE.md como algo que só vale na próxima sessão, e o custo de não saber disso é concreto. Você muda a regra, o agente continua ignorando, e você perde tempo tentando entender por que "a regra nova não pega". O que faltava era abrir uma sessão nova.

Faça duas perguntas antes de escrever qualquer regra

Antes de escrever uma regra nova, eu faço duas perguntas. A primeira: isso vale para todo projeto, ou só para este aqui? Todo projeto vai para o global; só este vai para o de projeto. A segunda, quando a resposta é "todo projeto": isso é uma regra de comportamento, ou um passo a passo que só roda de vez em quando? Comportamento fica no arquivo; passo a passo raro vira skill, e não fica solto em arquivo nenhum.

Se um único CLAUDE.md por projeto, sem camada global, aguentasse o crescimento sem duplicar regra e sem deixar regra defasada para trás, a separação não se justificaria. Com 28 projetos, não foi isso que aconteceu comigo.