CLAUDE.md explicado: ensine o seu projeto ao Claude Code uma vez só

Toda sessão nova do Claude Code começa com a cabeça vazia. Você diz que é para usar pnpm, não npm. Diz onde ficam os testes. Diz para não mexer na pasta gerada. Amanhã você diz tudo isso de novo.

É um arquivo de texto simples, em Markdown. O Claude Code o lê no início de cada sessão, então tudo o que está nele já é conhecido antes do seu primeiro prompt. Este guia mostra onde o arquivo fica, como escrever um que o Claude siga e o que deixar de fora.

O que o CLAUDE.md é, e o que ele não é

Cada sessão do Claude Code começa com uma janela de contexto nova. Dois mecanismos levam conhecimento de uma sessão para a seguinte:

Os dois são carregados como contexto. Essa palavra importa: o Claude lê o CLAUDE.md e tenta segui-lo, mas ele não é uma configuração imposta. Uma linha vaga ou contraditória pode ser ignorada. Voltamos a isso na parte de solução de problemas, porque é isso que define como o arquivo deve ser escrito.

Onde o arquivo fica

São quatro lugares, e eles se somam. O Claude os carrega do escopo mais amplo ao mais específico, então o que está mais perto do seu projeto é lido por último.

Os dois que você vai usar são o arquivo do projeto e o do usuário.

• Arquivo do projeto. Coloque o CLAUDE.md na raiz do projeto, ou numa pasta .claude na raiz. Faça o commit, para que todos que trabalham no projeto recebam as mesmas instruções. Escreva o que vale para qualquer pessoa: comandos de build, convenções, estrutura do projeto.
• Arquivo do usuário. O ~/.claude/CLAUDE.md acompanha você em todos os projetos. Use-o para hábitos pessoais, como o jeito que você prefere que as explicações sejam escritas.
• Arquivo local. O CLAUDE.local.md serve para anotações suas e específicas de um projeto, como a URL de um ambiente de testes. Adicione-o ao .gitignore para que não entre no commit.

O Claude também procura na pasta em que você o abriu e em todas as pastas acima dela. Se você começa em foo/bar/, ele carrega foo/bar/CLAUDE.md e foo/CLAUDE.md. Os arquivos de pastas abaixo de você são carregados depois, sob demanda, na primeira vez que o Claude lê ou edita um arquivo naquela subpasta.

Comece com o /init

Você não precisa escrever a primeira versão à mão. Dentro de uma sessão, rode:

> /initAnalisando seu código...CLAUDE.md criado com os comandos de build, as instruções de teste e as convenções encontradas.

O Claude Code lê o seu projeto e escreve um CLAUDE.md com os comandos de build e de teste e as convenções que descobre. Se já existir um CLAUDE.md, o /init sugere melhorias em vez de sobrescrevê-lo. Trate o resultado como um primeiro rascunho. Seu trabalho é acrescentar o que o Claude não teria como descobrir sozinho.

Para confirmar que o arquivo foi carregado, rode /context numa sessão e olhe em Memory files.

O que deve entrar no arquivo

Um bom teste, antes de escrever qualquer linha, tem duas perguntas:

Se as duas respostas forem sim, deixe a linha de fora. O que sobra é informação que nunca esteve no código, ou que custa tempo de verdade para ser redescoberta:

Acrescente uma linha quando o Claude errar a mesma coisa pela segunda vez, quando uma revisão de código pegar algo que ele deveria saber, ou quando você digitar a mesma correção da sessão passada. Esse é o sinal de que o fato pertence ao arquivo.

Um exemplo que vale copiar

Aqui está um arquivo de projeto curto. Repare que cada linha é algo que dá para verificar e que pouca coisa descreve a arquitetura.

# Project notes

## Commands
- Install: pnpm install (never npm or yarn)
- Dev server: pnpm dev (port 3000)
- Tests: pnpm test -- --run, run before every commit
- Typecheck: pnpm typecheck, must pass before a pull request

## Conventions
- 2-space indentation, double quotes
- API handlers live in src/api/handlers/
- Do not edit anything in src/gen/, it is generated by pnpm codegen

## Gotchas
- Integration tests need a local Redis: docker compose up redis
- Dates are stored in UTC, formatted only in the UI layer

São 15 linhas, e cada uma merece estar ali.

Como escrever linhas que o Claude segue

Como o CLAUDE.md é contexto e não configuração, o jeito de redigir cada linha decide se ela será seguida. Escreva instruções concretas o bastante para serem conferidas.

Depois, mantenha o arquivo em boa forma:

• Curto. Mire em menos de 200 linhas por arquivo. Arquivos mais longos usam mais contexto e o Claude os segue com menos confiabilidade.
• Organizado. Agrupe linhas relacionadas sob títulos e tópicos em Markdown. O Claude segue melhor a estrutura do que parágrafos densos.
• Coerente. Se duas linhas discordam, o Claude pode escolher uma ao acaso. Releia seus arquivos de vez em quando, inclusive os das subpastas, e apague o que estiver desatualizado.

Para o Claude auditar seus arquivos de instruções atrás de linhas desatualizadas ou conflitantes, rode /doctor prompt-audit. Ele relata o que achou e propõe edições, sem mudar nada até você pedir. Exige o Claude Code 2.1.283 ou posterior.

Importando outros arquivos

O CLAUDE.md pode puxar outros arquivos com um @ antes do caminho. O arquivo importado é carregado junto com o CLAUDE.md que o menciona.

See @README for the project overview and @package.json for the npm commands.

# Additional instructions
- git workflow: @docs/git-instructions.md

Caminhos relativos são resolvidos a partir do arquivo que contém a importação. Importações podem importar outros arquivos, até quatro níveis de profundidade. O @ só é lido fora de trechos de código, então coloque o caminho entre crases se quiser mencioná-lo sem importá-lo.

Importações servem para organizar, mas não diminuem o contexto: os arquivos importados continuam sendo carregados por inteiro. Para instruções pessoais que você quer em várias cópias do mesmo repositório, importe um arquivo da sua pasta pessoal, como @~/.claude/my-project-instructions.md. Na primeira vez que um projeto importa um arquivo de fora do diretório de trabalho, o Claude Code pede sua aprovação.

Quando um arquivo fica longo demais

Em algum momento o arquivo passa do que toda sessão precisa. Você tem algumas ferramentas, cada uma para um trabalho diferente.

Regras com escopo para certos arquivos

Coloque um arquivo Markdown por assunto em .claude/rules/, como testing.md ou api-design.md. Para uma regra valer só para certos arquivos, acrescente um campo paths no topo:

---
paths:
  - "src/api/**/*.ts"
---

# API rules

- Every endpoint validates its input
- Use the standard error response format

Uma regra sem paths carrega em toda sessão. Uma regra com escopo carrega quando o Claude lê ou edita um arquivo correspondente, o que tira as instruções do caminho no resto do tempo.

Se um bloco do CLAUDE.md é um procedimento de vários passos, como preparar um release, mova-o para uma habilidade. As habilidades só carregam quando são usadas.

Memória automática: as anotações que o Claude guarda para si

Além do arquivo que você escreve, o Claude Code pode guardar anotações por conta própria. A memória automática vem ligada por padrão nas sessões locais. Enquanto trabalha, o Claude salva quatro tipos de anotação: sobre você (função e preferências), feedback (correções e abordagens que você confirmou), o projeto (decisões e prazos que não aparecem no código) e referências (onde achar coisas fora do projeto).

Ele não salva o que consegue ler no código, nem o que o seu CLAUDE.md já diz. Você verá mensagens como "Saved 2 memories" na sessão. As anotações são Markdown simples em ~/.claude/projects/, e as primeiras 200 linhas ou 25 KB do arquivo de índice são carregadas no início de cada sessão.

Rode /memory para ver todos os arquivos de instruções e a pasta da memória automática, abrir qualquer um deles no seu editor e ligar ou desligar a memória automática. Se você disser ao Claude "use sempre pnpm, não npm", ele salva isso na memória automática. Para colocar algo no CLAUDE.md, diga isso: "adicione isto ao CLAUDE.md".

Dentro do Claude Tutorial

Escrever o que você repetiria

Transformar a mesma correção em instrução permanente é um hábito que vale a pena em qualquer tipo de trabalho com o Claude, não só em código, e o app o ensina passo a passo.

Em breve

Baixe naApp Store

DISPONÍVEL NOGoogle Play

Quando o Claude não segue

Passe por estes pontos em ordem. Eles resolvem a maioria dos casos.

Dois casos extras merecem atenção. Depois de um /compact, o CLAUDE.md da raiz do projeto é lido de novo do disco, então ele sobrevive. Uma instrução que você deu só na conversa não sobrevive, então mova-a para o arquivo. E quando um CLAUDE.md numa subpasta é muito longo (mais de uns 40.000 caracteres numa janela de contexto menor), o Claude recebe só o começo dele, então mantenha esses curtos.

Perguntas frequentes

Onde coloco o CLAUDE.md?

Na raiz do projeto (./CLAUDE.md) ou em ./.claude/CLAUDE.md. Coloque preferências pessoais para todos os projetos em ~/.claude/CLAUDE.md. Use ./CLAUDE.local.md, adicionado ao .gitignore, para anotações privadas sobre um projeto.

Qual deve ser o tamanho de um CLAUDE.md?

Mire em menos de 200 linhas. Se passar, o Claude Code mostra um aviso ao iniciar e no /status. Mova as partes de uma área específica para regras com escopo e corte o que o Claude consegue ler no código.

O CLAUDE.md é a mesma coisa que um prompt de sistema?

Não. O CLAUDE.md é entregue como uma mensagem depois do prompt de sistema. O Claude tenta segui-lo, mas não há garantia de cumprimento estrito. Para instruções que precisam valer sempre, use um hook ou uma regra de permissão.

Devo fazer o commit do CLAUDE.md no git?

Sim para o arquivo do projeto, para a equipe inteira compartilhá-lo e ele melhorar a cada correção. Não para o CLAUDE.local.md, que é pessoal.

O Claude lê o CLAUDE.md das subpastas?

Sim, sob demanda. Ele carrega o arquivo de uma subpasta na primeira vez que o Claude lê ou edita um arquivo naquela pasta, e mostra uma linha Loaded com o caminho.

Qual é a diferença entre o CLAUDE.md e uma habilidade?

O CLAUDE.md é para fatos necessários em toda sessão. Uma habilidade é um procedimento ou manual que só carrega quando é chamada ou relevante, então não ocupa espaço no resto do tempo.

Seu checklist do CLAUDE.md

Continue lendo

• Claude Code para iniciantes: instale, entre e faça sua primeira tarefa se você ainda não começou uma sessão.
• Boas práticas do Claude Code: hábitos que dão melhores resultados para prompts, verificações e gestão de contexto.
• Modos de permissão e modo plan do Claude Code, explicados para decidir o que o Claude pode fazer sem perguntar.
• Projetos do Claude: contexto que fica para a mesma ideia no app do Claude: instruções permanentes guardadas com um projeto.