CLAUDE.md y memoria persistente

Si los hooks son el sistema nervioso del agente, CLAUDE.md es su cerebro de proyecto y la memoria persistente su biografía profesional. Bien diseñadas, hacen que Claude Code se comporte como un colega que conoce tu equipo desde hace años, no como un consultor que llega cada lunes a empezar de cero.

Objetivos

• Entender los tres niveles de CLAUDE.md (usuario, repo, subdirectorio).
• Escribir un CLAUDE.md que aporte valor real y no ruido.
• Usar los 4 tipos de memoria persistente (user, feedback, project, reference).
• Aplicar la disciplina de "verificar antes de actuar sobre la memoria".
• Aplicar context engineering: qué cargar, qué dejar fuera, cuándo compactar.

11.1 Las tres capas de CLAUDE.md

Claude Code carga automáticamente CLAUDE.md de tres lugares al abrir una sesión. Por orden de precedencia (la más cercana gana en conflicto):

Las tres se mergean. Si el repo dice "modelo Sonnet por defecto" y tú quieres Opus, escribe el override en ~/.claude/CLAUDE.md sin tocar el del equipo.

11.2 El CLAUDE.md del repo · estructura de oro

Un CLAUDE.md bueno tiene 5 secciones, en orden:

# CLAUDE.md · <Nombre del proyecto>

> Repo: org/repo
> Web: https://...
> Stack: ... (1 línea)

---

## TL;DR

3-5 líneas. Qué hace el proyecto, qué stack usa, dónde se despliega.
Si el agente solo lee esta sección, debe poder decidir si una tarea
encaja o no.

---

## Reglas de oro

5-10 reglas que NADIE puede romper sin hablarlo. Numeradas.

1. **Despliegue**: solo via /root/qlc-publish.sh. NUNCA scp directo.
2. **Secretos**: nada en .env commiteado. Lista en .gitignore.
3. **SEO**: no tocar canonical, title, description sin permiso.
4. ...

---

## Comandos clave

```bash
npm run dev      # arranca local (puerto 4174)
npm test         # tests con vitest
npm run build    # compila a dist/
```

---

## Arquitectura mínima

- src/api/        endpoints REST
- src/services/   lógica de negocio (sin Express)
- src/db/         schema y migraciones
- packages/web/   front en Next.js (ver su CLAUDE.md propio)

---

## Pitfalls

- El test runner inyecta MOCK_DB=true; los tests directos sin esa env
  rompen.
- src/utils/dates.ts usa Luxon, no date-fns. NO mezclar.
- El despliegue a IONOS exige `cp -r repo/* staging/` antes del
  `deploy.sh`. Si lo saltas, despliega versión vieja.

11.3 Qué meter y qué NO en CLAUDE.md

Métrica práctica

Un buen CLAUDE.md cabe en 100-200 líneas. Si pasas de 400, conviene partirlo en sub-CLAUDE.md por subdirectorios o factorizar a documentos referenciados desde el principal.

11.4 Generar el CLAUDE.md inicial

Hay tres formas de empezar:

A · /init

Dentro de Claude Code, este comando lee el repo, hace git log, mira el package.json y propone un CLAUDE.md de partida. Te lleva del 0% al 60%.

B · A mano desde plantilla

Si tu equipo ya tiene varios repos, copia el CLAUDE.md de uno y adáptalo. La plantilla del equipo aporta consistencia.

C · Co-creado

Lo más eficaz a medio plazo: ejecuta /init, revisa, y luego itera con el agente:

> Lee este CLAUDE.md generado. Pregúntame: 1) qué reglas faltan que
  ya hayan provocado un bug, 2) qué pitfalls ya conoce el equipo,
  3) qué partes son demasiado verbose. Iteramos hasta que esté listo.

El resultado tiene la voz del equipo, no de Anthropic.

11.5 Memoria persistente — los 4 tipos

Más allá del CLAUDE.md estático, Claude Code mantiene memoria entre sesiones en:

~/.claude/projects/<path-codificado>/memory/

Cada entrada es un fichero Markdown con frontmatter. Hay 4 tipos:

Estructura interna de la carpeta memory/

~/.claude/projects/myproyecto/memory/
├── MEMORY.md            ← índice (una línea por entrada)
├── user_role.md
├── feedback_tests_no_mock.md
├── project_q1_goals.md
└── reference_dashboards.md

El índice MEMORY.md:

- [Rol del usuario](user_role.md) — backend senior, ahora en frontend
- [Tests sin mocks](feedback_tests_no_mock.md) — política tras incident Q3
- [Goals Q1](project_q1_goals.md) — entrega passkeys el 31/3
- [Dashboards oncall](reference_dashboards.md) — Grafana endpoints

11.6 Cuándo escribir memoria y cuándo NO

✓ Escribe memoria cuando:

• El usuario corrige tu enfoque y la lección aplicará a futuras sesiones.
• El usuario valida una decisión no obvia ("sí, ese refactor era el correcto").
• Aprendes algo del proyecto que NO está en CLAUDE.md ni en código.
• Te dicen explícitamente "recuerda esto".

✗ NO escribas memoria cuando:

• La información se ve leyendo el código (es derivable).
• Es del contexto de la sesión actual (eso es contexto, no memoria).
• Ya está en CLAUDE.md (duplicación = drift).
• Son PII, secretos, datos personales.
• Cambia rápido (no aporta a futuras sesiones).

Ejemplo de entrada de memoria bien hecha

---
name: feedback-tests-no-mock
description: No mockear DB en tests de integración. Política tras
  incident del Q3 2025 donde mocks pasaron y prod falló por
  diferencias de tipos en JSONB.
type: feedback
date: 2026-01-15
---

Los tests de integración deben pegar a una BD real (postgres en
docker). Razón: en Q3 2025 una migración pasó tests con mocks de
JSONB y rompió producción al introducirse un campo con tipos
ambiguos.

**Cómo aplicar:** rechazar PRs que mockeen la conexión a DB en
suites de integración. Tests unitarios sí pueden mockear, pero
deben ir en archivos *.unit.test.ts.

11.7 Verificar antes de actuar

Disciplina crítica: la memoria es un snapshot. Lo que era cierto al guardarla puede haber cambiado. Antes de aplicar una recomendación basada en memoria:

• Si menciona un fichero → comprueba que existe (ls, find, Read).
• Si menciona una función → grep para confirmar.
• Si menciona una política → pregúntate si sigue vigente.
• Si la entrada tiene más de 3 meses, revísala antes de invocarla.

"La memoria dice X" ≠ "X es cierto ahora".

Skill consolidate-memory

Anthropic publica una skill que hace una pasada reflexiva sobre tu memory/: detecta duplicados, fusiona, elimina obsoletos, actualiza el índice. Cada 2-3 meses lánzala:

> /consolidate-memory

11.8 Context engineering · qué cargar y qué no

El "context engineering" es la disciplina de decidir qué entra al contexto del modelo y qué no. Cuatro decisiones recurrentes:

1 · CLAUDE.md vs documentación referenciada

Lo crítico va en CLAUDE.md (siempre cargado). Lo extenso va en docs/ y CLAUDE.md hace referencia ("ver docs/architecture.md"). El modelo lee docs/ bajo demanda solo cuando importa.

2 · Memoria vs contexto de sesión

Cosas que aplican en futuras sesiones → memoria. Cosas que aplican AHORA → solo contexto. No mezcles.

3 · Cuándo /clear y cuándo /compact

• /clear: cambiamos de tarea. Empezamos limpio.
• /compact: misma tarea pero contexto saturado. Resumimos lo viejo y conservamos progreso.

4 · Sub-agentes para no contaminar

Si necesitas leer 80 archivos para encontrar algo, delega a un sub-agente. Tu agente principal recibe el resumen, no las 80 lecturas. Tu contexto principal queda limpio para razonar.

Práctica · 1.5 horas

Test de comprensión

Resumen del módulo

• Tres capas de CLAUDE.md: subdirectorio > repo > usuario.
• 5 secciones de oro: TL;DR, reglas, comandos, arquitectura, pitfalls.
• Memoria persistente en 4 tipos: user, feedback, project, reference.
• Verifica antes de actuar — la memoria es snapshot, no verdad presente.
• Context engineering: lo crítico en CLAUDE.md, lo extenso en docs referenciada.

Siguiente módulo: el Claude Agent SDK — construir agentes propios apoyados en estos primitivos.