Jerarquía de Memoria en Claude Code

Descripción

Claude Code no toma contexto de un solo lugar. Hay múltiples fuentes que influyen en cada respuesta, con prioridades distintas. Cuando dos fuentes se contradicen, Claude sigue la de mayor prioridad. Entender esta jerarquía es entender cómo piensa Claude.

En esta cápsula vas a aprender los 4 scopes de CLAUDE.md, el rol de .claude/rules/ para reglas modulares, los imports con @path, y los niveles conceptuales de precedencia. Al final, entenderás exactamente por qué Claude toma cada decisión que toma.

Nota: En versiones anteriores de esta guía hablábamos de "6 niveles" (incluyendo training data y system prompt como niveles 1-2). Mantenemos ese framing pedagógico, pero la documentación oficial se enfoca en los 4 scopes de CLAUDE.md que tú controlas: Managed policy, Project, User, y Local. Estos son los niveles donde tomas decisiones.

Los 4 Scopes de CLAUDE.md (oficial)

La documentación oficial de Claude Code organiza la jerarquía en 4 scopes ordenados de más general a más específico:

Cómo se resuelven conflictos: Locations más específicas ganan sobre las más amplias. Dentro del mismo scope, CLAUDE.local.md se carga DESPUÉS de CLAUDE.md, así que tus notas personales son lo último que Claude lee en ese nivel.

Cómo se descubren: Claude camina hacia arriba desde tu directorio actual, buscando CLAUDE.md y CLAUDE.local.md en cada nivel. Todos los encontrados se concatenan, no se sobreescriben.

.claude/rules/ — reglas modulares por topic

Para proyectos grandes, puedes dividir las instrucciones en archivos modulares dentro de .claude/rules/:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Instrucciones principales
│   └── rules/
│       ├── code-style.md   # Estilo de código
│       ├── testing.md      # Convenciones de tests
│       └── security.md     # Requerimientos de seguridad

Ventaja clave: los archivos en .claude/rules/ pueden tener YAML frontmatter con paths para cargarse SOLO cuando Claude trabaja con archivos que matchean el pattern:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- Todos los endpoints deben incluir validación de input
- Usar formato estándar de error response
- Incluir comentarios de OpenAPI

Esta rule solo se carga cuando Claude lee o edita archivos en src/api/. Para otros archivos no se carga, ahorrando contexto.

Patterns soportados:

User-level rules: ~/.claude/rules/ aplica a todos tus proyectos. Útil para preferencias personales no específicas del proyecto.

Imports con @path/to/file

CLAUDE.md puede importar otros archivos con la syntax @path/to/import. Los archivos importados se expanden e incluyen en contexto al inicio:

See @README for project overview and @package.json for npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md

• Acepta paths relativos (resuelven desde el archivo que importa, no desde working dir) y absolutos
• Max 5 niveles de importación recursiva
• Primera vez que Claude Code encuentra imports externos, muestra dialog de aprobación

AGENTS.md — compatibilidad cross-tool

Si tu repo ya usa AGENTS.md para otros coding agents (Aider, Continue, etc.), crea un CLAUDE.md que lo importe:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Claude Code lee solo CLAUDE.md, no AGENTS.md directamente. El import te permite compartir instrucciones entre tools sin duplicarlas.

Los 6 Niveles Pedagógicos (mental model)

Además de los 4 scopes de CLAUDE.md que tú controlas, conceptualmente hay 6 fuentes que influyen en cada respuesta de Claude. Mantenemos este framing porque ayuda a entender cómo Claude prioriza información:

Los 6 Niveles: Vista General

PRIORIDAD MÁS ALTA (gana en conflictos)
         ▲
         │
  ┌──────┴──────┐
  │ 6. Contexto │  ← Tu conversación actual
  │    de sesión │
  └──────┬──────┘
  ┌──────┴──────┐
  │ 5. CLAUDE.md│  ← Overrides por subdirectorio
  │    subdir   │
  └──────┬──────┘
  ┌──────┴──────┐
  │ 4. CLAUDE.md│  ← Tu archivo en project root
  │    proyecto │
  └──────┬──────┘
  ┌──────┴──────┐
  │ 3. CLAUDE.md│  ← Reglas de la organización (enterprise)
  │    empresa  │
  └──────┬──────┘
  ┌──────┴──────┐
  │ 2. System   │  ← Prompt interno de Anthropic
  │    prompt   │
  └──────┬──────┘
  ┌──────┴──────┐
  │ 1. Training │  ← Conocimiento del modelo base
  │    data     │
  └─────────────┘
         │
         ▼
PRIORIDAD MÁS BAJA (se sobreescribe)

Regla de precedencia: Los niveles superiores anulan a los inferiores. Si tu CLAUDE.md dice "usa snake_case" pero tu conversación dice "para este archivo usa camelCase", gana la conversación.

Nivel 1: Training Data (Conocimiento del Modelo)

Qué es

Es todo lo que Claude sabe por su entrenamiento. Incluye conocimiento de lenguajes de programación, frameworks, buenas prácticas, documentación de librerías, y patrones comunes de desarrollo.

Qué proporciona

• Conocimiento de lenguajes (Python, TypeScript, Rust, Go, etc.)
• Documentación de frameworks y librerías
• Patrones de diseño (MVC, Repository, Factory, etc.)
• Buenas prácticas generales de ingeniería de software
• Conocimiento de herramientas (git, npm, pip, Docker, etc.)

Quién lo controla

Anthropic — a través del proceso de entrenamiento del modelo. Tú no puedes modificar este nivel.

Cuándo toma precedencia

Cuando no hay información más específica en los niveles superiores. Si ningún CLAUDE.md dice qué convención de naming usar, Claude usa la convención que considera "mejor práctica" según su training.

Ejemplo práctico

Sin ningún CLAUDE.md ni instrucciones:

Tú: "Crea una clase para manejar usuarios en Python"

Claude usa su training:
→ Usa snake_case (convención de Python)
→ Crea una clase con __init__, __repr__
→ Sigue PEP 8
→ Usa type hints (Python moderno)

Claude toma estas decisiones porque su training data le dice que eso es convencional en Python. Si tu proyecto usa un estilo diferente, necesitas decírselo en niveles superiores.

Limitaciones

• No conoce TU proyecto específico
• No conoce TUS convenciones
• No sabe qué versiones usas
• No sabe qué archivos existen en tu codebase
• Puede tener información desactualizada (corte de conocimiento)

Nivel 2: System Prompt (Prompt Interno de Anthropic)

Qué es

Es un prompt que Anthropic inyecta automáticamente antes de cada sesión. Define el comportamiento base de Claude Code: cómo interactúa, qué herramientas tiene disponibles, qué permisos pide, y qué restricciones de seguridad sigue.

Qué proporciona

• Instrucciones de comportamiento (ser conciso, pedir confirmación antes de ejecutar comandos destructivos)
• Definición de herramientas disponibles (read file, write file, execute command, etc.)
• Restricciones de seguridad (no ejecutar código malicioso, pedir confirmación para operaciones peligrosas)
• Formato de output (cómo presenta código, explicaciones, etc.)

Quién lo controla

Anthropic — no puedes ver ni modificar el system prompt directamente.

Cuándo toma precedencia

Sobre el training data, pero debajo de cualquier CLAUDE.md. El system prompt establece las "reglas del juego" de Claude Code como herramienta, pero tus instrucciones (vía CLAUDE.md) tienen prioridad sobre la mayoría de comportamientos.

Ejemplo práctico

El system prompt dice algo como:
"Antes de ejecutar comandos que modifiquen el filesystem,
 pide confirmación al usuario."

Por eso cuando Claude quiere ejecutar:
> rm -rf node_modules && npm install

Te pregunta:
"Claude wants to run this command. Allow? [y/n/always]"

Esto viene del system prompt, no de tu configuración.

Lo que puedes influir

Aunque no puedes cambiar el system prompt directamente, puedes influir en el comportamiento de Claude a través de:

• Settings: Configurar allowedTools para pre-aprobar herramientas
• CLAUDE.md: Dar instrucciones que complementen o ajusten el comportamiento default

Nivel 3: CLAUDE.md Enterprise/Organización

Qué es

En entornos enterprise (empresas que usan Claude Code a escala), los administradores pueden definir un CLAUDE.md a nivel de organización que aplica a todos los proyectos de la empresa.

Qué proporciona

• Estándares de la empresa (coding standards, security policies)
• Restricciones globales (no usar ciertas librerías, no generar cierto tipo de código)
• Convenciones compartidas entre todos los equipos
• Reglas de compliance y seguridad

Quién lo controla

Administradores de la organización — equipos de plataforma, DevOps, o líderes técnicos.

Cuándo toma precedencia

Sobre el system prompt y el training data. Pero puede ser sobreescrito por el CLAUDE.md del proyecto (nivel 4) o superior.

Ejemplo práctico

# CLAUDE.md (Enterprise — definido por el equipo de plataforma)

## Estándares corporativos
- Todos los proyectos deben usar TypeScript strict
- No generar código que use eval()
- Logging obligatorio con el formato corporativo: JSON structured
- Todos los endpoints requieren autenticación
- No usar npm packages con licencia GPL
- Tests obligatorios: mínimo 80% coverage

Este CLAUDE.md aplica a TODOS los proyectos de la organización. Un developer individual no necesita repetir "no usar eval()" en cada proyecto — ya está a nivel enterprise.

Para quién es relevante

• Equipos enterprise: Si tu empresa tiene Claude Code con plan enterprise, esto aplica
• Developers individuales: Probablemente no tienes este nivel. Pasas directo al nivel 4

Analogía

Es como las variables de entorno de sistema operativo. PATH está definido globalmente y todos los programas lo heredan. El CLAUDE.md enterprise es el "PATH" de Claude Code en tu organización.

Nivel 4: CLAUDE.md del Proyecto (Project Root)

Qué es

El CLAUDE.md que tú creas en la raíz de tu proyecto. Es el nivel que cubrimos en profundidad en la cápsula anterior. Es el nivel más importante para la mayoría de developers.

Qué proporciona

• Descripción del proyecto
• Stack tecnológico
• Estructura de archivos
• Convenciones de código
• Comandos disponibles
• Reglas y restricciones

Quién lo controla

Tú (o tu equipo, si lo commitean al repo).

Cuándo toma precedencia

Sobre los niveles 1-3 (training, system prompt, enterprise). Es sobreescrito por CLAUDE.md de subdirectorios (nivel 5) y la conversación actual (nivel 6).

Ejemplo práctico

Enterprise CLAUDE.md dice:
"Todos los proyectos usan TypeScript strict"

Tu project CLAUDE.md dice:
"Stack: Python 3.12, FastAPI"

→ Claude usa Python porque tu project CLAUDE.md tiene más 
  prioridad que el enterprise para decisiones de stack.
  (El enterprise aplica a proyectos TypeScript, este no lo es)

Es el que commites al repo

CLAUDE.md del proyecto normalmente se commitea a git para que todo el equipo lo comparta:

git add CLAUDE.md
git commit -m "docs: add CLAUDE.md for project context"

Esto asegura que todos los developers del equipo tienen el mismo contexto cuando usan Claude Code.

Nivel 5: CLAUDE.md de Subdirectorio

Qué es

Archivos CLAUDE.md colocados en subdirectorios específicos del proyecto. Proporcionan contexto adicional o overrides cuando Claude trabaja en archivos de ese directorio.

Qué proporciona

• Reglas específicas para un área del codebase
• Overrides de convenciones para ciertos tipos de archivos
• Contexto adicional para directorios con lógica particular

Quién lo controla

Tú o tu equipo.

Cuándo toma precedencia

Cuando Claude trabaja en archivos dentro de ese subdirectorio. Un CLAUDE.md en /tests/ tiene prioridad sobre el CLAUDE.md raíz cuando Claude está escribiendo o leyendo archivos en /tests/.

Ejemplo práctico

my-project/
├── CLAUDE.md                    ← Nivel 4 (proyecto)
├── src/
│   └── ...
├── tests/
│   ├── CLAUDE.md                ← Nivel 5 (subdirectorio)
│   ├── unit/
│   └── integration/
└── docs/
    └── CLAUDE.md                ← Nivel 5 (subdirectorio)

CLAUDE.md raíz (nivel 4):

## Convenciones
- No usar any
- Imports absolutos
- camelCase para variables

tests/CLAUDE.md (nivel 5):

## Convenciones de Testing
- any es aceptable en mocks y fixtures
- Usar describe/it pattern
- Fixtures compartidas en conftest.py
- Naming de tests: test_[feature]_[scenario]_[expected]
- Los mocks van junto al test, no en carpeta separada
- No usar datos reales de producción en tests

En este ejemplo, la regla raíz "no usar any" se relaja en /tests/ donde "any es aceptable en mocks". Claude sabe esto porque el CLAUDE.md de subdirectorio tiene mayor prioridad.

Cuándo crear CLAUDE.md de subdirectorio

Ejemplo: Monorepo con múltiples CLAUDE.md

monorepo/
├── CLAUDE.md                  ← "Monorepo. Cada package tiene su stack."
├── packages/
│   ├── api/
│   │   ├── CLAUDE.md          ← "FastAPI, Python 3.12, pytest"
│   │   └── src/
│   ├── web/
│   │   ├── CLAUDE.md          ← "Next.js 14, TypeScript, Vitest"
│   │   └── src/
│   └── shared/
│       ├── CLAUDE.md          ← "TypeScript puro, no frameworks"
│       └── src/
└── infra/
    ├── CLAUDE.md              ← "Terraform, AWS CDK"
    └── modules/

Cada CLAUDE.md de subdirectorio da contexto específico a su área. Claude adapta su comportamiento según dónde estés trabajando.

Nivel 6: Contexto de la Conversación Actual

Qué es

Todo lo que dices y todo lo que Claude responde durante la sesión actual. Incluye tus instrucciones, correcciones, archivos que Claude leyó, y output de comandos ejecutados.

Qué proporciona

• Instrucciones específicas para la tarea actual
• Correcciones en tiempo real ("no, usa X en vez de Y")
• Contexto de archivos leídos durante la sesión
• Resultados de comandos ejecutados
• Decisiones tomadas durante la conversación

Quién lo controla

Tú — directamente, con cada mensaje que envías.

Cuándo toma precedencia

Siempre. Es el nivel de mayor prioridad. Si CLAUDE.md dice "usa snake_case" pero tú dices "para este archivo usa camelCase", Claude usa camelCase para ese archivo.

Ejemplo práctico

CLAUDE.md dice:
"Siempre usar Vitest para testing"

Tú: "Para este módulo específicamente, crea los tests con Jest 
     porque se integra mejor con la librería que estamos probando."

→ Claude usa Jest para este módulo porque tu instrucción 
  conversacional tiene prioridad sobre CLAUDE.md

Lo que NO sobrevive

El contexto conversacional se pierde cuando:

• Haces /clear
• La sesión termina
• Se aplica compaction (se resume, pierde detalle)
• Empiezas una sesión nueva

Por eso las instrucciones que aplican siempre deben ir en CLAUDE.md (nivel 4), no en la conversación (nivel 6). La conversación es temporal; CLAUDE.md es permanente.

Cómo Claude Resuelve Contradicciones

La regla de precedencia

Cuando dos niveles se contradicen, gana el de mayor prioridad:

Conversación > CLAUDE.md subdir > CLAUDE.md proyecto > 
CLAUDE.md enterprise > System prompt > Training data

Escenario 1: Training vs CLAUDE.md

Training data: "En Python, usa snake_case por convención PEP 8"
CLAUDE.md: "Convención: camelCase para todo (proyecto legacy Java→Python)"

→ Claude usa camelCase
→ CLAUDE.md (nivel 4) > Training data (nivel 1)

Escenario 2: CLAUDE.md raíz vs subdirectorio

CLAUDE.md raíz: "No usar any"
tests/CLAUDE.md: "any es aceptable en mocks"

Cuando Claude escribe un mock en tests/:
→ Usa any sin problema
→ CLAUDE.md subdir (nivel 5) > CLAUDE.md proyecto (nivel 4)

Cuando Claude escribe código en src/:
→ No usa any
→ Solo aplica CLAUDE.md proyecto (nivel 4)

Escenario 3: CLAUDE.md vs Conversación

CLAUDE.md: "Siempre incluir type hints"
Tú: "Genera este script rápido sin type hints, es un one-off"

→ Claude omite type hints para este script
→ Conversación (nivel 6) > CLAUDE.md (nivel 4)

→ En el SIGUIENTE mensaje (si no dices nada sobre types):
→ Claude vuelve a usar type hints
→ La instrucción conversacional fue para esa tarea específica

Escenario 4: Todos los niveles en acción

Training:    "Python usa snake_case"
System:      "Pide confirmación para rm"
Enterprise:  "No usar eval()"
Proyecto:    "Stack: Python 3.12, FastAPI. Naming: snake_case"
Subdir:      tests/CLAUDE.md: "Mocks pueden usar any"
Conversación: "Para este test, usa camelCase en los helpers"

Resultado cuando Claude escribe un test:
- ✅ Usa Python (training + proyecto)
- ✅ Pide confirmación para comandos destructivos (system)
- ✅ No genera eval() (enterprise)
- ✅ Usa FastAPI patterns (proyecto)
- ✅ Permite any en mocks (subdir)
- ✅ Usa camelCase en helpers de este test (conversación)

Cada nivel aporta algo. Cuando hay conflicto, gana el superior.

Analogía: Variables de Entorno

La jerarquía de memoria funciona como las variables de entorno en programación:

# Nivel 1 (Training) ≈ Defaults del sistema operativo
# Ya están ahí, no los defines

# Nivel 2 (System prompt) ≈ /etc/environment
# Configuración global del sistema, no la tocas

# Nivel 3 (Enterprise) ≈ /etc/profile.d/company.sh
# La empresa define variables para todos

# Nivel 4 (Proyecto) ≈ .env del proyecto
# Tú defines variables para este proyecto

# Nivel 5 (Subdir) ≈ .env en un subdirectorio
# Override específico para un área

# Nivel 6 (Conversación) ≈ export en la terminal
# Override temporal, solo para esta sesión

Si defines DATABASE_URL en .env (nivel 4) y luego haces export DATABASE_URL=other en la terminal (nivel 6), gana la terminal. Lo mismo pasa con la memoria de Claude.

Comparaciones y Decisiones

Trabajar con 1 nivel vs múltiples niveles

Cuándo necesitas más de un nivel

• 1 nivel es suficiente para proyectos pequeños (1 developer, 1 stack, <20 archivos)
• 2-3 niveles para proyectos medianos (equipo, testing con reglas propias, docs)
• 4+ niveles para enterprise y monorepos (múltiples stacks, equipos, políticas)

Qué poner en cada nivel

Patterns Comunes

Pattern 1: CLAUDE.md raíz + tests/CLAUDE.md

El pattern más común. CLAUDE.md raíz para el proyecto, un CLAUDE.md extra en /tests/ con convenciones de testing:

proyecto/
├── CLAUDE.md          → Stack, convenciones, comandos
└── tests/
    └── CLAUDE.md      → Convenciones de testing específicas

Pattern 2: Monorepo con CLAUDE.md por package

monorepo/
├── CLAUDE.md          → "Monorepo con packages independientes"
├── packages/
│   ├── api/CLAUDE.md  → Stack del API (Python, FastAPI)
│   ├── web/CLAUDE.md  → Stack del frontend (TypeScript, Next.js)
│   └── cli/CLAUDE.md  → Stack del CLI (Rust)

Pattern 3: Override temporal por conversación

Cuando necesitas romper una regla para un caso específico:

Tú: "Sé que CLAUDE.md dice no usar any, pero para este archivo 
     de tipos generados necesito any. Procede."

Claude respeta la instrucción conversacional sin que modifiques CLAUDE.md.

Pattern 4: Evolución progresiva

No necesitas los 6 niveles desde el día 1. Empieza con nivel 4 y agrega según necesites:

Semana 1: Crear CLAUDE.md raíz (nivel 4)
Semana 2: Agregar tests/CLAUDE.md si tienes convenciones de testing (nivel 5)
Mes 2:    Agregar CLAUDE.local.md para preferencias personales
Cuando escale: Considerar enterprise CLAUDE.md (nivel 3)

Pitfalls y Edge Cases

Pitfall 1: Asumir que la conversación persiste entre sesiones

Sesión 1:
Tú: "Siempre usa verbose logging"
Claude: [usa verbose logging en toda la sesión]

Sesión 2 (nueva):
Tú: "Crea un endpoint"
Claude: [NO usa verbose logging — la instrucción se perdió]

Solución: Si aplica siempre, ponlo en CLAUDE.md (nivel 4),
no en la conversación (nivel 6).

Pitfall 2: Contradicciones no intencionales entre niveles

CLAUDE.md raíz: "Imports absolutos siempre"
src/utils/CLAUDE.md: "Imports relativos para utils internos"

¿Qué pasa cuando Claude importa un util desde otro util?
→ Usa import relativo (subdir tiene prioridad)

¿Es eso lo que querías? Quizás sí, quizás no.
Sé explícito sobre el scope de cada regla.

Pitfall 3: CLAUDE.md de subdirectorio demasiado permisivo

tests/CLAUDE.md:
"En tests no aplican restricciones de código."

Esto anula TODAS las reglas del CLAUDE.md raíz dentro de /tests/.
Claude podría generar tests con eval(), any, console.log, 
y sin type hints — porque "no aplican restricciones."

Solución: Sé específico sobre qué relajas, no hagas un override global:
"En tests: any es aceptable en mocks. Las demás reglas de 
 CLAUDE.md raíz aplican normalmente."

Pitfall 4: No saber qué nivel está causando un comportamiento

Claude genera código con un patrón que no esperabas.
¿De dónde viene?

Checklist de diagnóstico:
1. ¿Lo dijiste en la conversación? → Nivel 6
2. ¿Hay un CLAUDE.md en el subdirectorio? → Nivel 5
3. ¿Está en CLAUDE.md raíz? → Nivel 4
4. ¿Hay un CLAUDE.md enterprise? → Nivel 3
5. ¿Es comportamiento default de Claude Code? → Nivel 2
6. ¿Es convención estándar del lenguaje? → Nivel 1

Tip: Pregúntale a Claude:
"¿Por qué usaste X en vez de Y? ¿De dónde viene esa decisión?"

Pitfall 5: Olvidar que auto memory es otro nivel

Auto memory (cápsula 04) agrega un nivel adicional al sistema. Si corregiste a Claude ("no uses var, usa const") y Claude lo guardó como auto memory, esa corrección persiste entre sesiones — incluso si no está en CLAUDE.md.

Esto puede causar comportamientos "fantasma" donde Claude hace algo que no le pediste explícitamente, pero lo aprendió de una corrección anterior.

Ejemplo Completo Integrado

Escenario: Monorepo con múltiples niveles

ecommerce/
├── CLAUDE.md                         ← Nivel 4: Proyecto
├── packages/
│   ├── api/
│   │   ├── CLAUDE.md                 ← Nivel 5: API
│   │   ├── src/
│   │   └── tests/
│   │       └── CLAUDE.md             ← Nivel 5: Tests del API
│   ├── storefront/
│   │   ├── CLAUDE.md                 ← Nivel 5: Storefront
│   │   └── src/
│   └── admin/
│       ├── CLAUDE.md                 ← Nivel 5: Admin
│       └── src/

CLAUDE.md raíz (nivel 4):

# E-Commerce Platform

Monorepo con 3 packages: api, storefront, admin.

## Reglas globales
- Commits en inglés: "type(scope): description"
- No commitear secrets
- Cada package tiene su propio stack (ver su CLAUDE.md)
- Shared types en packages/shared/types/

packages/api/CLAUDE.md (nivel 5):

# API Package

## Stack
- Python 3.12, FastAPI 0.109, SQLAlchemy 2.0
- Pytest + httpx

## Convenciones
- snake_case para todo
- Pydantic v2 para schemas
- Alembic para migrations

## Comandos (ejecutar desde packages/api/)
- Dev: `uvicorn src.main:app --reload`
- Test: `pytest -v`

packages/storefront/CLAUDE.md (nivel 5):

# Storefront Package

## Stack
- TypeScript 5.3, Next.js 14 (App Router)
- Tailwind CSS 3.4, shadcn/ui

## Convenciones
- camelCase para variables, PascalCase para componentes
- Server Components por defecto
- CSS: Tailwind utilities, no CSS modules

## Comandos (ejecutar desde packages/storefront/)
- Dev: `npm run dev`
- Build: `npm run build`

packages/api/tests/CLAUDE.md (nivel 5, anidado):

# API Tests

- Fixtures compartidas en conftest.py
- any aceptable en mocks
- Cada test file: test_{module}.py
- Factory pattern para crear datos de prueba
- Usar database isolation: cada test en transacción que hace rollback

Resolución en acción

Tú (trabajando en packages/api/):
"Crea un endpoint para buscar órdenes"

Claude aplica:
- Nivel 1 (Training): Sabe Python y FastAPI
- Nivel 4 (Proyecto): "Commits en inglés, no secrets"
- Nivel 5 (API): "snake_case, Pydantic v2, uvicorn"
→ Genera endpoint FastAPI con snake_case y Pydantic schemas

Tú (trabajando en packages/storefront/):
"Crea una página de búsqueda de productos"

Claude aplica:
- Nivel 1 (Training): Sabe TypeScript y Next.js
- Nivel 4 (Proyecto): "Commits en inglés, no secrets"
- Nivel 5 (Storefront): "PascalCase componentes, Tailwind, Server Components"
→ Genera Server Component con Tailwind CSS

Mismo proyecto. Diferentes CLAUDE.md de subdirectorio. 
Comportamiento completamente distinto. Eso es el poder de la jerarquía.

Ejercicios Prácticos

Ejercicio 1: Identifica los niveles en tu setup

Analiza tu configuración actual de Claude Code. ¿Cuántos niveles tienes activos?

1. ¿Tienes CLAUDE.md en la raíz del proyecto? (Nivel 4)
2. ¿Tienes CLAUDE.md en algún subdirectorio? (Nivel 5)
3. ¿Usas Claude Code en una organización con configuración enterprise? (Nivel 3)
4. ¿Hay auto memories guardadas? (Variable)

# Verificar CLAUDE.md en raíz
ls CLAUDE.md

# Buscar CLAUDE.md en subdirectorios
find . -name "CLAUDE.md" -not -path "./.git/*"

# Verificar auto memories
ls -la .claude/

# Verificar settings
cat .claude/settings.json 2>/dev/null
cat ~/.claude/settings.json 2>/dev/null

Ejercicio 2: Crea un CLAUDE.md de subdirectorio

Si tu proyecto tiene una carpeta de tests (tests/, __tests__/, spec/), crea un CLAUDE.md en esa carpeta con convenciones específicas de testing:

• Patrón de naming para tests
• Qué tipos de mocks son aceptables
• Fixtures y setup
• Qué convenciones del proyecto raíz se relajan en tests

# Testing Conventions

## Estructura
- Archivos: test_{modulo}.py (Python) o {modulo}.test.ts (TypeScript)
- Cada archivo de test corresponde a un módulo en src/

## Convenciones
- describe/it (o class/def test_) para organizar tests
- any aceptable en mocks y stubs
- Fixtures compartidas en conftest.py / setup.ts
- Factory functions para crear datos de prueba

## Reglas
- No usar datos reales de producción
- Cada test debe ser independiente (no depender de orden)
- Limpiar side effects después de cada test
- Mocks junto al test, no en carpeta separada

Ejercicio 3: Simula un conflicto entre niveles

1. En tu CLAUDE.md raíz, agrega: "Todos los comentarios en inglés"
2. En una sesión de Claude Code, di: "Para este archivo, escribe los comentarios en español"
3. Verifica que Claude usa español (la conversación tiene prioridad)
4. En el siguiente mensaje, pide que cree otro archivo SIN instrucción de idioma
5. Verifica que Claude vuelve a inglés (vuelve a CLAUDE.md raíz)

Ejercicio 4: Diseña la jerarquía para tu proyecto

Dibuja la estructura de CLAUDE.md que necesitaría tu proyecto. ¿Necesitas solo raíz? ¿Tests? ¿Subdirectorios específicos?

Criterios:

• ¿Hay áreas con convenciones diferentes? → CLAUDE.md de subdirectorio
• ¿Hay áreas con stacks diferentes? → CLAUDE.md de subdirectorio
• ¿Es un monorepo? → CLAUDE.md por package
• ¿Trabajas en equipo? → Considerar CLAUDE.local.md (cápsula 05)

proyecto/
└── CLAUDE.md      ← Solo nivel 4, suficiente

proyecto/
├── CLAUDE.md      ← Nivel 4: Stack, convenciones
└── tests/
    └── CLAUDE.md  ← Nivel 5: Reglas de testing

monorepo/
├── CLAUDE.md            ← Nivel 4: Reglas globales
├── frontend/CLAUDE.md   ← Nivel 5: Stack frontend
├── backend/CLAUDE.md    ← Nivel 5: Stack backend
└── shared/CLAUDE.md     ← Nivel 5: Convenciones shared

empresa/
├── [CLAUDE.md enterprise]  ← Nivel 3: Gestionado por plataforma
├── my-project/
│   ├── CLAUDE.md           ← Nivel 4: Mi proyecto
│   ├── CLAUDE.local.md     ← Personal (no en git)
│   └── tests/CLAUDE.md     ← Nivel 5: Testing

Ejercicio 5: Pregúntale a Claude de dónde viene una decisión

En tu próxima sesión de Claude Code, cuando Claude genere código con un patrón o convención, pregúntale:

"¿Por qué elegiste [pattern X] en vez de [pattern Y]? 
 ¿De dónde viene esa decisión?"

Intenta identificar si la decisión vino de:

• Training data (convención estándar del lenguaje)
• CLAUDE.md (una regla que tú definiste)
• Conversación (algo que dijiste antes en esta sesión)

Resumen

• 6 niveles de memoria determinan cómo Claude Code toma decisiones, de menor a mayor prioridad:
  1. Training data — conocimiento del modelo
  2. System prompt — comportamiento base de Claude Code
  3. CLAUDE.md enterprise — reglas de la organización
  4. CLAUDE.md proyecto — tu configuración (el más importante)
  5. CLAUDE.md subdirectorio — overrides por área
  6. Contexto de conversación — tus instrucciones actuales
• Los niveles superiores anulan a los inferiores cuando hay conflicto.
• CLAUDE.md raíz (nivel 4) es suficiente para la mayoría de proyectos.
• CLAUDE.md de subdirectorio (nivel 5) se usa para tests, monorepos, o áreas con convenciones diferentes.
• La conversación (nivel 6) tiene la máxima prioridad pero es temporal — se pierde entre sesiones.
• Lo que aplica siempre va en CLAUDE.md. Lo temporal va en la conversación.
• Diagnóstico: Si Claude hace algo inesperado, recorre los 6 niveles para encontrar la fuente.
• Analogía: Funciona como variables de entorno: los scopes más locales anulan a los globales.

Siguiente cápsula: 04 - Auto memory y settings — cómo Claude aprende implícitamente y cómo configurar permisos en 3 scopes.

Recursos Adicionales

1. Claude Code Memory — Anthropic Docs — Documentación oficial de la jerarquía de memoria completa
2. Claude Code Settings — Cómo los settings interactúan con la jerarquía de memoria
3. Claude Code Best Practices — Recomendaciones para gestionar contexto en múltiples niveles
4. Claude Code Overview — Arquitectura general y cómo funcionan los niveles internamente
5. Claude Code CLI Reference — Comandos para gestionar CLAUDE.md y memoria
6. Claude Code Interactive Mode — Cómo la jerarquía afecta las sesiones interactivas