O ficheiro que o Claude lê antes de tudo

O que é e porque importa

Cada sessão do Claude Code começa com o contexto vazio. O que lhe explicaste ontem no chat, hoje já não está lá. Então recomeças do zero: «então, a minha app é…». E nas vezes em que te esqueces, ele adivinha: a ferramenta, a pasta, quanto pode mudar.

É para isso que serve o CLAUDE.md. É um ficheiro de texto simples, na pasta do projeto, com as regras que queres que valham sempre. O Claude Code lê-o no início de cada sessão, antes até da tua primeira mensagem. Por isso chamo-lhe o ficheiro que o Claude lê antes de tudo.

Importa porque escreves uma só vez o que de outra forma repetirias todos os dias. Ele começa já a saber, e tu vais direto ao que queres fazer.

Uma coisa a saber já: é uma indicação, não um cadeado. O Claude lê-o e tenta segui-lo, e quanto mais claras forem as regras, mais as segue. Mas para bloquear mesmo uma coisa não chega: falo disso nas perguntas no fim.

1. O meu ficheiro, para copiar

Aqui está o meu ficheiro para copiar, numa app de exemplo: um livro de receitas. São dez linhas. Troca as partes entre < > pelas do teu projeto e tira os símbolos < >.

# <Livro de receitas>: <app de receitas>
Stack: <Next.js e TypeScript>
Código em <src/>, testes em <tests/>
Não toques no <.env> nem na <pasta dos pagamentos>
Pergunta antes de apagar ficheiros
Lê antes de mudar
Depois de cada alteração: <npm test>, e diz-me o resultado
Uma alteração de cada vez
Fala comigo em português
Escreve o código em inglês

As linhas sem < > mantenho-as iguais em todos os projetos. Aliás, as que valem em todo o lado, como a língua, passo-as para o ficheiro do meu utilizador: já lá vamos.

2. As dez linhas explicadas

Cada linha está lá porque me tirou um problema que eu tinha muitas vezes:

1. O que é a app. Acabou o «então, a minha app é…» em cada sessão nova.
2. Com o que é feita. Não te propõe ferramentas diferentes das que já usas.
3. Onde está o código e onde estão os testes. Não os procura de cada vez.
4. O que não deve tocar. As chaves e o dinheiro continuam a ser teus: as chaves secretas costumam estar no ficheiro .env, e os pagamentos são a parte onde um erro faz mais estragos. Mas é uma indicação, não um bloqueio: para o bloquear a sério é preciso uma regra deny ou um hook. Falo disso no guia GUARDIA (strikt.fit/guardia).
5. Pergunta antes de apagar. Nada de apagar coisas de surpresa.
6. Lê antes de mudar. Percebe o que lá está antes de o reescrever.
7. O comando dos testes. É o que prova que a app ainda funciona. E peço-lhe o resultado, não só que o corra.
8. Uma alteração de cada vez. Mudanças pequenas: se alguma coisa se partir, sabes onde.
9. A língua. Responde-te na tua língua.
10. O código em inglês. Nomes, funções e comentários ficam em inglês, como qualquer pessoa os lê.

São tudo coisas que não se percebem pelo código, ou que só se percebem a procurar: é precisamente isso que vale a pena escrever.

3. Onde fica

O nome é sempre CLAUDE.md. O que muda é a pasta, e a pasta decide onde vale:

• Na pasta principal do projeto: ./CLAUDE.md, ou ./.claude/CLAUDE.md. São equivalentes, escolhe um. Tem as regras desse projeto, e se o projeto estiver no git, quem trabalha nele contigo também as vê.
• No ficheiro do teu utilizador: ~/.claude/CLAUDE.md. As regras que valem para todos os teus projetos, como a língua, vão aqui. Só tu as vês.

O Claude Code lê-os no início de cada sessão, os dois: somam-se, não se substituem. Por isso não repitas no projeto o que já está no ficheiro do teu utilizador, e garante que não se contradizem: se duas linhas disserem coisas opostas, o Claude pode seguir uma ou outra.

Quando mudares um ficheiro, abre uma sessão nova: assim tens a certeza de que trabalha com a versão atualizada.

4. Como o crias e alteras

1. Abre o Claude Code na pasta do projeto e escreve /init. Ele olha para o teu código e escreve-te um primeiro CLAUDE.md, com os comandos para compilar e testar o projeto e as convenções que encontra. Se já houver um CLAUDE.md, não o substitui: propõe-te melhorias.
2. Depois acrescentas tu as regras que ele não consegue adivinhar sozinho: o que não deve tocar, como queres que trabalhe, em que língua falar contigo. São as do meu ficheiro aqui em cima.
3. Para o alterares, escreve /memory. Mostra-te os ficheiros de memória do projeto e do teu utilizador. Escolhes o ficheiro e abre-se no teu editor; se não existir, é criado.
4. Para confirmar que o carregou, numa sessão nova escreve /context e olha para a lista em Memory files. Os teus CLAUDE.md têm de lá estar: se faltar um, o Claude não o vê.

As regras novas também lhas podes pedir para escrever. Quando reparas que falta uma:

Acrescenta esta regra ao CLAUDE.md do projeto: [a regra]. Escreve-a numa linha, curta e precisa.

Conta a forma como o dizes. Com «acrescenta isto ao CLAUDE.md» vai parar ao ficheiro. Se só lhe disseres «lembra-te de que…», normalmente guarda-o na sua memória automática, que é outra coisa: explico-a nas perguntas no fim.

5. Mantém-no curto

Mantém-no curto e preciso: quanto mais claras e poucas forem as regras, mais as segue. A documentação do Claude Code recomenda ficar abaixo das 200 linhas por ficheiro: acima disso, as regras são menos seguidas.

Preciso quer dizer que se pode verificar. «Depois de cada alteração corre npm test» funciona melhor do que «testa bem o código». «O código está em src/» funciona melhor do que «mantém os ficheiros arrumados».

E depois tem de se manter vivo. Eu sigo três regras:

• Se lhe repetes a mesma coisa duas vezes, é uma linha que falta: acrescenta-a.
• Se uma linha já não é verdade, tira-a.
• Se é uma coisa que o Claude vê sozinho ao abrir o código, não é preciso escrevê-la.

Os erros mais comuns

• Deixar o ficheiro do /init como está. É uma base: acrescenta as regras que não se veem no código, como o que não tocar e em que língua falar contigo.
• Repetir em cada projeto as regras que valem em todo o lado. Põe-nas uma só vez em ~/.claude/CLAUDE.md.
• Escrever regras vagas, tipo «tem cuidado». Escreve coisas que se possam verificar: um comando, uma pasta, um ficheiro.
• Tratá-lo como um cadeado. É uma indicação: para bloquear mesmo um ficheiro precisas de uma regra deny nas permissões do Claude Code ou de um hook.
• Alterá-lo e continuar na mesma sessão a contar que ele o vê. Abre uma sessão nova e confirma com /context.

Checklist

• O CLAUDE.md está na pasta principal do projeto
• As partes entre < > já falam do meu projeto
• Está lá o comando que corre os testes
• A língua está em ~/.claude/CLAUDE.md, não em cada projeto
• Numa sessão nova, o /context mostra-o em Memory files
• É curto, sem linhas repetidas nem desatualizadas

Perguntas frequentes