Cap 8: Memory y CLAUDE.md

Sistema de memoria

Claude Code tiene dos sistemas de memoria complementarios:

1. CLAUDE.md — instrucciones explícitas escritas por el desarrollador
2. Auto Memory — conocimiento que Claude aprende y guarda automáticamente

CLAUDE.md en profundidad

Carga de archivos: Ancestor loading

Claude Code carga CLAUDE.md de la raíz del proyecto y de todos los directorios ancestros hasta el home:

~/.claude/CLAUDE.md          ← Global (siempre se carga)
~/proyectos/CLAUDE.md        ← Si existe, se carga
~/proyectos/mi-app/CLAUDE.md ← Proyecto (se carga al estar aquí)

Carga de archivos: Descendant loading

Cuando Claude accede a archivos en subdirectorios, carga los CLAUDE.md de esos directorios:

src/CLAUDE.md                ← Se carga cuando Claude lee archivos en src/
src/components/CLAUDE.md     ← Se carga cuando Claude trabaja en components/

Esto es útil para reglas específicas por módulo:

<!-- src/components/CLAUDE.md -->
# Reglas para componentes

- Usar functional components con hooks
- Props tipadas con interface, no type
- Exportar como named export, no default

Archivos soportados

Archivo	Compartible	Uso
CLAUDE.md	Sí (commiteable)	Reglas del equipo
CLAUDE.local.md	No (gitignored)	Reglas personales

Monorepo

En un monorepo, cada paquete puede tener su propio CLAUDE.md:

monorepo/
├── CLAUDE.md               ← Reglas globales del monorepo
├── packages/
│   ├── api/
│   │   └── CLAUDE.md       ← Reglas específicas del API
│   ├── web/
│   │   └── CLAUDE.md       ← Reglas específicas del frontend
│   └── shared/
│       └── CLAUDE.md       ← Reglas de la librería compartida

Auto Memory

Claude Code guarda automáticamente patrones y aprendizajes en un directorio de memoria persistente:

~/.claude/projects/<project-hash>/memory/
├── MEMORY.md               ← Archivo principal (siempre en contexto)
├── debugging.md             ← Notas de debugging
└── patterns.md              ← Patrones detectados

Qué guarda auto memory

• Comandos de build/test del proyecto
• Patrones de código confirmados
• Preferencias del usuario detectadas
• Soluciones a problemas recurrentes

Qué NO guarda

• Contexto de sesión temporal
• Información no verificada
• Datos que duplican CLAUDE.md

MEMORY.md

El archivo MEMORY.md se carga siempre en el contexto. Tiene un límite de ~200 líneas — las líneas después se truncan. Para notas extensas, usar archivos separados con links desde MEMORY.md.

Comandos de memoria

/memory

/memory          # Ver memorias actuales

Permite ver y editar las memorias guardadas por auto memory.

/rules

/rules           # Ver todas las reglas activas

Muestra todos los CLAUDE.md cargados y sus reglas.

Mejores prácticas

CLAUDE.md < 150 líneas

El archivo se carga completo en el contexto de cada sesión. Un archivo largo desperdicia tokens:

# CLAUDE.md — Proyecto Mi App

## Comandos
bun dev              # desarrollo
bun test             # tests
bun build            # producción

## Stack
- Astro 5 + React 19
- TypeScript strict
- Tailwind CSS
- Bun como runtime

## Convenciones
- Commits: feat: / fix: / refactor:
- Archivos < 150 líneas
- Tests junto al código (__tests__/)
- Arquitectura hexagonal

## Reglas
- No modificar /vendor
- No commitear .env
- Ejecutar tests antes de commit

Separar por responsabilidad

En lugar de un CLAUDE.md gigante, usa la jerarquía:

Regla	Ubicación
Preferencias personales	~/.claude/CLAUDE.md
Reglas del proyecto	./CLAUDE.md
Config personal del proyecto	./CLAUDE.local.md
Reglas del módulo API	src/api/CLAUDE.md
Reglas de componentes	src/components/CLAUDE.md

Auto memory vs CLAUDE.md

Aspecto	CLAUDE.md	Auto Memory
Quién lo escribe	Desarrollador	Claude Code
Cuándo se carga	Siempre	Siempre (MEMORY.md)
Compartible	Sí	No (por usuario)
Contenido	Reglas explícitas	Aprendizajes
Límite	~150 líneas recomendado	~200 líneas en MEMORY.md

---

Siguiente: Orchestration Workflow