CLAUDE.md
Sem procedimento testado nesta página.
O que é
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.
Relacionado
Você pode estar procurando isso se
- toda vez tenho que explicar o projeto de novo
- ele esquece o que eu falei na conversa passada
- ele repete o mesmo erro que eu já corrigi três vezes
- queria ensinar uma vez e valer pra sempre
- escrevi lá e mesmo assim ele ignora