CLAUDE.md

O CLAUDE.md é um arquivo de texto que o Claude Code lê sozinho no início de toda sessão. O que está escrito nele vale para a conversa inteira, sem você repetir nada.

Ele existe em quatro lugares, carregados do mais amplo para o mais específico:

Onde	Caminho	Para que
Política gerenciada	definido pela TI da empresa	regras da organização
Usuário	~/.claude/CLAUDE.md	suas preferências, em todos os projetos
Projeto	./CLAUDE.md ou ./.claude/CLAUDE.md	o que vale para quem trabalha nesse repositório
Local	./CLAUDE.local.md	suas preferências só naquele projeto, fora do git

Os arquivos não se sobrescrevem: eles são concatenados. O do projeto aparece no contexto depois do seu, então instrução mais próxima de onde você abriu o Claude é lida por último. O Claude Code também sobe a árvore de diretórios e carrega os CLAUDE.md das pastas acima da sua.

O que entra: o que você teria que explicar de novo. Comandos de build, convenções, arquitetura, “sempre faça X”. O sinal mais confiável é este — o Claude errou a mesma coisa uma segunda vez, ou você digitou a mesma correção que já tinha digitado na sessão passada.

O que não entra:

• Instrução de uma tarefa só. Isso é conversa.
• Procedimento de vários passos que só importa de vez em quando. Isso é skill, que carrega sob demanda.
• Regra que só vale para um pedaço do código. Isso é regra com escopo de caminho, em .claude/rules/.

Tamanho importa, e o alvo é abaixo de 200 linhas por arquivo. O CLAUDE.md entra no contexto antes da sua primeira palavra e é cobrado em toda mensagem. Arquivo grande consome mais e é seguido pior — os dois efeitos ao mesmo tempo.

E saiba o limite do mecanismo: CLAUDE.md é contexto, não configuração aplicada. Ele é entregue ao Claude como mensagem, não como regra de sistema. Instrução específica e verificável (“use indentação de 2 espaços”) é seguida muito melhor que instrução vaga (“formate direito”). Se algo precisa acontecer sempre, sem depender da decisão do modelo, isso é hook ou regra de permissão — não uma frase no arquivo.