Memoria en Claude Code: CLAUDE.md raíz y anidado
Claude Code soporta varios archivos CLAUDE.md organizados en el árbol del proyecto. El raíz se carga siempre; los anidados se cargan de forma diferida, solo cuando el modelo toca archivos de esa carpeta. Esto resuelve el problema del CLAUDE.md gigante que satura el contexto: en lugar de un archivo que intenta hablar de todo, cada carpeta tiene sus propias reglas, que llegan justo cuando hacen falta.
El principio: las instrucciones de una carpeta solo se cargan cuando el modelo toca archivos de esa carpeta. Por eso el archivo raíz debe ser mínimo (solo lo universalmente relevante) y la especialización vive anidada.
Los dos tipos de CLAUDE.md
Raíz (en .claude/ o en el directorio raíz): se carga al inicio de cada sesión, en cada mensaje, como parte del system reminder. Está siempre presente. Por eso debe ser corto: solo lo que aplica en cualquier contexto del proyecto.
Anidado (en cualquier subcarpeta): se carga de forma diferida, solo cuando el modelo lee un archivo dentro de esa carpeta. En ese momento, Claude Code añade el contenido del CLAUDE.md local al resultado de la herramienta, como un system reminder contextual.
La clave: carga diferida por acceso
Un CLAUDE.md anidado no existe para el modelo hasta que lo necesita. Si editas el módulo de Windows, el CLAUDE.md del módulo de macOS nunca se carga. El contexto se mantiene limpio de información irrelevante.
La acumulación es jerárquica: si el modelo lee un archivo tres niveles abajo, se cargan los CLAUDE.md de cada nivel intermedio. Al leer app/windows/models/algo.ts, se apilan app/windows/models/CLAUDE.md, app/windows/CLAUDE.md y el raíz, en ese orden.
Esto invierte la estrategia habitual
La lógica común es "pongo todo en el archivo principal para asegurarme de que el modelo lo tenga". Con la jerarquía, la estrategia correcta es la opuesta: el raíz mínimo, y cada subcarpeta con sus propias instrucciones que llegan just-in-time. Así evitas que cada sesión consuma una parte desproporcionada del contexto antes de que escribas una sola instrucción, y que el modelo aplique convenciones del backend cuando editas el frontend.
Esta jerarquía es la base de la Context Layer, el sistema completo de contexto distribuido para codebases grandes.
Preguntas frecuentes
¿Claude Code soporta varios archivos CLAUDE.md?
Sí. Soporta una jerarquía: un CLAUDE.md raíz que se carga siempre, y CLAUDE.md anidados en subcarpetas que se cargan solo cuando el modelo toca archivos de esa carpeta. Así cada zona del proyecto tiene sus reglas sin saturar el contexto.
¿Cuál es la diferencia entre un CLAUDE.md raíz y uno anidado?
El raíz (en la raíz del proyecto) se carga al inicio de cada sesión y en cada mensaje, así que debe ser corto. El anidado (en una subcarpeta) se carga de forma diferida, solo cuando el modelo lee un archivo de esa carpeta, y se apila sobre los niveles superiores.
¿Por qué mi CLAUDE.md hace que el contexto se llene?
Suele ser un único archivo demasiado largo que intenta cubrir todo el proyecto y se carga entero en cada sesión. La solución es la jerarquía: dejar el raíz mínimo y mover las reglas específicas a CLAUDE.md anidados en cada carpeta, que se cargan solo cuando hacen falta.
¿Cómo se acumulan los CLAUDE.md anidados?
De forma jerárquica: al leer un archivo en una subcarpeta profunda, se cargan los CLAUDE.md de cada nivel intermedio más el raíz, apilados en orden. Los de carpetas que no tocas nunca se cargan.
Recursos relacionados
- CLAUDE.md: la memoria del proyecto: qué poner en el archivo.
- Context Layer: la arquitectura completa que extiende esta jerarquía.
- Ingeniería de contexto y la guía para dominar Claude Code.
Tu siguiente paso
Los comandos de memoria y decenas más están en la Cheat Sheet de Claude Code: una hoja imprimible, en español.
Descargar la Cheat Sheet gratis
Es el resumen de Ship with Claude Code, la guía de Takren (14 módulos, 190 capítulos, actualizaciones gratuitas).