CLAUDE.md e Memória

Toda sessão do Claude Code começa com uma janela de contexto vazia. Dois mecanismos carregam conhecimento entre sessões: CLAUDE.md (instruções que você escreve) e auto memory (notas que o Claude escreve sozinho). Os dois são context engineering puro: o que você coloca aqui dita como o agente se comporta em todas as conversas seguintes.

CLAUDE.md vs Auto Memory

	CLAUDE.md	Auto memory
Quem escreve	Você	O Claude
O que contém	Instruções e regras	Aprendizados e padrões
Escopo	Projeto, usuário ou organização	Por working tree
Carrega em	Toda sessão	Toda sessão (primeiras 200 linhas/25KB)
Pra que serve	Padrões de código, workflows, arquitetura	Comandos de build, insights de debug, preferências aprendidas

CLAUDE.md é pra você guiar comportamento. Auto memory deixa o Claude aprender com correções sem você precisar escrever nada.

CLAUDE.md

Onde Colocar

Diferentes localizações, escopo diferente. Mais específico vence o mais geral.

Escopo	Localização	Compartilhado com
Managed policy	`/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux/WSL), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows)	Toda a organização
Projeto	`./CLAUDE.md` ou `./.claude/CLAUDE.md`	Time via git
Usuário	`~/.claude/CLAUDE.md`	Só você, todos os projetos
Local	`./CLAUDE.local.md` (no `.gitignore`)	Só você, projeto atual

Todos os arquivos descobertos são concatenados (não sobrescrevem). O Claude sobe o diretório procurando, então em monorepo ele pega o CLAUDE.md da raiz e do package que você está editando.

Como Escrever

CLAUDE.md carrega na janela de contexto a cada sessão. Cada token aqui é um token a menos pro resto do trabalho. Por isso, regras de ouro:

Tamanho: alvo abaixo de 200 linhas. Arquivos longos consomem contexto e reduzem aderência (o Claude começa a ignorar). Se está crescendo, quebre em path-scoped rules.

Estrutura: headers e bullets. Escaneabilidade importa pro modelo igual importa pra leitor humano.

Especificidade: instruções concretas e verificáveis.

Bom	Ruim
"Use 2-space indentation"	"Format code properly"
"Run `npm test` before committing"	"Test your changes"
"API handlers live in `src/api/handlers/`"	"Keep files organized"

Consistência: se duas regras se contradizem, o Claude pode escolher uma arbitrariamente. Revise periodicamente.

O que incluir

✅ Incluir	❌ Excluir
Comandos Bash que o Claude não consegue adivinhar	Qualquer coisa que ele descobre lendo o código
Regras de estilo que diferem do default da linguagem	Convenções padrão da linguagem
Instruções de teste e runner preferido	Documentação de API detalhada (linka pro doc)
Etiqueta de repositório (branch naming, PR conventions)	Informação que muda toda hora
Decisões arquiteturais específicas do projeto	Descrição arquivo-por-arquivo do codebase
Quirks do ambiente de dev (env vars obrigatórias)	"Escreva código limpo"
Gotchas e comportamentos não-óbvios	Tutoriais longos

Use `/init` pra Começar

/init

Analisa seu codebase, detecta build system, framework de teste, padrões, e cria um CLAUDE.md inicial. Se já existe um, sugere melhorias em vez de sobrescrever.

Existe também o modo interativo (CLAUDE_CODE_NEW_INIT=1) que pergunta o que configurar (CLAUDE.md, skills, hooks), explora com subagente e propõe um plano antes de escrever.

Imports

CLAUDE.md pode importar outros arquivos com sintaxe @path/to/file:

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

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

Paths são relativos ao arquivo que importa. Recursão até 5 níveis. Imports carregam no launch igual o resto.

CLAUDE.local.md

Pra preferências pessoais que não vão pro git. Vai no .gitignore. Útil pra:

URLs de sandbox que só você usa
Dados de teste pessoais
Atalhos de tooling individuais

AGENTS.md

Se seu repo já usa AGENTS.md pra outros agentes, crie um CLAUDE.md que importa:

@AGENTS.md

## Claude Code

Use plan mode pra mudanças sob `src/billing/`.

Comments HTML

Comentários block-level HTML são removidos antes do conteúdo entrar no contexto:

<!-- Notas pro mantenedor sobre por que essa regra existe -->

Não gastam tokens, mas você lê quando abrir o arquivo.

Organizar em `.claude/rules/`

Pra projetos maiores, em vez de inflar o CLAUDE.md, quebre em arquivos modulares em .claude/rules/. Cada arquivo cobre um tópico:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Instruções gerais
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── security.md

Path-Specific Rules

Aqui mora a economia. Rules com paths no frontmatter só carregam quando o Claude abre arquivos que casam:

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

# API Development Rules

- Endpoints precisam de validação de input
- Use o formato padrão de error response
- Inclua comentários OpenAPI

Rules sem paths carregam sempre, igual CLAUDE.md.

Patterns suportam glob:

Pattern	Mata
`*/.ts`	Todo TypeScript
`src/*/`	Tudo sob `src/`
`*.md`	Markdown na raiz
`src/*/.{ts,tsx}`	Brace expansion

Auto Memory

Auto memory é o Claude tomando notas sozinho. Ele decide o que vale lembrar baseado em se a informação seria útil em conversa futura.

Storage

Cada projeto tem seu próprio diretório:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Index, carrega em toda sessão (primeiras 200 linhas/25KB)
├── debugging.md       # Notas detalhadas (carregam sob demanda)
├── api-conventions.md
└── ...

MEMORY.md é o índice. Os outros arquivos carregam só quando o Claude precisa.

Toggles

# Via comando
/memory  # toggle no painel

# Via settings
{ "autoMemoryEnabled": false }

# Via env var
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Diretório Custom

{ "autoMemoryDirectory": "~/my-custom-memory-dir" }

Aceito em policy, local e user settings. Não aceito em project settings (pra evitar redirecionamento malicioso).

Como o Claude Decide o que Salvar

Não é "sempre salva". Ele avalia se o aprendizado seria útil em conversas futuras. Tipos comuns:

Comandos de build que ele aprendeu (pnpm build:packages)
Insights de debug (que função olhar quando dá X erro)
Convenções de arquitetura que ele descobriu lendo código
Preferências do usuário que apareceram em correções (use ESM, não CommonJS)

Auditando

Auto memory é markdown. Você lê, edita, deleta. /memory lista tudo que está carregado e dá acesso pra abrir os arquivos.

Se você não quer que o Claude aja em algo de auto memory, fala explicitamente: "Ignore o que está em memory sobre X".

Comando `/memory`

Lista todos CLAUDE.md, CLAUDE.local.md, rules e auto memory carregados na sessão. Toggle pra auto memory. Link pra abrir o folder de auto memory. Selecionar um arquivo abre no seu editor.

Quando você pede "sempre use pnpm, não npm" ou "lembre que os testes de API precisam de Redis local", o Claude salva em auto memory. Pra ir pro CLAUDE.md, fala explicitamente: "adiciona isso no CLAUDE.md".

O que Sobrevive à Compactação

CLAUDE.md da raiz é re-lido do disco e re-injetado depois de /compact. Nested CLAUDE.md em subdiretórios não voltam automaticamente: re-carregam quando o Claude lê um arquivo daquele diretório de novo.

Se uma instrução sumiu depois de compactar, era só de conversa, ou estava num nested que ainda não recarregou. Mova pra CLAUDE.md raiz pra persistir.

Excluir CLAUDE.md em Monorepos

Em monorepo, ancestor CLAUDE.md de outros times pode entrar no seu contexto sem necessidade. Use claudeMdExcludes:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Coloque em .claude/settings.local.json pra ficar local.

Managed policy CLAUDE.md não pode ser excluído.

Troubleshooting

Claude não está seguindo o CLAUDE.md

CLAUDE.md é entregue como user message depois do system prompt. O Claude lê e tenta seguir, mas não há garantia estrita. Pra debug:

Rode /memory e confirme que o arquivo está carregado
Verifique se está numa localização que carrega na sua sessão
Torne instruções mais específicas
Procure conflitos entre múltiplos CLAUDE.md

Pra instruções no nível de system prompt, use --append-system-prompt.

CLAUDE.md grande demais

Acima de 200 linhas, aderência cai. Quebre em path-scoped rules ou skills.

Imports não funcionam

A primeira vez que o Claude encontra imports externos, ele mostra um dialog de aprovação. Se você negou, fica desabilitado pra sempre. Re-aprove via settings ou aceite no próximo prompt.

Conclusão

CLAUDE.md é a documentação executável do seu projeto. Bem feito, ele faz o Claude trabalhar como se conhecesse a base há meses. Mal feito (longo, vago, conflitante), ele atrapalha mais que ajuda. A regra básica:

Específico > genérico
Curto > longo
Verificável > subjetivo
Path-scoped > tudo no raiz

E auto memory cuida do que você nunca lembraria de escrever sozinho.

Próximo: Dicas de Desenvolvimento e Economia de Tokens

Referências:

CLAUDE.md vs Auto Memory​

CLAUDE.md​

Onde Colocar​

Como Escrever​

O que incluir​

Use /init pra Começar​

Imports​

CLAUDE.local.md​

AGENTS.md​

Comments HTML​

Organizar em .claude/rules/​

Path-Specific Rules​

Auto Memory​

Storage​

Toggles​

Diretório Custom​

Como o Claude Decide o que Salvar​

Auditando​

Comando /memory​

O que Sobrevive à Compactação​

Excluir CLAUDE.md em Monorepos​

Troubleshooting​

Claude não está seguindo o CLAUDE.md​

CLAUDE.md grande demais​

Imports não funcionam​

Conclusão​