Memoria y Contexto: CLAUDE.md y Reglas Modulares

Los dos sistemas de memoria

Claude Code tiene dos mecanismos de memoria, complementarios, y los dos se cargan al inicio de cada sesión. No son alternativas: resuelven cosas distintas.

CLAUDE.md es el manual de onboarding que escribís vos. Se carga desde el directorio actual y desde todos los de arriba, y los archivos se acumulan en vez de pisarse. Sus ubicaciones, de alcance más amplio a más específico:

Auto memory son las notas que Claude escribe solo, a partir de tus correcciones. Vive en ~/.claude/projects/<proyecto>/memory/, con un índice MEMORY.md y un archivo por tema. Guarda cuatro tipos de nota, marcados en el frontmatter con el campo type: user (tu rol y cómo trabajás), feedback (correcciones que le diste), project (decisiones y trabajo en curso que no se deducen del código) y reference (dónde encontrar información fuera del proyecto).

Está activada por defecto. Se prende y apaga con el comando /memory, o con autoMemoryEnabled en settings.json. Del índice MEMORY.md se cargan las primeras 200 líneas o 25 KB, lo que se alcance primero; los archivos por tema los lee bajo demanda.

Cómo escribir un buen CLAUDE.md

Todo lo que ponés en CLAUDE.md consume tokens de la ventana de contexto en cada interacción. Un archivo inflado no solo desperdicia presupuesto: reduce la calidad de las respuestas, porque Claude tiene más instrucciones que compiten por su atención y las sigue de forma menos consistente.

Regla simple: incluí solo lo que causaría errores si faltara. Todo lo demás es ruido.

Tamaño de referencia: apuntá a un máximo de ~200 líneas. Si crece más, es señal de que necesitás dividir con reglas modulares (.claude/rules/, ver más abajo) o con importaciones @.

Qué sí incluir:

• Comandos exactos de build, test y lint (Claude los va a ejecutar literalmente).
• Decisiones de arquitectura que afectan cómo se escribe el código.
• Convenciones de código específicas del proyecto.
• Variables de entorno y servicios requeridos.
• Trampas comunes o patrones que Claude debe evitar.
• Estructura de monorepo: qué paquete es responsable de qué.

Qué NO incluir:

• Cosas que Claude ya sabe (sintaxis estándar, APIs comunes).
• Recordatorios obvios (“escribí código limpio”).
• Guías de estilo extensas que ya aplica un linter.
• Documentación completa de APIs externas (mejor referenciarlas con @).

Nunca le pidas a un LLM que haga el trabajo de un linter. Los LLMs son costosos y lentos comparados con ESLint o Prettier. Si el código ya sigue una guía de estilo, Claude tiende a respetar los patrones existentes por aprendizaje en contexto, sin que haga falta indicárselo. Para lo que un linter no cubre — o para forzar el formato siempre, sin depender de que el modelo lo infiera — conviene un Hook que corra el formatter automáticamente (Skills, Subagentes y Hooks).

Cómo escribir las reglas:

# ❌ Mal (sugerencia, no verificable)
- Estaría bueno manejar bien los errores de negocio
- Preferimos que los controllers no tengan lógica de negocio

# ✅ Bien (imperativo, específico, verificable)
- Los errores de negocio se lanzan como `AppError({ code, status })`,
  nunca `throw new Error(...)` genérico
- Los controllers solo parsean el request y llaman al service — la
  lógica de negocio vive únicamente en services/
- Los archivos de test van junto al módulo que testean, con sufijo
  `.test.ts`
- Las rutas de la API van en src/routes/, un archivo por recurso

Usá IMPORTANT o YOU MUST con moderación: reservalos para 2-3 reglas críticas cuyo incumplimiento genera problemas graves. Si todo está marcado como importante, nada lo es.

- IMPORTANT: Nunca reprocesés ni canceles un pago manualmente desde
  el código. Los reembolsos pasan siempre por el servicio de pagos,
  nunca con un UPDATE directo a la tabla.
- YOU MUST ejecutar `npm run lint:fix` antes de dar un cambio
  por terminado.

Reglas modulares con .claude/rules/

Cuando CLAUDE.md se vuelve muy grande, dividilo en archivos temáticos dentro de .claude/rules/ (a nivel proyecto o global). Cada archivo puede restringirse a ciertos directorios o extensiones usando patrones glob, así solo se carga cuando es relevante para lo que estás tocando.

Sintaxis de patrones glob

Un glob es una plantilla con comodines que se compara con una ruta de archivo: o encaja, o no encaja. No es una regex — el punto . es literal y no hay cuantificadores como + o {3,5}.

Ejemplos que vas a usar seguido:

---
paths:
  - "src/**/*.{jsx,tsx}"                     # componentes React en src
  - "db/migrations/[0-9][0-9][0-9][0-9]_*.sql"  # migraciones numeradas
  - "**/__tests__/**"                        # cualquier cosa dentro de un __tests__
---

Errores típicos:

1. Confundir * con **. src/*.ts no cubre subcarpetas; para eso necesitás src/**/*.ts.
2. ** mal aislado. src**/foo no funciona como globstar; tiene que ir solo entre barras: src/**/foo.
3. Pensar que son regex. app.js en un glob es exactamente app.js, punto literal incluido.
4. Olvidar los archivos ocultos. .env, .gitignore suelen quedar fuera de patrones genéricos como *.json; si los querés incluir, sé explícito con .* o **/.*.

Estos mismos globs se usan en tres lugares de Claude Code: el campo paths de las reglas de .claude/rules/, las reglas de permisos (Permisos y seguridad operativa) y el campo paths de una skill (Skills, Subagentes y Hooks) — aprenderlos una vez alcanza para los tres.

Ver y editar la memoria

El comando /memory lista tus archivos CLAUDE.md y CLAUDE.local.md por scope, permite abrirlos en el editor, prender o apagar auto memory, y abrir la carpeta de memoria automática. Para verificar qué se cargó realmente en la sesión actual, el comando es /context, que muestra los archivos bajo Memory files.

Dos cosas que conviene saber:

• AGENTS.md no se lee. Claude Code lee CLAUDE.md. Si el repo ya usa AGENTS.md para otros agentes, la solución recomendada es un CLAUDE.md que lo importe con @AGENTS.md y agregue debajo lo específico de Claude.
• En monorepos, claudeMdExcludes permite saltear los CLAUDE.md de otros equipos que quedan en el árbol de directorios por encima del tuyo.

Documentación relacionada: referencia oficial de memoria y CLAUDE.md.