Módulo 3: CLAUDE.md y el sistema de memoria

Módulo 3: CLAUDE.md y el Sistema de Memoria

Descripción

Has instalado Claude Code. Verificaste que funciona con /doctor. Configuraste tu modelo preferido y entiendes la diferencia entre Opus 5 y Sonnet 5. Claude Code está listo en tu terminal. Ahora viene el paso más importante de toda la guía: darle a Claude contexto sobre tu proyecto.

Un agente de código es tan bueno como el contexto que le das. Sin contexto, Claude Code es un developer senior con amnesia — tiene habilidades extraordinarias pero no sabe nada sobre tu proyecto, tus convenciones, tu stack, ni tus reglas. Con buen contexto, es un developer senior que lleva meses en tu equipo y conoce cada rincón del codebase.

Este módulo te enseña a configurar ese contexto de forma profesional. CLAUDE.md es el archivo que hace la diferencia entre resultados mediocres y resultados de nivel producción. No es un archivo opcional — es el fundamento sobre el que se construye todo lo que viene después.

Dónde estamos en la guía

Módulo 01: Qué es Claude Code ✅
Módulo 02: Instalación y setup ✅
Módulo 03: CLAUDE.md y memoria ← ESTÁS AQUÍ
Módulo 04: Workflow agentic
Módulo 05: Skills y Hooks
Módulo 06: Subagents
Módulo 07: Integraciones (Git, SDK, Remote Control)
Módulo 08: Proyecto integrador

En el Módulo 01 entendiste qué es Claude Code y por qué lidera el espacio. En el Módulo 02 lo instalaste y configuraste. Ahora, en el Módulo 03, pasamos de instalar a configurar la inteligencia del agente. Todo lo que viene después — workflow agentic, skills, hooks, subagents — funciona mejor cuando CLAUDE.md está bien hecho.

El Mental Model Fundamental

CLAUDE.md es el equivalente a configurar tu IDE antes de escribir código.

Piensa en lo que pasa cuando abres VS Code en un proyecto nuevo sin configurar nada: no tiene el formatter correcto, no sabe qué linter usar, no conoce tus atajos, no sabe dónde están los tests. Funciona, sí — pero funciona mal. La primera hora la pasas configurando .eslintrc, prettier.config, tsconfig.json, extensions, settings.

CLAUDE.md es exactamente eso, pero para tu agente de código. Es la configuración que le dice a Claude:

Qué tecnologías usas
Cómo se estructura el proyecto
Qué convenciones seguir
Qué comandos ejecutar
Qué NO hacer

Si no lo configuras bien, cada interacción con Claude Code es una lotería. A veces acierta, a veces no. Si lo configuras bien, Claude Code produce código consistente que respeta tus convenciones desde el primer prompt.

La analogía precisa

Sin CLAUDE.md:
→ Developer senior que acaba de llegar a la empresa
→ Tiene habilidades pero no conoce las reglas de tu equipo
→ Cada tarea requiere que le expliques todo desde cero
→ Produce código que "funciona" pero no encaja con el resto

Con CLAUDE.md profesional:
→ Developer senior que lleva 6 meses en tu equipo
→ Conoce el stack, las convenciones, la arquitectura
→ Solo necesitas decirle QUÉ hacer, no CÓMO
→ Produce código consistente con el resto del proyecto

El impacto real

La diferencia no es teórica. Observa este ejemplo:

Sin CLAUDE.md:

Tú: "Crea un endpoint para listar productos con paginación"

Claude: [usa Express aunque tu proyecto es FastAPI]
Claude: [usa snake_case aunque tu proyecto usa camelCase]
Claude: [pone el archivo en routes/ aunque tu proyecto usa routers/]
Claude: [usa print() para logging aunque tienes loguru configurado]

Con CLAUDE.md profesional:

Tú: "Crea un endpoint para listar productos con paginación"

Claude: [usa FastAPI porque CLAUDE.md dice "Stack: FastAPI"]
Claude: [usa snake_case porque CLAUDE.md dice la convención]
Claude: [pone el archivo en src/routers/ siguiendo la estructura]
Claude: [usa loguru porque CLAUDE.md dice "Logging: loguru"]

Mismo prompt. Resultados radicalmente diferentes. La diferencia es CLAUDE.md.

El error más común

La mayoría de usuarios hacen esto:

# Instalan Claude Code
curl -fsSL https://claude.ai/install.sh | bash

# Abren su proyecto
cd my-project
claude

# Inmediatamente piden tareas
> "Agrega autenticación a mi app"

No crean CLAUDE.md. Claude no sabe qué framework usan, qué convenciones tienen, ni qué estructura de archivos sigue el proyecto. El resultado es código genérico que requiere 5-10 mensajes de corrección para encajar.

Un profesional hace esto:

# Instalan Claude Code
curl -fsSL https://claude.ai/install.sh | bash

# Crean CLAUDE.md ANTES de hacer cualquier otra cosa
# (5-10 minutos que ahorran horas)

# Abren su proyecto
cd my-project
claude

# Claude lee CLAUDE.md automáticamente
# Ahora sí, la primera tarea
> "Agrega autenticación a mi app"

# Claude sabe el framework, las convenciones, la estructura
# Resultado: código que encaja desde el primer intento

Los 5-10 minutos que inviertes creando CLAUDE.md se pagan con creces en cada sesión posterior.

Objetivo del Módulo

Al completar este módulo, serás capaz de:

✅ Crear un CLAUDE.md profesional bien estructurado (<200 líneas)
✅ Entender y aplicar los 4 scopes oficiales de CLAUDE.md (Managed / Project / User / Local) y los 6 niveles pedagógicos de precedencia
✅ Organizar reglas modulares con .claude/rules/ (con path-specific frontmatter)
✅ Usar imports con @path para referenciar archivos externos en CLAUDE.md
✅ Usar CLAUDE.local.md y ~/.claude/CLAUDE.md (User scope) para preferencias personales no compartidas
✅ Comprender cómo funciona auto memory y qué aprende Claude de tus correcciones
✅ Configurar settings en los scopes global, project, y local
✅ Diagnosticar de dónde viene un comportamiento inesperado de Claude Code
✅ Diseñar la jerarquía de CLAUDE.md apropiada para tu tipo de proyecto

Por Qué Este Módulo es el Diferenciador

Si analizas los cursos de Claude Code que existen en el mercado, ninguno cubre el sistema de memoria completo:

La mayoría menciona CLAUDE.md como "un archivo de configuración" y pasan al siguiente tema
Ninguno explica los 4 scopes oficiales (Managed / Project / User / Local) ni los 6 niveles pedagógicos de precedencia
Ninguno cubre .claude/rules/ con path-specific rules ni los imports con @path
Ninguno cubre CLAUDE.local.md ni ~/.claude/CLAUDE.md (User scope) para preferencias personales
Ninguno explica la relación entre auto-memory, CLAUDE.md, .claude/rules/, y settings

Este módulo va profundo en cada uno de estos temas. Al completarlo, vas a entender el sistema de memoria de Claude Code mejor que el 99% de los usuarios.

Los 3 pilares del sistema de memoria

┌─────────────────────────────────────────────────┐
│           SISTEMA DE MEMORIA                    │
│                                                 │
│  ┌─────────────┐  ┌──────────────┐  ┌────────┐ │
│  │  CLAUDE.md   │  │  Auto Memory │  │Settings│ │
│  │  (explícito) │  │  (implícito) │  │(config)│ │
│  │              │  │              │  │        │ │
│  │ Tú escribes  │  │ Claude       │  │ Tú     │ │
│  │ las reglas   │  │ aprende de   │  │ defines│ │
│  │ del proyecto │  │ correcciones │  │ scopes │ │
│  └─────────────┘  └──────────────┘  └────────┘ │
│                                                 │
│  6 niveles de jerarquía determinan              │
│  qué tiene prioridad sobre qué                  │
│                                                 │
└─────────────────────────────────────────────────┘

CLAUDE.md — Lo que tú le dices explícitamente sobre el proyecto (cápsula 02)
Jerarquía de 6 niveles — Cómo se resuelven conflictos entre fuentes de contexto (cápsula 03)
Auto memory y Settings — Lo que Claude aprende solo + tu configuración de permisos (cápsulas 04 y 05)

Prerequisitos

Conocimiento requerido:

✅ Módulo 02 completado (Claude Code instalado y funcionando)
✅ Familiaridad básica con Markdown (headers, listas, bloques de código)
✅ Familiaridad básica con terminal

Para la práctica:

✅ Un proyecto existente donde practicar (cualquier lenguaje)
✅ O una carpeta nueva con al menos un package.json, requirements.txt, o equivalente

Verificación rápida:

Antes de continuar, verifica que Claude Code funciona ejecutando:

claude

Si se abre la interfaz interactiva, estás listo. Si no, revisa el Módulo 02.

Si no tienes un proyecto:

Crea uno mínimo para practicar:

mkdir my-practice-project
cd my-practice-project
npm init -y
# o: pip install fastapi && echo "fastapi" > requirements.txt

Lo importante es tener una carpeta con algo de estructura donde Claude pueda operar.

Roadmap del Módulo

Este módulo tiene 5 cápsulas progresivas:

Cápsula 01 — Introducción al módulo (esta cápsula)

Contexto, mental model, y roadmap. Entiendes por qué CLAUDE.md importa y qué vas a aprender.

Cápsula 02 — CLAUDE.md profesional

El archivo más importante de tu proyecto cuando usas Claude Code. Qué incluir, qué omitir, estructura ideal (<200 líneas), 3 ejemplos comparativos (principiante, profesional, inflado), y la diferencia dramática entre trabajar con y sin CLAUDE.md.

Cápsula 03 — Jerarquía de 6 niveles de memoria

Los 6 niveles de contexto que Claude Code usa para tomar decisiones: desde el training data del modelo hasta el contexto de la conversación actual. Cómo se superponen, quién controla cada nivel, y cómo resolver contradicciones.

Cápsula 04 — Auto memory y settings

Cómo Claude aprende automáticamente de tus correcciones (auto memory), dónde se guarda, y cómo gestionarla. Los 3 scopes de settings (global, project, local) y qué configurar en cada uno.

Cápsula 05 — CLAUDE.local.md y User CLAUDE.md

Los dos mecanismos para preferencias personales: CLAUDE.local.md (project-local, en .gitignore) y ~/.claude/CLAUDE.md (User scope, aplica a todos tus proyectos). Cuándo usar cada uno, cómo interactúan con la jerarquía, y patterns para worktrees.

Mapa de progresión

Cápsula 01 (esta)     → Mental model y contexto
Cápsula 02            → CLAUDE.md: el archivo que cambia todo
Cápsula 03            → 6 niveles: cómo Claude prioriza contexto
Cápsula 04            → Auto memory + settings: lo implícito
Cápsula 05            → CLAUDE.local.md: tu toque personal

Dificultad: ⭐ ──────────────────────────▶ ⭐⭐⭐

Las cápsulas 02 y 03 son fundamentales — sin CLAUDE.md y sin entender la jerarquía, todo lo demás se construye sobre una base débil. Las cápsulas 04 y 05 son complementarias — optimizan tu setup para uso profesional.

Qué Construirás en Este Módulo

A lo largo de las 5 cápsulas, producirás:

Un CLAUDE.md profesional para tu proyecto real (o para el proyecto de práctica)
CLAUDE.md de subdirectorio para un directorio específico (e.g., /tests/)
CLAUDE.local.md con tus preferencias personales de desarrollo
Configuración de settings en los 3 scopes (global, project, local)
Auto memories generadas a través de correcciones durante los ejercicios

Al final del módulo, tu proyecto tendrá un sistema de memoria completo y profesional que transformará la calidad de las respuestas de Claude Code.

Conexión con el Proyecto Integrador

En el Módulo 08, construirás una herramienta CLI completa usando Claude Code. El CLAUDE.md que aprendes a crear en este módulo es exactamente el que usarás para ese proyecto:

Defines el stack — Python/TypeScript, dependencias, framework CLI
Estableces convenciones — naming, estructura de archivos, patterns
Configuras comandos — cómo buildear, testear, ejecutar
Agregas reglas — qué no tocar, qué patterns evitar
Personalizas con CLAUDE.local.md — tus preferencias durante el desarrollo

Un buen CLAUDE.md para el proyecto integrador puede reducir el tiempo de desarrollo significativamente, porque Claude Code entiende el proyecto desde el primer prompt.

Un Vistazo al Antes y Después

Para que visualices el impacto de este módulo, aquí tienes cómo se ve tu proyecto antes y después de completar las 5 cápsulas:

Antes del módulo (tu proyecto hoy)

my-project/
├── package.json
├── src/
│   ├── index.ts
│   └── ...
└── tests/
    └── ...

Claude Code: no tiene contexto
→ Adivina el stack
→ Adivina las convenciones
→ Adivina la estructura
→ No sabe qué comandos usar
→ No sabe qué NO hacer

Después del módulo (tu proyecto configurado)

my-project/
├── CLAUDE.md                  ← Reglas del proyecto (compartido)
├── CLAUDE.local.md            ← Tus preferencias (personal)
├── .claude/
│   ├── settings.json          ← Permisos del equipo (compartido)
│   └── settings.local.json   ← Tus permisos extras (personal)
├── .gitignore                 ← Incluye CLAUDE.local.md
├── package.json
├── src/
│   ├── index.ts
│   └── ...
└── tests/
    ├── CLAUDE.md              ← Convenciones de testing
    └── ...

Claude Code: tiene contexto completo
→ Conoce el stack (CLAUDE.md)
→ Sigue las convenciones (CLAUDE.md)
→ Respeta la estructura (CLAUDE.md)
→ Ejecuta comandos sin preguntar (settings)
→ Sabe qué NO hacer (reglas en CLAUDE.md)
→ Te responde en tu idioma (CLAUDE.local.md)
→ Aprende de tus correcciones (auto memory)

La diferencia es tangible desde la primera sesión después de configurar.

Conceptos Clave que Verás

CLAUDE.md

El archivo Markdown en la raíz de tu proyecto que le da contexto persistente a Claude Code. Se carga al inicio de cada sesión y sobrevive a /compact y /clear. Es tu herramienta #1 para controlar la calidad del output.

4 Scopes de CLAUDE.md

La documentación oficial organiza CLAUDE.md en 4 scopes: Managed policy (organización), Project (./CLAUDE.md o ./.claude/CLAUDE.md), User (~/.claude/CLAUDE.md), y Local (./CLAUDE.local.md). Scopes más específicos ganan en conflictos.

Jerarquía conceptual (6 niveles pedagógicos)

Además de los 4 scopes, conceptualmente hay 6 fuentes que influyen en cada respuesta de Claude — desde el training data hasta la conversación actual. Mantenemos este framing pedagógico porque ayuda a entender cómo Claude prioriza información.

`.claude/rules/` — reglas modulares

Directorio para organizar reglas por topic con YAML frontmatter paths. Rules con paths solo se cargan cuando Claude trabaja con archivos que matchean el pattern — ahorras contexto.

Imports con `@path`

CLAUDE.md puede importar otros archivos con @path/to/file. Útil para referenciar README, package.json, o docs extensos sin duplicar contenido.

Auto memory

Claude Code aprende de tus correcciones automáticamente. Si le dices "no uses var, usa const", lo recuerda para sesiones futuras. Se guarda en ~/.claude/projects/<project>/memory/ con un MEMORY.md como índice. Requiere Claude Code v2.1.59+.

Settings (3 scopes)

Configuración explícita en 3 niveles: global (todas tus máquinas), project (compartido con el equipo), y local (solo para ti). Controla permisos, herramientas permitidas, y comportamiento.

CLAUDE.local.md y User CLAUDE.md

Dos mecanismos para preferencias personales: CLAUDE.local.md (project-local, no se commitea) y ~/.claude/CLAUDE.md (user-wide, aplica a todos tus proyectos).

Versiones y Compatibilidad

Este módulo cubre:

Claude Code 2.0+
Opus 5 (1M token context window)
Sonnet 5 (1M token context window)

Features cubiertos:

✅ CLAUDE.md (project root y subdirectorios)
✅ CLAUDE.local.md (preferencias personales)
✅ Auto memory (aprendizaje de correcciones)
✅ Settings (global, project, local scopes)
✅ Jerarquía de 6 niveles de memoria

Nota sobre cambios:

Claude Code se actualiza frecuentemente (~35 releases en 7 semanas, enero-febrero 2026). Los conceptos de este módulo son estables — CLAUDE.md, la jerarquía de memoria, y el sistema de settings son fundamentales a la arquitectura de Claude Code. Los detalles de implementación pueden evolucionar; los principios no.

Los 6 Niveles en un Vistazo

Antes de entrar en detalle (cápsula 03), aquí tienes un preview de la jerarquía completa para que tengas el mapa mental:

PRIORIDAD ALTA (gana en conflictos)
         ▲
         │
  6. Tu conversación actual
  5. CLAUDE.md en subdirectorios (e.g., /tests/)
  4. CLAUDE.md en la raíz del proyecto
  3. CLAUDE.md de la organización (enterprise)
  2. System prompt de Anthropic
  1. Training data del modelo
         │
         ▼
PRIORIDAD BAJA (se sobreescribe)

Nivel	Quién lo controla	Ejemplo
6. Conversación	Tú, en cada mensaje	"Para este archivo, usa camelCase"
5. CLAUDE.md subdir	Tú, en cada directorio	"En tests/, any es aceptable"
4. CLAUDE.md proyecto	Tú, en la raíz	"Stack: FastAPI, snake_case"
3. CLAUDE.md enterprise	Admin de la org	"No usar eval(), logging JSON"
2. System prompt	Anthropic	"Pedir confirmación para rm"
1. Training data	Anthropic (entrenamiento)	"Python usa snake_case"

Lo esencial: Los niveles superiores ganan cuando hay conflicto. Tu conversación siempre tiene la última palabra. CLAUDE.md te da el control más importante: las reglas persistentes del proyecto.

La cápsula 03 cubre cada nivel en profundidad con ejemplos prácticos.

Resumen

Este módulo es el fundamento de todo tu trabajo con Claude Code. La diferencia entre un usuario casual y un profesional se reduce a esto: el profesional configura el contexto antes de trabajar.

Lo que aprendiste en esta cápsula:

El agente es tan bueno como el contexto que le das
CLAUDE.md es el equivalente a configurar tu IDE — si no lo haces bien, todo sufre
El sistema de memoria tiene 3 pilares: CLAUDE.md, auto memory, y settings
Hay 6 niveles de jerarquía que determinan cómo Claude prioriza el contexto
CLAUDE.local.md permite preferencias personales sin afectar al equipo
Este módulo es el diferenciador: ningún otro recurso cubre esto en profundidad

Siguiente cápsula: 02 - CLAUDE.md profesional — cómo crear el archivo más importante de tu proyecto cuando usas Claude Code.

Recursos Adicionales

Documentación oficial

Claude Code Memory — Sistema de memoria, CLAUDE.md, auto memory, jerarquía completa
Claude Code Settings — Configuración de scopes: global, project, local
Claude Code Best Practices — Workflows recomendados y gestión de contexto

Complementarios

Claude Code Overview — Arquitectura general y capabilities
Claude Code CLI Reference — Referencia de comandos y flags
Claude Code Interactive Mode — Shortcuts y gestión de sesiones

← AnteriorModel Selection y Effort Level Siguiente →CLAUDE.md Profesional: El Archivo que Cambia Todo

Módulo 3: CLAUDE.md y el Sistema de Memoria

Módulo 3: CLAUDE.md y el Sistema de Memoria

Descripción

Dónde estamos en la guía

El Mental Model Fundamental

La analogía precisa

El impacto real

El error más común

Objetivo del Módulo

Por Qué Este Módulo es el Diferenciador

Los 3 pilares del sistema de memoria

Prerequisitos

Conocimiento requerido:

Para la práctica:

Verificación rápida:

Si no tienes un proyecto:

Roadmap del Módulo

Cápsula 01 — Introducción al módulo (esta cápsula)

Cápsula 02 — CLAUDE.md profesional

Cápsula 03 — Jerarquía de 6 niveles de memoria

Cápsula 04 — Auto memory y settings

Cápsula 05 — CLAUDE.local.md y User CLAUDE.md

Mapa de progresión

Qué Construirás en Este Módulo

Conexión con el Proyecto Integrador

Un Vistazo al Antes y Después

Antes del módulo (tu proyecto hoy)

Después del módulo (tu proyecto configurado)

Conceptos Clave que Verás

CLAUDE.md

4 Scopes de CLAUDE.md

Jerarquía conceptual (6 niveles pedagógicos)

.claude/rules/ — reglas modulares

Imports con @path

Auto memory

Settings (3 scopes)

CLAUDE.local.md y User CLAUDE.md

Versiones y Compatibilidad

Features cubiertos:

Nota sobre cambios:

Los 6 Niveles en un Vistazo

Resumen

Recursos Adicionales

Documentación oficial

Complementarios

`.claude/rules/` — reglas modulares

Imports con `@path`