🧠 CLAUDE.md y memoria persistente
El CLAUDE.md como instrucciones permanentes del proyecto. Memoria entre sesiones, qué guardar y qué evitar, contexto conciso y convenciones del equipo que Claude realmente respeta.
1 📄 Qué es el CLAUDE.md
El CLAUDE.md se lee automáticamente al inicio de cada sesión
El CLAUDE.md no es solo un README. Es el archivo de instrucciones que Claude lee antes de cualquier prompt. Define qué es el proyecto, cómo funciona y qué reglas debe seguir el agente.
# 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
- • Resumen general en 2-3 líneas
- • Estructura de carpetas con propósito
- • Reglas obligatorias explícitas
- • Versiones del stack fijadas
- • Convenciones de nomenclatura
✗ CLAUDE.md problemático
- • 500 líneas de historia del proyecto
- • Tokens de API en texto sin cifrar
- • Reglas vagas ("sé cuidadoso")
- • Desactualizado desde hace 6 meses
- • Copiar y pegar documentación genérica
2 💾 Memoria entre sesiones
Claude no tiene memoria nativa entre sesiones. Toda "memoria" debe construirse explícitamente como archivos que Claude pueda leer en la siguiente sesión.
Jerarquía de memoria explícita
CLAUDE.md — memoria permanente
Instrucciones que nunca cambian entre sesiones: arquitectura, reglas, stack, convenciones. Se leen automáticamente.
docs/decisions.md — memoria de decisiones
Registro de decisiones tomadas con Claude. "El 2026-05-10 decidimos usar TanStack Query en vez de SWR porque..."
Prompt para traspaso de sesión — contexto de la sesión anterior
Al terminar: «Resume lo que hicimos hoy en 5 bullets y guárdalo en docs/session-2026-05-15.md».
Consejo: session handoff
Al terminar una sesión larga, pide: "Escreva um handoff de sessão em docs/handoff.md: o que foi feito, o que está pendente e quaisquer decisões tomadas." En la próxima sesión, pídele a Claude que lea el handoff antes de empezar.
3 ✂️ Contexto conciso
Un CLAUDE.md de 2.000 líneas es tan inútil como uno de 10. La información crítica debe estar al principio, y cada línea debe justificar su presencia.
Prioridad de la información en CLAUDE.md
Resumen + propósito del proyecto
Qué hace el proyecto en 2-3 líneas
Reglas obligatorias y restricciones
Qué NUNCA puede hacer Claude
Stack y estructura de carpetas
Dónde está cada cosa
Convenciones y preferencias
Nombres, commits, revisión de código
✓ Qué incluir
- • Propósito del proyecto (2 líneas)
- • Restricciones críticas de seguridad
- • Stack con versiones importantes
- • Mapa de carpetas con tree
- • Convenciones que difieren del estándar
✗ Qué no incluir
- • Tokens, claves de API, contraseñas
- • Historial completo de decisiones
- • Tutoriales sobre cómo usar el stack
- • Todo el contenido del CHANGELOG
- • Comentarios sobre sesiones anteriores
4 📋 Convenciones del equipo
Claude sigue las convenciones cuando están escritas explícitamente. Sin eso, adopta sus propias convenciones, que pueden ser buenas, pero no serán las tuyas.
## 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órioLas convenciones vagas no funcionan
"Usa nombres descriptivos" no es una convención, es una aspiración. "Funciones en camelCase, archivos en kebab-case, constantes en UPPER_SNAKE" es una convención que Claude puede seguir mecánicamente.
5 🔐 Qué guardar y qué no guardar
El CLAUDE.md es un archivo versionado — cualquier dato sensible que contenga puede filtrarse a través del historial de git, un push accidental a un repositorio público o los logs de API.
Nunca lo pongas en CLAUDE.md
- •
OPENAI_API_KEY=sk-... - • Credenciales de bases de datos
- • Tokens OAuth o JWT
- • Datos personales de usuarios
- • Claves privadas o 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✓ En CLAUDE.md
- • Nombres de variables env (sin valores)
- • Dónde se encuentran las configs
- • Reglas de acceso y permisos
- • Qué datos son sensibles
✗ En el CLAUDE.md
- • Valores reales de claves de API
- • Cadenas de conexión con contraseña
- • Datos de usuarios de producción
- • Secretos internos de la empresa
6 🔄 Evolución del CLAUDE.md
El CLAUDE.md es un documento vivo. Los proyectos cambian, las stacks evolucionan, las convenciones mejoran. El archivo debe acompañar esa evolución.
Frecuencia de revisión
Con cada cambio de stack — inmediato
¿Cambiaste de Node a Bun? Actualiza CLAUDE.md en el mismo PR. Nunca dejes que deje de reflejar la realidad.
Mensual — limpiar lo obsoleto
Elimina las referencias a módulos borrados, actualiza las versiones de los paquetes y revisa las reglas que ya no tienen sentido.
Trimestral — revisión completa
Vuelve a leer todo con una mirada crítica: ¿qué sigue siendo cierto? ¿Qué cambió? ¿Qué falta?
CLAUDE.md en git
Versiona el CLAUDE.md en git como cualquier otro archivo. Esto crea un historial de cómo evolucionaron las instrucciones y permite revertir cambios si alguno provoca un comportamiento inesperado.
📋 Resumen del módulo
- • CLAUDE.md como instrucciones permanentes
- • Jerarquía de memoria explícita
- • Contexto conciso y priorizado
- • Convenciones en lenguaje mecánico
- • Seguridad: lo que nunca va en el CLAUDE.md
- • Frecuencia de revisión del documento
- • Escribe el CLAUDE.md de tu proyecto
- • Crea un .env.example con todas las variables
- • Configura el workflow de entrega de sesión
- • Programa una revisión trimestral en el calendario