3.2 Memória Externa — Arquivos de Apoio | Mestre em Contexto e Tokens

📄 CLAUDE.md — o arquivo sempre carregado

O CLAUDE.md é o único arquivo que o Claude Code carrega automaticamente no início de toda sessão — e re-injeta depois de compaction. Tudo que for regra permanente do projeto vai aqui, não na conversa.

Ciclo de vida do CLAUDE.md em uma sessão

🚀

1. Abertura da sessão

Claude Code lê ./CLAUDE.md do diretório atual automaticamente.

💬

2. Durante a conversa

CLAUDE.md permanece no contexto em todos os turnos.

🔄

3. Após compaction

Claude Code re-lê do disco e re-injeta. Sobrevive a /compact e auto-compaction.

🆕

4. Nova sessão

Mesmo ciclo recomeça. Instruções sobrevivem "para sempre".

🧠A garantia única do CLAUDE.md

Três propriedades que nenhum outro lugar oferece: automático (não precisa colar), persistente (vale para toda sessão), resiliente (re-injetado após compaction).

Por isso regras que precisam valer SEMPRE vão aqui. Pedido na conversa some. Regra no CLAUDE.md fica.

Exemplo enxuto (~50 linhas)

# Projeto: api-pagamentos

## Contexto
API Node/Fastify para processar pagamentos (Stripe + PIX).
Produção serve 50k tx/dia. Confiabilidade > performance.

## Stack
- Node 20, pnpm 9, TypeScript 5.4
- Fastify 4, Prisma 5, PostgreSQL 16
- Jest para testes, Playwright para e2e

## Regras
- Sempre rodar `pnpm test` antes de commitar
- Nunca logar dados de cartão (PCI-DSS)
- Migrations: `pnpm prisma migrate dev`

## Arquivos de apoio
- Decisões arquiteturais: /docs/decisions.md
- Roadmap atual: /docs/todo.md
- Esquema de dados: /prisma/schema.prisma

📏 Regra oficial: menos de 200 linhas

A Anthropic publicou um limite explícito para CLAUDE.md — e tem motivo técnico por trás.

📘Recomendação oficial Anthropic

"Target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence."

Fonte: Anthropic Claude Code best practices

A segunda parte da frase é a mais importante: "reduce adherence". Não é só o custo de tokens — é que o próprio modelo presta menos atenção às instruções quando o arquivo fica grande demais.

Aderência vs tamanho do CLAUDE.md (ilustrativo)

~50 linhasaderência alta

~150 linhasboa

~200 linhas (limite oficial)OK

~400 linhasinstruções ignoradas

~800 linhaspraticamente inútil

✓ O que MANTER no CLAUDE.md

✓Stack e versões principais
✓Regras que sempre valem (testes, lint, commit)
✓Contexto de domínio em 2-3 linhas
✓Ponteiros para outros arquivos

✗ O que EXTRAIR para fora

✗Workflows raros → virar skill
✗Arquitetura detalhada → ARCHITECTURE.md
✗Decisões passadas → decisions.md
✗Roadmap/TODOs → todo.md

🌳 Hierarquia de CLAUDE.md

O Claude Code procura CLAUDE.md em 4 níveis de escopo e junta tudo. Saber onde cada coisa vai evita duplicação e problemas de compartilhamento.

Os 4 níveis, em ordem de precedência

Nível	Caminho	Escopo	Versionado?
🔒 Managed Policy	/etc/claude-code/	Toda a máquina (admin/org)	Gerenciado pela org
👤 User	~/.claude/CLAUDE.md	Todos os projetos seus	Pessoal (não no repo)
📁 Project ★ mais comum	./CLAUDE.md	Esse projeto (compartilhado)	Sim — git add
🏠 Local	./CLAUDE.local.md	Esse projeto, só você	Não — .gitignore

Onde colocar cada tipo de regra

👤

Preferências pessoais → ~/.claude/

"Sempre use pnpm", "idioma pt-BR", "prefira TypeScript". Vale em todo projeto seu.

📁

Regras do projeto → ./CLAUDE.md

Stack, convenções, comandos. Todo mundo no time vê e usa.

🏠

Overrides locais → ./CLAUDE.local.md

"Uso porta 3001 em vez de 3000", caminhos específicos da sua máquina. Não vai pro git.

💡Regra mnemônica

"Se outra pessoa do time precisa ver → project. Se é só pra você em todos os projetos → user. Se é pra esse projeto mas só na sua máquina → local."

🛠️ Skills vs CLAUDE.md

Muita gente trata skills e CLAUDE.md como substitutos — mas são complementares. A diferença está em quando carregam.

📘 CLAUDE.md

Quando carregaSempre

Tamanho ideal< 200 linhas

CustoToda sessão

Re-injeta?Sim

Ideal para:

Regras curtas que sempre valem

🎒 Skills

Quando carregaSob demanda

Tamanho máximo5k tokens cada

Budget total25k combinado

CustoSó quando invocada

Ideal para:

Workflows longos e esporádicos

Matriz de decisão

Frequência	Tamanho	Onde colocar
Alta (todo turno)	Curto	CLAUDE.md ★
Alta	Longo	Dividir: core no CLAUDE.md, detalhe em skill
Baixa	Curto	Ainda skill (economiza tokens)
Baixa	Longo	Skill ★

⚠️Antipattern clássico

CLAUDE.md de 500 linhas com 10 workflows diferentes. Cada sessão paga o custo dos 10 — mesmo usando só 1. Transforme cada workflow em skill e mantenha no CLAUDE.md só o ponteiro.

Economia típica: 3-5k tokens por sessão, mais aderência às regras que SOBRARAM no CLAUDE.md.

📝 Arquivos de decisão e estado

Para tudo que não cabe no CLAUDE.md mas precisa estar disponível, use arquivos markdown auxiliares. O CLAUDE.md aponta para eles; o Claude lê só quando precisa.

📋

decisions.md — ADRs curtos

Decisões arquiteturais em formato enxuto: data + decisão + motivo. Ficam versionadas com o código.

# Decisões arquiteturais

## 2026-04-10 · PostgreSQL (não MongoDB)
Transações críticas exigem ACID. Mongo ficaria só para logs.

## 2026-04-15 · Fastify (não Express)
2x mais rápido em benchmarks internos. Schema validation nativo.

## 2026-04-18 · Prisma (não TypeORM)
Melhor DX com TypeScript. Migrations automáticas.

✅

todo.md — lista volátil

Tarefas em andamento. Atualiza a cada sessão. O handoff pode referenciar "continuar de onde parou em todo.md".

# TODO — Sprint atual

## Feito
- [x] Setup inicial do projeto
- [x] Schema Prisma v1

## Em progresso
- [ ] Endpoint POST /api/orders (50% — falta validação)

## Próximo
- [ ] Middleware de autenticação
- [ ] Testes e2e do fluxo de checkout

🏛️

ARCHITECTURE.md — mapa do sistema

Visão geral estável. O Claude consulta quando precisa entender como os módulos conversam.

# Arquitetura — api-pagamentos

## Módulos
- /src/api        → rotas HTTP (Fastify)
- /src/domain     → lógica de negócio (pura)
- /src/infra      → Prisma, Redis, Stripe SDK
- /src/workers    → jobs em background (BullMQ)

## Fluxo de um pagamento
api → domain/validate → infra/stripe → workers/webhook

🎯Como o CLAUDE.md aponta

# CLAUDE.md (trecho)

## Arquivos de apoio
- Antes de decidir arquitetura: leia /docs/decisions.md
- Antes de começar tarefa nova: leia /docs/todo.md
- Para entender fluxo: /docs/ARCHITECTURE.md

Dessa forma o Claude só carrega o auxiliar quando vai usar. Economia real de contexto.

🧠 Memória, arquivo ou skill?

Três destinos possíveis para cada pedaço de informação — e eles não são intercambiáveis. Escolher errado causa duplicação, desperdício ou esquecimento.

Árvore de decisão: onde vai cada informação

Tipo de informação	Exemplo	Destino
🧬 Fato permanente sobre você	"prefiro pnpm", "idioma pt-BR"	~/.claude/CLAUDE.md (memória)
📋 Regra permanente do projeto	"nunca logar dados de cartão"	./CLAUDE.md
🏛️ Decisões arquiteturais	"escolhemos Postgres porque..."	./docs/decisions.md
✅ Estado / TODO	"falta implementar middleware X"	./docs/todo.md
🛠️ Workflow reutilizável	"como publicar uma nova release"	skill
📚 Documentação de referência	"esquema de dados detalhado"	arquivo dedicado (apontado no CLAUDE.md)
🚀 Handoff de continuação	"estado atual da sessão"	handoff.md (colado em nova sessão)

🔍Teste rápido de 2 perguntas

1. "Isso muda por projeto?"

SIM → arquivo de projeto (CLAUDE.md ou .md apontado). NÃO → memória de usuário.

2. "É um procedimento reutilizável?"

SIM → skill. NÃO → arquivo markdown.

🏆A meta-regra

Cada informação tem 1 lugar. Duplicação gera inconsistência (atualiza um, esquece outro). Se você sente necessidade de repetir, é sinal que o lugar original está errado.

📋Resumo do Módulo

✓

CLAUDE.md é automático, persistente e resiliente — re-injetado após compaction

✓

Limite oficial de 200 linhas — acima disso aderência cai

✓

4 níveis hierárquicos — managed, user, project, local

✓

Skills ≠ CLAUDE.md — sob demanda (5k cada, 25k total) vs sempre carregado

✓

Arquivos auxiliares enxutos — decisions.md, todo.md, ARCHITECTURE.md

✓

Cada informação tem 1 lugar — memória, arquivo ou skill

Próximo módulo:

3.3 — 🚀 Continuando de Onde Parou

Como retomar uma sessão com handoff, validar entendimento e evitar o erro fatal de "limpa e lembra".

← Módulo Anterior Próximo: Continuando de Onde Parou →