CLAUDE.md: o que é, onde fica e o que escrever nele?

O que é o CLAUDE.md, e por que ele existe?

Quem usa um agente de código por algumas semanas descobre que digita as mesmas frases. Usa pnpm, não npm. O teste fica ao lado do arquivo, não numa pasta separada. Não mexe na pasta de migrações sem falar comigo. Se você repete a mesma frase em toda sessão, ela não pertence à conversa. Ela está no lugar errado, e o lugar certo é o CLAUDE.md.

O arquivo entra no contexto antes do seu pedido e antes do histórico da conversa, e fica lá até a sessão acabar. É a única camada do contexto que você escreve de antemão. Isso o torna forte, porque ele orienta tudo o que vem depois, e caro, porque cada linha ocupa espaço em todas as respostas da sessão. É por isso que o curso o chama de constituição do projeto: poucas regras, que valem sempre, e que ninguém muda sem motivo.

Calibre a expectativa: segundo a documentação oficial, o CLAUDE.md é contexto, não configuração imposta. O Claude tenta seguir, sem garantia, principalmente com instrução vaga ou contraditória. O que precisa acontecer sempre, como bloquear um comando, vai em permissões ou num hook, que o programa executa independentemente do que o modelo decidir.

Onde fica o CLAUDE.md?

Existem vários lugares, e cada um tem um alcance. Os que você vai usar no dia a dia são estes:

Há ainda um nível de organização, a política gerenciada, que a equipe de TI instala na máquina e ninguém desliga individualmente. Se você trabalha sozinho, pode ignorar.

Os arquivos se somam, em vez de um substituir o outro. O Claude Code carrega o CLAUDE.md da pasta onde você abriu a sessão e o de cada pasta acima dela, do mais geral para o mais próximo. Se duas regras se contradizem, a documentação avisa que o Claude pode seguir qualquer uma das duas. Então não conte com um nível “ganhando” do outro: resolva a contradição no texto.

O nível de subpasta é o mais subestimado. Ele resolve um caso muito comum: o pedaço legado do projeto que segue outra convenção e que você não vai reescrever agora. A separação que importa é uma só: o que é do projeto vai no repositório, e o que é seu fica na sua máquina.

Para conferir quais arquivos entraram na sessão atual, rode /context e veja a lista em Memory files. Para abrir e editar, use /memory.

Como funcionam as importações com @ e o AGENTS.md?

Um CLAUDE.md pode puxar outros arquivos com @caminho, por exemplo @docs/git.md. O caminho é relativo ao arquivo que faz a importação, e um arquivo importado pode importar outro, até quatro saltos. Se o caminho estiver entre crases, ele vira texto e não é importado. Quando um arquivo do projeto importa algo de fora da pasta de trabalho, o Claude Code pede aprovação na primeira vez.

Importar organiza, mas não economiza: o arquivo importado entra no contexto no começo da sessão, igual ao resto. Não é um jeito de ter um CLAUDE.md grande de graça.

Se o repositório já tem um AGENTS.md para outros agentes, saiba que o Claude Code lê o CLAUDE.md, não o AGENTS.md. A saída recomendada é um CLAUDE.md com a linha @AGENTS.md no topo e, abaixo, o que for específico do Claude. Assim as duas ferramentas leem as mesmas regras sem duplicar texto.

O que colocar no CLAUDE.md?

O critério cabe numa pergunta, feita linha por linha: que comportamento isto muda? Se a resposta não vem, a linha não entra. Passam no teste:

• Os comandos de teste, lint e build, incluindo como rodar um teste só. Evita a meia hora dele tentando adivinhar o seu.
• Convenção que o código não deixa óbvia. Onde fica o teste, como um erro de domínio sobe, em que unidade um valor é guardado.
• O que não se toca sem avisar. Migrações, arquivos editados à mão por outra equipe, a pasta de legado.
• Decisão que parece errada e é de propósito. “Nada de ORM na pasta de relatórios: SQL à mão, por desempenho” muda a solução e evita um refator inteiro na direção errada.
• Onde coisa nova vai. Componente novo, rota nova, script novo.

Tem um segundo filtro, que quase ninguém aplica: de onde veio cada linha. Uma regra que você confirmou lendo o código, perguntando para quem sabe ou decidindo no escopo da tarefa tem origem. Uma linha sem origem é palpite, e palpite escrito com autoridade vira a regra que o agente segue sem questionar.

O que não colocar no CLAUDE.md?

Esta é a lista que exige coragem, porque vários itens soam responsáveis:

• O que o código já diz sozinho. Ele lê o código melhor do que lê a sua prosa sobre o código.
• Descrição do produto. “Este é um e-commerce em Node” é verdade e não muda nada: ele descobre isso no primeiro arquivo.
• Lista de pastas. Um comando produz isso melhor, e sempre atualizado.
• Boa prática genérica. “Escreva código limpo e testável” não muda decisão nenhuma.
• Qualquer coisa copiada de outro projeto sem conferir se vale neste.

Procedimento de vários passos, ou regra que só importa numa parte do código, também sai. A documentação sugere uma skill ou uma regra em .claude/rules/ restrita àqueles caminhos, que só carregam quando fazem sentido.

Como fica um CLAUDE.md pronto para copiar?

Um primeiro arquivo cabe em pouco mais de dez linhas e já paga no mesmo dia. Troque os comandos e as pastas pelos do seu projeto:

# Comandos
- Testes: npm test (um arquivo só: npm test -- caminho/do/arquivo)
- Lint: npm run lint -- --fix
- Build: npm run build

# Convenções que o código não mostra
- Dinheiro é inteiro em centavos, nunca float.
- Texto que o usuário vê fica em src/i18n, nunca direto no componente.
- Componente novo vai em src/components, um por arquivo.

# Não mexa sem perguntar
- infra/: configuração de produção, só com aprovação humana.
- src/antigo/: em manutenção, mudança mínima.

# De propósito
- O cache fica desligado em desenvolvimento. Não reative.

Repare no que não tem aí: nenhuma frase sobre o que o produto é, nenhuma boa prática genérica, nenhuma árvore de pastas. Se preferir não começar do zero, o comando /init analisa o projeto e gera um arquivo inicial. Trate o resultado como rascunho e corte o que o código já diz.

Como manter o arquivo vivo?

O CLAUDE.md estraga, e o sintoma é silencioso. A parte contraintuitiva: regra velha é pior que regra nenhuma. Sem a regra, ele lê o código e acerta, porque o código é a verdade. Com a regra velha, ele obedece você e erra com confiança, e a culpa parece dele.

Dois hábitos resolvem. Quando um pull request contrariar uma regra, apague a regra no mesmo commit. E, de vez em quando, peça ao próprio agente: aponte o que neste arquivo não bate mais com o código. Ele é bom nisso.

A armadilha mais comum nasce bem-intencionada: o arquivo de duzentas linhas que descreve o projeto ao agente. Tudo aquilo compete por atenção com o seu pedido e dilui as poucas linhas que mudavam comportamento. A documentação oficial recomenda ficar abaixo de 200 linhas por arquivo, porque arquivo longo reduz a aderência. Na prática, comece com dez. Acrescente uma sempre que se pegar repetindo uma frase, e apague uma sempre que o código contrariar.

Os comandos que ajudam nessa manutenção estão no guia de comandos do Claude Code. E a regra da casa que você escreve aqui é a mesma que você vai cobrar depois, ao revisar código gerado por IA.

Continue lendo

• Comandos do Claude Code: quais usar e em que momento?Os comandos de barra e atalhos do Claude Code organizados pelo momento de uso: começar, contexto, modelo e esforço, retomar e custo. Atualizado em 2026.
• Como revisar código gerado por IA, e por que não é a revisão de sempre?Código gerado por IA erra sem deixar rastro. Para onde olhar primeiro, em que ordem ler o diff e os sete defeitos que a IA produz com mais frequência.
• Claude Code para iniciantes: como sair do terminal vazio para a primeira sessão?O que é o Claude Code, o mínimo de terminal para começar, onde abrir a primeira sessão e o que pedir primeiro. Para quem nunca abriu um terminal.