Guia de campo do Claude Code em português

CLAUDE.md: o que é e como escrever um que o Claude Code segue

Toda sessão do Claude Code começa com a janela vazia. O que ele sabe do seu projeto antes do primeiro pedido vem de arquivos, e o principal deles é o CLAUDE.md que você escreve (p. 41). Abaixo, o que é, de onde cada um é lido, o que vale a pena pôr nele e um modelo para copiar.

O que é o CLAUDE.md

É um arquivo de texto em Markdown com as instruções do seu projeto: como rodar os testes, as convenções que fogem do padrão, as armadilhas. Ele entra no começo de toda conversa como contexto. O Claude lê e tenta seguir; nada o obriga (p. 42). Por isso, o que tem de acontecer sempre, como bloquear um comando, não vai no CLAUDE.md: vira uma regra deny ou um hook. Não há formato obrigatório, nem campo, nem frontmatter (p. 45). Para começar, /init lê o projeto e escreve um CLAUDE.md inicial; se ele já existe, sugere melhorias (p. 44).

De onde cada CLAUDE.md é lido (Windows)

Escopo	Onde fica	Para quê
Organização	`C:\Program Files\ClaudeCode\CLAUDE.md`	Padrões da empresa, distribuídos pela TI
Usuário	`~\.claude\CLAUDE.md`	Suas preferências, em qualquer projeto
Projeto	`.\CLAUDE.md` ou `.\.claude\CLAUDE.md`	Build, testes, convenções; vai para o git
Local	`.\CLAUDE.local.md`	Dados seus, só nesta máquina

Abra o Claude Code numa pasta e ele lê o CLAUDE.md e o CLAUDE.local.md dela e de cada pasta acima, até a raiz do disco. Os das subpastas entram só quando o Claude lê, edita ou cria um arquivo ali (p. 42). Nenhum substitui o outro: todos são somados, do mais amplo para o mais específico, e o mais perto de onde você abriu é o último a ser lido. Se dois se contradizem, não dá erro: o Claude pode seguir qualquer um, então mantenha os níveis coerentes (p. 43).

Para ver o que carregou, digite /context na sessão: a lista Memory files mostra cada CLAUDE.md lido na abertura.

O que pôr e o que deixar de fora

O CLAUDE.md entra inteiro em toda requisição, então cada linha custa. A documentação dá quatro sinais de que uma linha merece entrar: o Claude cometeu o mesmo erro pela segunda vez; uma revisão pegou algo que ele deveria saber; você digitou no chat a mesma correção da sessão passada; um colega novo precisaria da mesma informação (p. 44). A pergunta de cada linha: tirar esta linha faria o Claude errar? Se não, corte.

Entra	Fica de fora
Comandos que o Claude não adivinha	O que ele descobre lendo o código
Como rodar os testes e com qual ferramenta	Documentação longa de API: ponha o link
Decisões de arquitetura deste projeto	Informação que muda toda semana
Variáveis de ambiente exigidas, armadilhas	Conselho óbvio, como "escreva código limpo"

Seja concreto o bastante para conferir: em vez de "teste suas mudanças", escreva "rode npm test antes de commitar". Mantenha cada arquivo com menos de 200 linhas, a meta da documentação; o aviso de arquivo grande não sai nas 200 linhas, só a partir de uns 40 mil caracteres por arquivo (o limite cresce com a janela do modelo), na abertura e no /status (p. 45).

Um CLAUDE.md de projeto para copiar

CLAUDE.md, na raiz do repositório

# Comandos
- Instalar: pnpm install (não use npm: o lockfile é do pnpm)
- Testar um arquivo: pnpm vitest run caminho/do/arquivo.test.ts
- Antes de dar por pronto: pnpm tsc --noEmit
# Convenções que fogem do padrão
- Datas em UTC no banco; converter só na tela
# Armadilhas
- gerado/ é recriada pelo build: nunca editar à mão
- Os testes de integração precisam do Docker rodando

Títulos de Markdown e listas curtas, não parágrafos: seções organizadas são mais fáceis de seguir que texto corrido. Uma linha que o Claude insiste em pular pode levar ênfase ("IMPORTANTE:"), e só ela; com várias em maiúsculas, nenhuma se destaca (p. 45).

Quando o Claude não segue o CLAUDE.md

Se ele faz o que uma linha proíbe, o arquivo provavelmente está longo demais e a regra se perde no meio. Se pergunta algo que o CLAUDE.md responde, a frase está ambígua. Nos dois casos, mexa no texto e confira numa sessão nova: a conversa em que você editou já tem a resposta e esconde o defeito (p. 45). E lembre que instrução dada só no chat some no /compact; o CLAUDE.md da raiz é relido do disco (p. 48). Para revisar instruções velhas, o /doctor prompt-audit aponta caminho morto, comando inexistente e arquivos que se contradizem.