CLAUDE.md: como dar memória ao Claude Code

Toda vez que você abre o Claude Code, ele começa com a memória zerada. A janela de contexto é nova, e tudo que você explicou ontem — o comando de testar, onde ficam os handlers da API, aquele padrão que o time segue — sumiu. No dia seguinte, você reexplica. E no outro também.

O jeito oficial de quebrar esse ciclo é o CLAUDE.md: um arquivo onde você escreve, uma vez, o que o Claude deveria saber em toda sessão. Ele lê no começo de cada conversa e parte daí já contextualizado. E tem um irmão mais novo que faz metade do trabalho por você: a memória automática, em que o próprio Claude anota o que aprende.

Se você ainda não tem o Claude Code rodando, comece pela instalação e depois volte aqui.

Os dois tipos de memória

Vale separar logo, porque confunde:

• CLAUDE.md — quem escreve é você. São instruções e regras: comandos de build, convenções de código, arquitetura, "sempre faça X". É a sua voz dizendo ao Claude como trabalhar neste projeto.
• Memória automática — quem escreve é o Claude. Conforme você corrige e demonstra preferências, ele anota sozinho: aquele comando que finalmente funcionou, uma pegadinha de debug, um hábito seu.

Os dois são carregados no início de toda conversa e se completam. Um você dita; o outro o Claude descobre. Comecemos pelo que está nas suas mãos.

Onde o CLAUDE.md mora

O arquivo pode viver em lugares diferentes, e cada um tem um alcance. Eles são carregados juntos, do mais amplo pro mais específico:

• Pessoal — ~/.claude/CLAUDE.md. Vale em todos os seus projetos. Bom pra preferências suas: estilo de código, atalhos de ferramenta que você usa em tudo.
• Do projeto — ./CLAUDE.md ou ./.claude/CLAUDE.md. Fica versionado no Git e vai junto pro time. Aqui entram arquitetura, padrões e fluxos do projeto.
• Local — ./CLAUDE.local.md. Suas preferências privadas daquele projeto (URLs de sandbox, dados de teste). Jogue no .gitignore pra não commitar.

O Claude também sobe pela árvore de diretórios: se você roda dentro de app/api/, ele junta o CLAUDE.md de api/, o de app/ e o da raiz. Instruções mais perto de onde você está são lidas por último.

Como começar sem escrever do zero

Não precisa encarar uma página em branco. Dentro do projeto, rode:

/init

O Claude varre o código e gera um CLAUDE.md inicial com os comandos de build, as instruções de teste e as convenções que ele conseguiu identificar. Se já existir um arquivo, o /init sugere melhorias em vez de sobrescrever. A partir daí, você refina com o que ele não tem como adivinhar — decisões de arquitetura, o "porquê" das coisas, regras do time.

O que (e como) escrever

A regra mental: o CLAUDE.md é o lugar de anotar o que você reexplicaria. Adicione algo quando:

• o Claude comete o mesmo erro pela segunda vez;
• um code review pega algo que ele deveria saber sobre este repositório;
• você digita pela enésima vez a mesma correção no chat.

E escreva de um jeito que ele consiga seguir. Três princípios que fazem diferença:

• Seja específico. "Use indentação de 2 espaços" funciona melhor que "formate direito". "Os handlers da API ficam em src/api/handlers/" bate "mantenha organizado".
• Seja enxuto. Mire em menos de 200 linhas por arquivo. O CLAUDE.md ocupa espaço na janela de contexto em toda sessão — arquivo gigante consome tokens e, ironicamente, reduz a aderência. Se economizar contexto é uma dor sua, vale ler também como gastar menos tokens no Claude.
• Seja estruturado. Use títulos ## e listas. O Claude lê a estrutura como você lê: seções organizadas são mais fáceis de seguir que um parágrafo denso.

Um exemplo curto e concreto vale mais que mil regras vagas:

# Projeto Loja
 
## Comandos
- Build: `npm run build`
- Testes: `npm test` (rode antes de cada commit)
 
## Convenções
- Handlers da API em `src/api/handlers/`
- Componentes React em `src/components/`, um por arquivo
- Indentação de 2 espaços, sem ponto e vírgula

Importar outros arquivos

Se o conteúdo cresce, dá pra quebrar em pedaços com a sintaxe @caminho:

Veja @README para visão geral e @package.json para os comandos.
 
# Instruções extras
- fluxo de git @docs/git-instructions.md

O Claude expande esses arquivos e carrega tudo junto no início. Útil pra reaproveitar um README ou um guia que já existe sem duplicar. (Quer só citar um caminho sem importar? Coloque entre crases: `@README` vira texto literal.)

A pegadinha mais importante

Aqui mora o mal-entendido que mais decepciona gente: o CLAUDE.md é contexto, não lei. O Claude lê e tenta seguir, mas não é uma trava. Instruções vagas ou que se contradizem entre dois arquivos podem ser ignoradas.

Então, pra algo que precisa acontecer sempre — rodar o lint antes de todo commit, bloquear um comando perigoso — não confie só no texto. Use um hook, que roda como comando de verdade num momento fixo do ciclo, independente do que o Claude decide. É a diferença entre pedir e garantir. (Tem um guia completo sobre hooks no Claude Code aqui no blog.)

A memória automática: o Claude anotando sozinho

Essa é a parte nova e que mais surpreende. Com a memória automática ligada (é o padrão nas versões recentes), o Claude guarda anotações pra si mesmo enquanto trabalha: o comando de build que deu certo, uma descoberta de debug, uma preferência sua. Ele não salva a cada sessão — decide o que vale a pena com base em se a informação seria útil numa conversa futura.

Você ajuda dando o empurrão. Frases como:

lembre que os testes precisam de um Redis local rodando
sempre use pnpm neste projeto, não npm

…viram anotações persistentes. As notas ficam em ~/.claude/projects/<projeto>/memory/, com um MEMORY.md que funciona de índice e é carregado em toda sessão (os detalhes ficam em arquivos por tópico, lidos sob demanda). Como o caminho vem do repositório Git, todos os worktrees do mesmo projeto compartilham a mesma memória.

Audite com /memory

Não é uma caixa-preta. A qualquer momento, rode:

/memory

Ele lista todos os arquivos de instrução carregados na sessão (CLAUDE.md, CLAUDE.local.md, regras) e dá acesso à pasta da memória automática. Tudo é markdown comum — você lê, edita ou apaga o que estiver errado. É bom passar o olho de vez em quando pra remover instruções desatualizadas ou que se contradizem, já que o conflito é justamente o que faz o Claude escolher uma regra na sorte.

O essencial

Memória, no Claude Code, são duas peças que se encaixam:

1. CLAUDE.md — você escreve as regras, comandos e convenções que valem sempre. Comece com /init, mantenha enxuto e específico.
2. Memória automática — o Claude anota os aprendizados sozinho. Você confere e poda com /memory.

Junte as duas e cada nova sessão já começa sabendo do seu projeto — sem você reexplicar nada. E pra aquilo que não pode falhar, lembre: regra rígida é trabalho de hook, não de texto.

Por onde continuar

• Quer transformar um trecho do seu CLAUDE.md num procedimento que carrega só quando precisa? Veja como criar uma Skill no Claude Code.
• Tarefas pesadas entupindo seu contexto? Aprenda a delegar com subagentes no Claude Code.
• Tá começando agora? O guia do Claude Code no terminal te deixa pronto pro dia a dia.

Fonte: documentação oficial da Anthropic, How Claude remembers your project. Os fatos (locais e ordem de carregamento do CLAUDE.md, /init, /memory, imports com @, o limite recomendado de 200 linhas e o funcionamento da memória automática) vêm de lá; a redação, os exemplos e a estrutura são deste blog.