Katas Hierarchical Claude Memory

Qué es

CLAUDE.md es la memoria persistente del agente, organizada en tres niveles que cargan en cascada:

• ~/.claude/CLAUDE.md — nivel usuario (preferencias personales, viven en el home, nunca en el repo).
• <repo>/CLAUDE.md — nivel equipo (convenciones compartidas, versionadas con el código).
• <repo>/<subpath>/CLAUDE.md — nivel módulo (reglas locales de un paquete o directorio).

Cada nivel se compone modularmente con @imports para mantener el archivo principal corto y caché-friendly. La regla más específica gana: repo/src/CLAUDE.md sobrescribe repo/CLAUDE.md, que a su vez se apila sobre ~/.claude/CLAUDE.md.

Frontera: memoria durable vs compaction

La memoria jerárquica conserva reglas y convenciones estables entre sesiones dentro de una superficie gobernada. Un bloque Claude API compaction conserva continuidad del transcript activo: resume estado, decisiones, evidencia y próximos pasos para solicitudes posteriores, pero no actualiza CLAUDE.md, no crea autoridad durable y puede ser reemplazado por una compaction posterior. [DOC][CONFIG]

Promueve contenido del resumen a memoria durable solo mediante una decisión separada, con fuente, alcance, privacidad y propietario. No promociones automáticamente hipótesis, output de tools, datos personales, instrucciones específicas de una tarea ni estado efímero. [CONFIG]

Por qué importa (falla que evita)

Repetir convenciones en cada prompt cuesta tokens y diverge entre miembros del equipo. Sin una fuente de verdad por nivel, el agente improvisa: cada sesión reinventa el estilo, los lints y las prohibiciones, y el equipo paga el costo en inconsistencia y retrabajo. Un CLAUDE.md monolítico de 2000 líneas con todo inline degrada la caché y dispersa la atención del modelo.

Modelo mental

• Más específico gana: repo/src/CLAUDE.md sobrescribe repo/CLAUDE.md; la precedencia es subpath > repo > user para el scope del proyecto.
• Frontera de privacidad: lo personal (preferencias del usuario) NO va en el repo; va en el home (~/.claude/CLAUDE.md).
• Modularidad con @imports: mantienen el archivo principal corto y caché-friendly; cada sección importa archivos chicos en docs/.
• Anti-monolito: un CLAUDE.md de 2000 líneas con todo inline degrada caché y dispersa atención. Modularizar y separar por nivel es la cura.
• Compaction es continuidad, no memoria: el bloque devuelto pertenece al transcript y debe volver a la API; la memoria jerárquica contiene solo conocimiento estable aprobado. [DOC][CONFIG]

Patrón correcto

# <repo>/CLAUDE.md  (nivel equipo, versionado)
## Style
@docs/style-guide.md

## Testing
@docs/testing-conventions.md

## Forbidden
- never run pip install without venv

# ~/.claude/CLAUDE.md  (nivel usuario, NO versionado)
- terse commits
- ruff over black

Anti-patrón

# <repo>/CLAUDE.md  (ANTI: monolítico + mezcla de niveles)
# 2000 líneas con TODO inline (style + testing + forbidden + ...)
# además incluye preferencias personales del autor:
- terse commits        # <- esto es del usuario, contamina el repo del equipo
- ruff over black      # <- diverge entre máquinas, no es convención de equipo

Argumento de certificación

Separación estricta usuario/equipo/módulo en CLAUDE.md y uso de @imports para modularidad y caché-friendliness. El agente certifica cuando: las preferencias personales viven solo en el home, las convenciones de equipo en el repo, las reglas locales en el módulo, y el archivo principal se mantiene corto vía @imports en lugar de inline monolítico.

Cuándo activar

• Diseñar o auditar la memoria persistente de un proyecto con CLAUDE.md.
• Decidir dónde colocar una convención (¿usuario, equipo o módulo?).
• Refactorizar un CLAUDE.md monolítico hacia @imports modulares.
• Resolver precedencia entre niveles que entran en conflicto.
• Decidir si un dato de un resumen de compaction sigue siendo continuidad transitoria o merece promoción gobernada a memoria durable.

Skills relacionadas

• katas-path-conditional-rules
• katas-context-cache-discipline
• katas-subagent-isolation

Packet

Capas del packet, cargables bajo demanda (disciplina ICM: una capa por vez, nunca todas juntas): knowledge/ cuerpo de conocimiento · prompts/ prompts listos · examples/ salida de ejemplo · agents/ subagentes del packet · templates/ plantilla de output.