O arquivo CLAUDE.md, ou como explicar seu projeto para o Claude Code

Depois da primeira conversa com o Claude Code, a segunda traz uma surpresa: ele não lembra de nada. Toda sessão começa com a memória vazia. Ele não sabe como rodar os testes do seu projeto, não sabe que você usa quatro espaços e não tabs, não sabe que ninguém deve mexer naquela pasta. Ele vai chutar, e de vez em quando vai chutar errado.

O CLAUDE.md resolve isso. É um arquivo de texto em Markdown que o Claude lê no início de toda sessão. Você escreve ali o que, de outro jeito, teria que repetir. É a diferença entre uma semana boa e uma semana ruim com a ferramenta, e é um arquivo só.

Onde ele fica

Tem três lugares que importam, do mais geral para o mais específico:

• ~/.claude/CLAUDE.md: suas preferências pessoais, para todos os projetos. O estilo de código de que você gosta, como quer que ele fale com você, as ferramentas que você usa.
• CLAUDE.md na raiz do projeto (ou em .claude/CLAUDE.md): as regras daquele projeto. Ele vai para o git, então a equipe toda compartilha.
• CLAUDE.local.md na raiz do projeto: suas anotações pessoais só para aquele projeto. Não vai para o git; adicione ao .gitignore.

Os três são lidos e somados, nessa ordem; um não substitui o outro. O que está mais perto de onde você abriu o Claude é lido por último. O Claude também lê os CLAUDE.md das pastas acima daquela em que você o abriu. Se o projeto tiver subpastas com um CLAUDE.md próprio, esses só entram quando o Claude mexe em arquivos dessas pastas. Em uma empresa, pode existir ainda um arquivo gerenciado pela organização, que vale para todo mundo e não pode ser desligado.

Para confirmar que o arquivo foi carregado, digite /context em uma sessão e procure por ele na lista "Memory files". Se não aparecer ali, o Claude não está vendo o arquivo.

Comece com /init

Você não precisa escrever o arquivo do zero. Dentro de uma sessão, digite:

> /init

O Claude analisa o projeto e cria um CLAUDE.md com os comandos de build e de testes que encontrar, e as convenções que conseguir deduzir. Se o arquivo já existir, ele sugere melhorias em vez de sobrescrever. Daí em diante, a sua parte é acrescentar o que ele não consegue descobrir sozinho: as regras da casa.

O que colocar

Uma pergunta decide cada linha: se eu tirar isto, o Claude vai errar? Se a resposta for não, corte.

Vale a pena colocar:

• Comandos que ele não adivinha: como rodar a aplicação localmente, como rodar os testes, como fazer o deploy.
• Regras de estilo que fogem do padrão da linguagem. "Quatro espaços" só se o seu projeto for diferente do que a ferramenta faria por padrão.
• Decisões de arquitetura próprias do projeto. Por que não tem framework, por que a configuração fica fora da raiz pública.
• Etiqueta do repositório: nome das branches, idioma dos commits, se ele faz commit sozinho ou espera.
• Armadilhas conhecidas: aquela variável de ambiente sem a qual nada sobe, aquela pasta que parece lixo e não é.

Não vale a pena colocar:

• O que ele descobre lendo o código: a estrutura de pastas, a lista de dependências, o que cada arquivo faz.
• Convenções normais da linguagem. Ele já conhece.
• Documentação extensa de APIs. Coloque um link.
• Coisas que mudam toda semana.
• Frases vazias como "escreva código limpo".

Como escrever

Três regras, todas da documentação oficial e todas confirmadas por quem já se deu mal:

1. Curto. Menos de 200 linhas. Um arquivo comprido gasta contexto em toda sessão e, pior, as regras importantes se perdem no meio das outras. Se o Claude ignora uma regra que está escrita ali, o arquivo provavelmente está grande demais.
2. Concreto. Escreva o que dá para verificar. "Rode php vendor/bin/phpunit antes de cada commit" funciona; "teste as alterações" não. "Os handlers ficam em src/api/handlers/" funciona; "mantenha os arquivos organizados" não.
3. Sem contradições. Se duas regras se contradizem, ele escolhe uma meio ao acaso. De tempos em tempos, leia o arquivo de cima a baixo e apague o que não vale mais.

Use títulos e listas. O Claude lê a estrutura como uma pessoa lê: seções claras são mais fáceis de seguir do que parágrafos densos. Se quiser deixar um recado para quem mantém o arquivo, use um comentário HTML (<!-- assim -->): ele é removido antes de o texto chegar ao Claude e não gasta contexto. Se tiver uma regra que ele insiste em pular, coloque "IMPORTANTE" nessa linha, e só nela. Se colocar em muitas, nenhuma se destaca.

Um exemplo completo

Um site pequeno em PHP, sem framework, feito por uma pessoa só. O CLAUDE.md na raiz do projeto poderia ser este:

# Loja (PHP 8.4, sem framework)

## Comandos
- Servidor local: `php -S localhost:8080 -t www`
- Testes: `php vendor/bin/phpunit` (rodar antes de cada commit)
- Verificar a sintaxe de um arquivo alterado: `php -l arquivo.php`

## Regras
- PHP puro. Nenhuma dependência nova sem perguntar antes.
- Todo SQL com prepared statements. Nunca concatenar variáveis na query.
- `config/app.php` existe só no servidor: não vai para o git nem para pacotes.
- Tema escuro e claro, os dois obrigatórios. As cores são variáveis CSS.

## Git
- Branches: feature/<nome-curto>. Commits em português, uma alteração por commit.
- Não fazer commit sem eu pedir.

## Quando alterar algo
- Sempre subir a versão em `config/app.php`: x.x.1 correções, x.1.0 melhorias, x+1.0.0 funcionalidades novas.
- Explicar o porquê, não só o quê.

Umas vinte linhas. Repare no que não está ali: não diz que www/ é a raiz pública nem lista os arquivos, porque isso ele vê. Cada linha é algo que ele faria errado sem ela.

Quando acrescentar

O arquivo cresce com o uso, não de uma vez. A documentação dá quatro sinais de que é hora de acrescentar uma linha:

• O Claude cometeu o mesmo erro pela segunda vez.
• Uma revisão de código pegou algo que ele deveria saber sobre o projeto.
• Você digitou no chat a mesma correção que já tinha digitado na sessão anterior.
• Uma pessoa nova na equipe precisaria da mesma informação para começar a trabalhar.

Você não precisa abrir o editor. Diga "adiciona isso ao CLAUDE.md" e ele adiciona. Para abrir os arquivos na mão, /memory lista todos e abre o que você escolher.

Importar outros arquivos

Um CLAUDE.md pode puxar outros arquivos com @caminho, por exemplo @README ou @docs/git.md. O conteúdo entra no contexto na inicialização, como se estivesse escrito ali. Isso serve para organizar, não para economizar: os arquivos importados contam do mesmo jeito para o tamanho. Para mencionar um caminho sem importar, coloque entre crases.

Se você já usa o AGENTS.md

Outras ferramentas de programação com IA leem um arquivo chamado AGENTS.md. O Claude Code não lê. Para não manter duas cópias, crie um CLAUDE.md que importa esse arquivo e acrescente embaixo o que for só para o Claude:

@AGENTS.md

## Claude Code
- Usar o modo de plano para alterações em `src/pagamentos/`.

E a memória automática?

Existe um segundo mecanismo. Não é o assunto deste guia, mas é bom saber que ele existe. Além do que você escreve no CLAUDE.md, o Claude faz anotações para si mesmo: as correções que você deu, suas preferências, o contexto que ele não consegue tirar do código. Elas ficam em ~/.claude/projects/<projeto>/memory/. O índice, MEMORY.md, é carregado em toda sessão (as primeiras 200 linhas ou 25 KB, o que vier primeiro); as anotações detalhadas só são lidas quando fazem falta. Vem ligada por padrão, e /memory mostra o que ele guardou e deixa você apagar o que quiser. Uma regra prática: regra do projeto vai para o CLAUDE.md; hábito seu, ele aprende sozinho.

Problemas comuns

• Ele não está seguindo o que eu escrevi. Primeiro rode /context para ver se o arquivo foi carregado. Depois veja se a regra é vaga ou se contradiz outra. O CLAUDE.md é contexto, não lei: o Claude lê e tenta cumprir, mas não há garantia. Para algo que precisa acontecer sempre, sem exceção (um lint depois de cada edição, por exemplo), a ferramenta certa é um hook, não uma linha no CLAUDE.md.
• O arquivo ficou enorme. Corte o que ele descobre sozinho. O comando /doctor sugere cortes em um CLAUDE.md que esteja no git.
• Ele perdeu as regras depois de um /compact. O CLAUDE.md da raiz do projeto sobrevive à compactação; o que se perde é o que você só disse na conversa. Se era importante, passe para o arquivo.

Fontes

• How Claude remembers your project, documentação oficial, consultada em 16 de setembro de 2026: locais, ordem de carregamento, limite de 200 linhas, /init, /context, /memory, importações, AGENTS.md, memória automática.
• Best practices for Claude Code, seção "Write an effective CLAUDE.md": o que incluir e o que deixar de fora, e o alerta sobre arquivos longos.