O ficheiro CLAUDE.md, ou como dizer ao Claude Code o que é o teu projeto

Se já fizeste a primeira conversa com o Claude Code, a segunda vai trazer uma surpresa: ele não se lembra de nada. Cada sessão começa com a memória vazia. Não sabe como se correm os testes do teu projeto, não sabe que usas quatro espaços e não tabs, não sabe que aquela pasta não se toca. Vai adivinhar, e vai adivinhar mal de vez em quando.

O CLAUDE.md resolve isto. É um ficheiro de texto, em Markdown, que o Claude lê no início de todas as sessões. Tu escreves lá o que de outra forma terias de repetir. É a diferença entre uma semana boa e uma semana má com a ferramenta, e é um ficheiro só.

Onde fica

Há três sítios que te interessam, do mais geral para o mais específico:

• ~/.claude/CLAUDE.md: as tuas preferências pessoais, para todos os projetos. Estilo de código de que gostas, como queres que te fale, ferramentas que usas.
• CLAUDE.md na raiz do projeto (ou em .claude/CLAUDE.md): as regras desse projeto. Vai para o git, por isso toda a equipa o partilha.
• CLAUDE.local.md na raiz do projeto: as tuas notas pessoais só para esse projeto. Não vai para o git; acrescenta-o ao .gitignore.

Os três são lidos e juntos, por esta ordem, não se substituem uns aos outros. O que está mais perto de onde abriste o Claude é lido em último lugar. O Claude também lê os CLAUDE.md das pastas acima daquela onde o abriste. Se o projeto tiver subpastas com o seu próprio CLAUDE.md, esses só entram quando o Claude mexe em ficheiros dessas pastas. Numa empresa pode ainda existir um ficheiro gerido pela organização, que se aplica a todos e não se desliga.

Para confirmar que o ficheiro foi carregado, escreve /context numa sessão e procura-o na lista "Memory files". Se não aparecer lá, o Claude não o vê.

Começa com /init

Não precisas de escrever o ficheiro do nada. Dentro de uma sessão, escreve:

> /init

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

O que pôr lá

A pergunta que decide cada linha é esta: se eu tirar isto, o Claude vai fazer asneira? Se a resposta for não, corta.

Vale a pena pôr:

• Comandos que ele não adivinha: como se corre a aplicação em local, como se correm os testes, como se faz o deploy.
• Regras de estilo que fogem ao normal da linguagem. "Quatro espaços" só se o teu projeto for diferente do que a ferramenta faria por defeito.
• Decisões de arquitetura próprias do projeto. Porque é que não há framework, porque é que a configuração vive fora da raiz pública.
• Etiqueta do repositório: nome dos ramos, língua dos commits, se faz commit sozinho ou espera.
• Armadilhas conhecidas: aquela variável de ambiente sem a qual nada arranca, aquela pasta que parece lixo e não é.

Não vale a pena pôr:

• O que ele descobre a ler o código: a estrutura das pastas, a lista de dependências, o que faz cada ficheiro.
• Convenções normais da linguagem. Ele já as sabe.
• Documentação extensa de APIs. Põe um link.
• Coisas que mudam todas as semanas.
• Frases vazias como "escreve código limpo".

Como escrever

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

1. Curto. Menos de 200 linhas. Um ficheiro comprido gasta contexto em todas as sessões e, pior, as regras importantes perdem-se no meio das outras. Se o Claude ignora uma regra que está lá escrita, o ficheiro é provavelmente grande de mais.
2. Concreto. Escreve o que se pode verificar. "Corre php vendor/bin/phpunit antes de cada commit" funciona; "testa as alterações" não. "Os handlers ficam em src/api/handlers/" funciona; "mantém os ficheiros organizados" não.
3. Sem contradições. Se duas regras se contradizem, ele escolhe uma ao calhas. De vez em quando lê o ficheiro de cima a baixo e apaga o que já não é verdade.

Usa títulos e listas. O Claude lê a estrutura como um humano lê: secções claras seguem-se melhor do que parágrafos densos. Se quiseres deixar uma nota para as pessoas que mantêm o ficheiro, usa um comentário HTML (<!-- assim -->): é retirado antes de o texto chegar ao Claude e não gasta contexto. Se houver uma regra que ele insiste em saltar, põe "IMPORTANTE" nessa linha, e só nessa. Se puseres em muitas, nenhuma se destaca.

Um exemplo completo

Um sítio pequeno em PHP, sem frameworks, feito por uma pessoa. O CLAUDE.md na raiz do projeto podia ser este:

# Loja (PHP 8.4, sem frameworks)

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

## Regras
- PHP puro. Nenhuma dependência nova sem perguntar primeiro.
- Toda a 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, ambos obrigatórios. As cores são variáveis CSS.

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

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

Vinte e poucas linhas. Repara no que não está lá: não diz que www/ é a raiz pública nem lista os ficheiros, porque isso ele vê. Cada linha é uma coisa que ele faria mal sem ela.

Quando acrescentar

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

• O Claude cometeu o mesmo erro pela segunda vez.
• Uma revisão apanhou algo que ele devia ter sabido sobre este projeto.
• Escreveste no chat a mesma correção que já tinhas escrito na sessão anterior.
• Um colega novo precisaria da mesma informação para ser produtivo.

Não precisas de abrir o editor. Diz-lhe "acrescenta isto ao CLAUDE.md" e ele acrescenta. Para abrir os ficheiros à mão, /memory lista-os todos e abre o que escolheres.

Importar outros ficheiros

Um CLAUDE.md pode puxar outros ficheiros com @caminho. Por exemplo, @README ou @docs/git.md. O conteúdo entra no contexto no arranque, tal como se estivesse escrito ali. Serve para organizar, não para poupar: os ficheiros importados contam na mesma para o tamanho. Para mencionar um caminho sem o importar, mete-o entre acentos graves.

Se já usas o AGENTS.md

Outras ferramentas de programação com IA leem um ficheiro chamado AGENTS.md. O Claude Code não o lê. Para não manteres dois ficheiros iguais, cria um CLAUDE.md que o importa, e acrescenta por baixo o que for só para o Claude:

@AGENTS.md

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

E a memória automática?

Há um segundo mecanismo, que não é o tema deste guia mas convém saber que existe. Além do que tu escreves no CLAUDE.md, o Claude escreve notas para si próprio: as correções que lhe deste, as tuas preferências, o contexto que não consegue tirar do código. Ficam em ~/.claude/projects/<projeto>/memory/. O índice, MEMORY.md, carrega em todas as sessões (as primeiras 200 linhas ou 25 KB, o que chegar primeiro); as notas detalhadas só são lidas quando fazem falta. Está ligada por defeito; /memory mostra o que ele guardou e deixa-te apagar o que quiseres. Uma regra prática: o que é regra do projeto vai para o CLAUDE.md; o que é hábito teu, ele aprende sozinho.

Erros comuns

• Não está a seguir o que escrevi. Primeiro /context, para ver se o ficheiro carregou. Depois vê 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 tem de 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.
• Ficou enorme. Corta o que ele descobre sozinho. O comando /doctor propõe cortes num CLAUDE.md que esteja no git.
• Perdeu as regras depois de um /compact. O CLAUDE.md da raiz sobrevive à compactação; o que se perde é o que só disseste na conversa. Se era importante, passa-o para o ficheiro.

Fontes

• How Claude remembers your project, documentação oficial, lida a 5 de setembro de 2026 e de novo a 16 de setembro de 2026. Localizações, ordem de carregamento, limite de 200 linhas, /init, /context, /memory, importações, memória automática.
• Best practices for Claude Code, secção "Write an effective CLAUDE.md", lida na mesma data. O que incluir e o que excluir, a pergunta "se tirar isto, ele erra?", o aviso sobre ficheiros compridos.