🧠 CLAUDE.md and persistent memory
CLAUDE.md as the project's permanent instructions. Memory between sessions, what to keep vs. avoid, concise context, and team conventions that Claude actually follows.
1 📄 What is CLAUDE.md?
CLAUDE.md is read automatically at the start of each session
CLAUDE.md isn't just a README. It's the instruction file Claude reads before any prompt. It defines what the project is, how it works, and which rules the agent must follow.
# 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✓ Effective CLAUDE.md
- • Overview in 2-3 lines
- • Folder structure with a purpose
- • Explicit mandatory rules
- • Pinned stack versions
- • Naming conventions
✗ Problematic CLAUDE.md
- • 500 lines of project history
- • API tokens in plain text
- • Vague rules ("be careful")
- • 6 months out of date
- • Copying and pasting generic docs
2 💾 Memory across sessions
Claude has no native memory between sessions. All "memory" must be built explicitly as files Claude can read in the next session.
Explicit memory hierarchy
CLAUDE.md — permanent memory
Instructions that never change between sessions: architecture, rules, stack, conventions. Read automatically.
docs/decisions.md — decision log
Log of decisions made with Claude. "On 2026-05-10, we decided to use TanStack Query instead of SWR because..."
Session handoff prompt — previous session context
When wrapping up: "Summarize what we did today in 5 bullets and save it to docs/session-2026-05-15.md".
Tip: session handoff
At the end of a long session, ask: "Escreva um handoff de sessão em docs/handoff.md: o que foi feito, o que está pendente e quaisquer decisões tomadas." In your next session, ask Claude to read the handoff before getting started.
3 ✂️ Lean context
A 2,000-line CLAUDE.md is as useless as a 10-line one. Critical information should come first, and every line should justify its presence.
Information priority in CLAUDE.md
Overview + project purpose
What the project does in 2-3 lines
Mandatory rules and restrictions
What Claude must NEVER do
Stack and folder structure
Where everything goes
Conventions and preferences
Names, commits, code review
✓ What to include
- • Project purpose (2 lines)
- • Critical security restrictions
- • Stack with important versions
- • Folder map with tree
- • Conventions that differ from the standard
✗ What not to include
- • Tokens, API keys, passwords
- • Complete decision history
- • Tutorials on how to use the stack
- • All CHANGELOG content
- • Comments about past sessions
4 📋 Team conventions
Claude follows conventions when they are written explicitly. Without that, it adopts its own conventions — which may be good, but won't be yours.
## 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órioVague conventions don't work
"Use descriptive names" isn't a convention; it's an aspiration. "Functions in camelCase, files in kebab-case, constants in UPPER_SNAKE" is a convention Claude can follow mechanically.
5 🔐 What to Store vs. What Not to Store
CLAUDE.md is a version-controlled file—any sensitive data in it can leak through git history, an accidental push to a public repository, or API logs.
Never put in CLAUDE.md
- •
OPENAI_API_KEY=sk-... - • Database credentials
- • OAuth or JWT tokens
- • Users' personal data
- • Private keys or certificates
# 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✓ In CLAUDE.md
- • Environment variable names (no values)
- • Where the configs are stored
- • Access and permission rules
- • Which data is sensitive
✗ In CLAUDE.md
- • Actual API key values
- • Connection strings with passwords
- • Production user data
- • Internal company secrets
6 🔄 Evolution of CLAUDE.md
CLAUDE.md is a living document. Projects change, stacks evolve, and conventions improve. The file needs to keep up with that evolution.
Review cadence
With every stack change — immediate
Switched from Node to Bun? Update CLAUDE.md in the same PR. Never let it diverge from reality.
Monthly — remove obsolete items
Remove references to deleted modules, update package versions, and review rules that no longer make sense.
Quarterly — full review
Reread everything with a critical eye: what is still true? What changed? What is missing?
CLAUDE.md in git
Version the CLAUDE.md file in git like any other file. This creates a history of how the instructions evolved and lets you roll back if a change causes unexpected behavior.
📋 Module summary
- • CLAUDE.md as permanent instructions
- • Explicit memory hierarchy
- • Lean, prioritized context
- • Mechanical language conventions
- • Security: what should never go in CLAUDE.md
- • Document review cadence
- • Write your project's CLAUDE.md
- • Create a .env.example with all vars
- • Configure the session handoff workflow
- • Schedule a quarterly review on the calendar