🧠 CLAUDE.md e memória persistente
O CLAUDE.md como instruções permanentes do projeto. Memória entre sessões, o que guardar vs evitar, contexto enxuto e convenções de time que o Claude realmente respeita.
1 📄 O que é o CLAUDE.md
O CLAUDE.md é lido automaticamente no início de cada sessão
O CLAUDE.md não é apenas um README. É o arquivo de instruções que o Claude lê antes de qualquer prompt. Define o que o projeto é, como ele funciona e quais regras o agente deve seguir.
# my-project — Instruções do agente
## Visão geral
Dashboard pessoal de produtividade. Stack: Bun + React +
Vite + Tailwind. Deploy: Cloudflare Pages via wrangler.
## Estrutura do projeto
```
src/ → componentes React e lógica de UI
scripts/ → data pipeline e automação
docs/adr/ → decisões de arquitetura
```
## Regras obrigatórias
- NUNCA ler ou escrever arquivos fora deste repo
- Dashboard é READ-ONLY — sem mutações de dados
- Variáveis sensíveis em .env (nunca em src/)
- Commits seguem Conventional Commits
## Stack e versões
- Bun 1.1.x como runtime
- React 19 + TanStack Query v5
- Tailwind CSS 4.x
## Convenções de código
- TypeScript strict mode ativado
- Nomes de arquivos em kebab-case
- Componentes em PascalCase
- testes com Vitest✓ CLAUDE.md eficaz
- • Visão geral em 2-3 linhas
- • Estrutura de pastas com propósito
- • Regras obrigatórias explícitas
- • Versões de stack fixadas
- • Convenções de nomenclatura
✗ CLAUDE.md problemático
- • 500 linhas de história do projeto
- • Tokens de API em texto limpo
- • Regras vagas ("seja cuidadoso")
- • Desatualizado há 6 meses
- • Copia-e-cola de docs genéricos
2 💾 Memória entre sessões
O Claude não tem memória nativa entre sessões. Toda "memória" deve ser construída explicitamente como arquivos que o Claude pode ler na próxima sessão.
Hierarquia de memória explícita
CLAUDE.md — memória permanente
Instruções que nunca mudam entre sessões: arquitetura, regras, stack, convenções. Lido automaticamente.
docs/decisions.md — memória de decisões
Log de decisões tomadas com o Claude. "Em 2026-05-10 decidimos usar TanStack Query em vez de SWR porque..."
Session handoff prompt — contexto da sessão anterior
Ao encerrar: "Resuma o que fizemos hoje em 5 bullets e salve em docs/session-2026-05-15.md".
Dica: session handoff
Ao terminar uma sessão longa, peça: "Escreva um handoff de sessão em docs/handoff.md: o que foi feito, o que está pendente e quaisquer decisões tomadas." Na próxima sessão, peça ao Claude para ler o handoff antes de começar.
3 ✂️ Contexto enxuto
Um CLAUDE.md de 2.000 linhas é tão inútil quanto um de 10 linhas. A informação crítica deve estar no início, e cada linha deve justificar sua presença.
Prioridade de informação no CLAUDE.md
Visão geral + propósito do projeto
O que o projeto faz em 2-3 linhas
Regras obrigatórias e restrições
O que o Claude NUNCA pode fazer
Stack e estrutura de pastas
Onde fica cada coisa
Convenções e preferências
Nomes, commits, revisão de código
✓ O que incluir
- • Propósito do projeto (2 linhas)
- • Restrições críticas de segurança
- • Stack com versões importantes
- • Mapa de pastas com tree
- • Convenções que divergem do padrão
✗ O que não incluir
- • Tokens, chaves de API, senhas
- • Histórico completo de decisões
- • Tutoriais de como usar a stack
- • Todo o conteúdo do CHANGELOG
- • Comentários sobre sessões passadas
4 📋 Convenções do time
O Claude segue convenções quando elas estão escritas explicitamente. Sem isso, ele adota suas próprias convenções — que podem ser boas, mas não serão as suas.
## Convenções de código
### Nomenclatura
- Arquivos: kebab-case (meu-componente.tsx)
- Componentes React: PascalCase (MeuComponente)
- Funções: camelCase (calcularTotal)
- Constantes: UPPER_SNAKE_CASE (MAX_RETRIES)
- Tipos/interfaces: PascalCase (UserData)
### Commits (Conventional Commits)
- feat: nova feature
- fix: correção de bug
- refactor: refatoração sem mudança de comportamento
- docs: documentação
- test: testes
### Git
- Branches: feat/nome-da-feature ou fix/nome-do-bug
- Sem commits direto na main
- PR revisado antes de merge
### Imports
- Absolutos quando disponível (src/lib/utils)
- Relativos para arquivos no mesmo diretórioConvenções vagas não funcionam
"Use nomes descritivos" não é uma convenção, é uma aspiração. "Funções em camelCase, arquivos em kebab-case, constantes em UPPER_SNAKE" é uma convenção que o Claude pode seguir mecanicamente.
5 🔐 O que guardar vs não guardar
O CLAUDE.md é um arquivo versionado — qualquer dado sensível nele pode vazar via git history, push acidental para repositório público ou logs de API.
Nunca coloque no CLAUDE.md
- •
OPENAI_API_KEY=sk-... - • Credenciais de banco de dados
- • Tokens OAuth ou JWT
- • Dados pessoais de usuários
- • Chaves privadas ou certificados
# Copie para .env e preencha os valores reais
# NUNCA commit o .env — está no .gitignore
OPENAI_API_KEY= # sua chave OpenAI
ANTHROPIC_API_KEY= # sua chave Anthropic
PINECONE_API_KEY= # sua chave Pinecone
DATABASE_URL= # postgresql://...
CLOUDFLARE_ACCOUNT_ID= # ver Cloudflare Dashboard✓ No CLAUDE.md
- • Nomes de variáveis env (sem valores)
- • Onde as configs ficam
- • Regras de acesso e permissões
- • Quais dados são sensíveis
✗ No CLAUDE.md
- • Valores reais de API keys
- • Strings de conexão com senha
- • Dados de usuários de produção
- • Segredos internos da empresa
6 🔄 Evolução do CLAUDE.md
O CLAUDE.md é um documento vivo. Projetos mudam, stacks evoluem, convenções melhoram. O arquivo precisa acompanhar essa evolução.
Cadência de revisão
A cada mudança de stack — imediato
Mudou de Node para Bun? Atualize o CLAUDE.md no mesmo PR. Nunca deixe divergir da realidade.
Mensal — limpar obsoleto
Remove referências a módulos deletados, atualiza versões de pacotes, revisa regras que já não fazem sentido.
Trimestral — revisão completa
Relê tudo com olho crítico: o que ainda é verdade? O que mudou? O que está faltando?
CLAUDE.md no git
Versione o CLAUDE.md no git como qualquer outro arquivo. Isso cria histórico de como as instruções evoluíram e permite rollback se uma mudança causar comportamento inesperado.
📋 Resumo do módulo
- • CLAUDE.md como instruções permanentes
- • Hierarquia de memória explícita
- • Contexto enxuto e priorizado
- • Convenções em linguagem mecânica
- • Segurança: o que nunca vai no CLAUDE.md
- • Cadência de revisão do documento
- • Escreva o CLAUDE.md do seu projeto
- • Crie um .env.example com todos os vars
- • Configure session handoff workflow
- • Agende revisão trimestral no calendário