CLAUDE.md modular vs monolítico: cómo organizar el contexto
CLAUDE.md modular vs monolítico: qué capa de Claude Code carga al arrancar, cuál bajo demanda, por qué @imports no ahorra contexto y cómo migrar 400 líneas.

Imagina un CLAUDE.md de 400 líneas. La regla sobre migraciones está en la 312.
"Nunca edites una migración ya aplicada; crea una nueva." Claude la edita igual. La reescribes en mayúsculas, le pones un "IMPORTANTE" y la subes al principio. Dos semanas después, otra regla deja de cumplirse.
Decides pasar a un CLAUDE.md modular. Partes el archivo en seis piezas enlazadas con @imports. Más ordenado, sí. Pero el agente se comporta igual, porque Claude Code sigue cargando las 400 líneas al arrancar.
Partir el archivo no es tener un CLAUDE.md modular. Lo que cambia las cosas es cuándo carga cada instrucción.
En corto: un CLAUDE.md modular deja en la raíz solo lo que hace falta en cada sesión y mueve el resto a capas que Claude Code carga bajo demanda: reglas con paths, CLAUDE.md de subcarpeta, skills y subagentes. Los @imports ordenan pero no ahorran contexto, porque cargan al arrancar. Menos ruido y menos contradicciones reducen las alucinaciones, aunque no las eliminan.
El porqué está en Context Engineering: cómo estructurar la memoria de tus agentes. Aquí va el mapa de Claude Code y la migración.
¿Qué es un CLAUDE.md modular?
Un CLAUDE.md modular es una arquitectura de contexto en la que el archivo raíz contiene solo los hechos que Claude necesita en todas las sesiones, y cada instrucción restante vive en la capa que se carga cuando de verdad aplica.
La documentación oficial recomienda menos de 200 líneas por CLAUDE.md, porque los archivos largos "consumen más contexto y reducen la adherencia".
Qué meter en la raíz ya lo conté en CLAUDE.md: el system prompt de tu proyecto. Este post trata de lo que sacas de ella.
Las capas de contexto de Claude Code y cuándo carga cada una
El momento de carga de cada capa decide lo que pagas en la ventana. Datos de la documentación de memoria, skills y subagentes, consultada el 7 de noviembre de 2026:
| Capa | Cuándo entra en contexto | Qué ocupa |
|---|---|---|
CLAUDE.md raíz + CLAUDE.local.md |
Siempre, al arrancar. El CLAUDE.md raíz se relee tras /compact |
Entero (se omite si pasa de 4 MiB) |
@imports |
Al arrancar, con el archivo que importa. Máximo 4 saltos | Entero: no ahorra nada |
.claude/rules/ sin paths |
Al arrancar, con la prioridad de .claude/CLAUDE.md |
Entero |
.claude/rules/ con paths |
Al leer, escribir o editar un archivo que encaja con el glob | Hasta 40.000 caracteres por archivo con ventana de 200K |
CLAUDE.md de subcarpeta |
Al leer, escribir o editar un archivo de esa carpeta | Mismo límite |
| Skills | Descripción siempre; cuerpo al invocarse | Hasta 1.536 caracteres por descripción; el listado, ~1% de la ventana |
| Subagentes | Al delegar, en su propia ventana | Su prompt más tu CLAUDE.md, salvo Explore, Plan u omitClaudeMd |
| Auto memory | MEMORY.md al arrancar; temas bajo demanda |
Primeras 200 líneas o 25 KB de MEMORY.md |
Dos detalles cambian decisiones.
Los niveles managed policy, usuario, proyecto y local no se sobrescriben: se concatenan, del más amplio al más específico. Si dos se contradicen, Claude "puede elegir uno de forma arbitraria". La precedencia estricta es de settings.json, no de CLAUDE.md.
Y un subagente no te libra del monolito. Arranca con ventana limpia, pero carga toda tu jerarquía de CLAUDE.md. Con 400 líneas en la raíz, cada subagente las paga también. Más sobre esto en arquitectura de subagentes frente al mega-prompt.
CLAUDE.md monolítico vs modular: la comparativa
El monolítico gana en simplicidad; el modular, en precisión. Ninguno es gratis:
| Criterio | Monolítico | Modular |
|---|---|---|
| Coste fijo por sesión | Todo el archivo | Raíz, reglas sin paths y listado de skills |
| Encontrar una regla | Un sitio, Ctrl+F | Tienes que saber qué capa la tiene |
| Contradicciones | Frecuentes, pero visibles en una lectura | Menos por pieza, invisibles entre piezas |
| Previsibilidad | Lo que está, carga | Depende de que el agente toque el archivo que dispara la regla |
| Limitación o riesgo | Pasadas 200 líneas baja la adherencia y la regla 312 compite con todo | Una regla con paths que no se dispara no existe para Claude, y no te avisa |
Mi opinión: a partir de 200 líneas, el monolítico ya no es una opción neutral. Es deuda, y un CLAUDE.md modular es la forma de pagarla.
El error más común: creer que @imports ahorra contexto
@imports organiza, pero no difiere la carga. La documentación lo dice explícitamente: dividir en imports "ayuda a organizar, pero no reduce el contexto", porque lo importado carga junto al CLAUDE.md que lo referencia.
Hay una trampa más fina. En el issue #16299 de anthropics/claude-code, abierto en enero de 2026 sobre reglas con paths que cargaban siempre, un usuario midió en octubre, con la versión 2.1.300, que un @import dentro de una regla con ruta carga al arrancar aunque la regla no se dispare: el cuerpo de la regla no sumaba nada, pero el import de 20.000 caracteres que llevaba dentro sí, unos 17.000 tokens.
En el mismo hilo, otro equipo cuenta que 75 archivos de referencia en .claude/rules/ sin paths le subían el arranque a 139.500 tokens antes de abrir un archivo. Lo vieron con /context.
Si quieres que algo cargue tarde, no lo importes.
Qué va en cada capa: criterios para organizar CLAUDE.md
A cada bloque de tu CLAUDE.md, una pregunta: ¿cuándo lo necesita Claude?
| Si la instrucción… | Va en… |
|---|---|
| Aplica en toda sesión (build, convenciones globales, prohibiciones) | CLAUDE.md raíz |
| Solo importa al tocar ciertos archivos | .claude/rules/ con paths |
| Es un procedimiento de varios pasos | Skill |
| Llena la ventana de logs o búsquedas | Subagente |
| Es una preferencia tuya o la URL de tu sandbox | CLAUDE.local.md, en .gitignore |
| Claude la deduce leyendo el código | En ningún sitio: bórrala |
| Debe cumplirse sin excepción | Un hook o permissions.deny |
La última fila pesa más de lo que parece: CLAUDE.md es contexto, no configuración que se haga cumplir.
En monorepos, el CLAUDE.md por carpeta tiene sus propias reglas: las detallé en Claude Code en monorepos.
Migración de ejemplo: de 400 líneas a un CLAUDE.md modular
Imagina un backend en TypeScript con API REST, migraciones y tests end-to-end. Su CLAUDE.md de 400 líneas se reparte así:
| Bloque | Líneas | Destino |
|---|---|---|
| Comandos, convenciones, prohibiciones | 60 | CLAUDE.md raíz |
| Convenciones de la API | 90 | .claude/rules/api.md |
| Migraciones y base de datos | 70 | .claude/rules/migrations.md |
| Procedimiento de release | 80 | Skill release |
| Árbol de carpetas y dependencias | 50 | Borrado |
| URLs de staging y datos de prueba | 50 | CLAUDE.local.md |
El coste fijo por sesión pasa de 400 líneas a 60 más la descripción de una skill. Las 160 de API y migraciones solo entran cuando el agente toca esos archivos. Cifras ilustrativas.
proyecto/
├── CLAUDE.md # 60 líneas: lo de todas las sesiones
├── CLAUDE.local.md # en .gitignore
└── .claude/
├── rules/
│ ├── api.md # paths: src/api/**
│ └── migrations.md # paths: src/db/**/*.ts
└── skills/
└── release/
└── SKILL.md # el cuerpo carga solo al invocarse
Y la regla que no se cumplía, ahora pegada al código al que aplica:
---
paths:
- "src/db/**/*.ts"
---
# Migraciones
- Nunca edites una migración que ya está en main. Crea una nueva.
- Cada migración lleva su `down`.
- Ejecuta `npm run db:check` antes de dar la tarea por terminada.
Para comprobarlo, ejecuta /context all al empezar: la regla de migraciones no debe estar en Memory files. Para ver cuándo entra, registra la carga con el hook InstructionsLoaded y pide a Claude que lea un .ts de src/db/. Si tu repo usa AGENTS.md, revisa antes cómo convive con CLAUDE.md: por defecto, un CLAUDE.md en la raíz hace que Claude deje de leerlo, salvo que lo importe con @AGENTS.md.
Auto memory en Claude Code: por qué no es tu CLAUDE.md
La memoria persistente de Claude Code son dos sistemas: CLAUDE.md lo escribes tú y auto memory lo escribe Claude. Auto memory vive en ~/.claude/projects/<proyecto>/memory/, solo en tu máquina.
Al arrancar carga el índice MEMORY.md, hasta 200 líneas o 25 KB; los archivos de tema, bajo demanda. Es el patrón modular aplicado a la memoria.
No la uses para reglas de equipo: no viaja por git ni llega a los subagentes. Un subagente puede tener su propia memoria con el campo memory, pero es otro directorio, no la tuya. La revisas con /memory. Cómo la uso en el día a día está en mi flujo real con CLAUDE.md y memoria.
Si quieres llevar esto a la memoria y las herramientas de un agente propio, el ebook gratuito El Developer Agéntico lo trata a fondo.
Por qué el contexto modular reduce alucinaciones (sin eliminarlas)
El context engineering en Claude Code no hace que el modelo deje de inventar. Le quita motivos, por tres vías.
Menos ruido. Si la sesión no toca la base de datos, las reglas de migraciones no compiten por atención.
La regla llega cuando importa. Una regla con paths entra cuando Claude abre el archivo afectado, justo antes de decidir, aunque tras un /compact tiene que volver a dispararse.
Menos contradicciones. Ante instrucciones contradictorias, Claude puede elegir una de forma arbitraria. Archivos pequeños de un solo tema se revisan mejor, y /doctor prompt-audit (desde la versión 2.1.283) busca archivos que chocan entre sí.
Lo que no resuelve: una regla ambigua sigue siéndolo aunque cargue a tiempo. Revisar lo que genera el agente contra una especificación sigue siendo necesario; es lo que practicamos en el workshop de SDD + Agentic Engineering.
Cuándo NO modularizar tu CLAUDE.md
Si tu CLAUDE.md cabe en 100 líneas. Un CLAUDE.md modular añade indirección sin ahorrar nada. Un archivo que lees en un minuto se audita mejor que cinco.
Si tu agente escribe mucho por Bash. En el issue #93248, de septiembre de 2026, un usuario documentó con la versión 2.1.267 que su regla de TypeScript no cargó al crear un .ts desde cero. Otro midió en octubre, con la 2.1.296, que la herramienta Write ya la dispara, pero que las escrituras por Bash (sed -i, >, heredocs) y los comandos con pipes no cargan nada; las lecturas simples con cat o head sí. Una regla crítica con ruta puede no llegar nunca.
Si la regla tiene que sobrevivir a /compact. Las reglas con paths entran en el historial y la compactación las resume con todo lo demás; no vuelven hasta que Claude toque otra vez un archivo que encaje. La documentación lo dice claro: si una regla debe persistir, quítale paths o súbela al CLAUDE.md raíz. Para la regla de migraciones del ejemplo, si es crítica, valora dejarla en la raíz o respaldarla con un hook.
Si nadie va a mantener el mapa. Sin ese criterio, el modular acumula contradicciones igual que el monolítico, pero escondidas.
Empieza por medir, no por partir
Así empieza un CLAUDE.md modular: ejecuta /context all y mira qué carga al arrancar. Luego marca cada bloque de tu CLAUDE.md con su respuesta a "¿cuándo lo necesita Claude?". Lo que no sea "siempre" tiene otro sitio. Lo que Claude deduce del código, bórralo.
Si quieres aplicarlo de principio a fin en un proyecto, de la spec al producto, es el flujo del curso Construye con IA: de la idea al producto con Claude Code.
Preguntas frecuentes
¿Los @imports de CLAUDE.md reducen el consumo de contexto?
No. Los archivos importados cargan al arrancar junto al CLAUDE.md que los referencia, con un máximo de cuatro saltos. Sirven para organizar o compartir un AGENTS.md, no para diferir la carga.
¿Cuándo se cargan los CLAUDE.md de las subcarpetas?
Los del directorio donde arrancas y los superiores cargan al inicio. Los de subcarpetas, la primera vez que Claude lee, escribe o edita un archivo en ella. Por eso no salen en /context al empezar; cuando cargan, verás una línea Loaded con su ruta.
¿Sigue existiendo CLAUDE.local.md?
Sí. Es el nivel local del proyecto: carga después de CLAUDE.md en el mismo directorio y debe ir en .gitignore. Si tu proyecto depende de AGENTS.md, crear un CLAUDE.local.md hace que Claude deje de leerlo, salvo que cambies la opción Project instructions en /config.
¿Cuánto contexto ocupa una skill que no he invocado?
Su entrada en el listado: nombre y descripción, recortados a 1.536 caracteres. El listado completo tiene un presupuesto del 1% de la ventana. El cuerpo de SKILL.md entra al invocarla, y con disable-model-invocation: true ni siquiera la descripción está en contexto.
Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
¿Quieres construir con agentes en serio?
Curso «Construye con IA» con Claude Code, de la idea al producto.
Developer con más de 15 años en frontend y creador de Dominicode. Escribe sobre IA aplicada al desarrollo de software.
¿Te resultó útil este artículo?
Compártelo con tu comunidad y ayuda a otros desarrolladores.