\
CONTEXT/academy
Lección 02 · ≈ 13 min

La jerarquía y los imports

Los cuatro niveles de CLAUDE.md, el orden de carga y los imports con @.

La jerarquía y los imports

Ya sabes qué poner en CLAUDE.md. Ahora, dónde: porque no hay un solo fichero, sino una jerarquía. Lo personal tuyo, lo del equipo y lo de la organización viven en sitios distintos y se combinan. Entenderlo evita el lío de "¿por qué Claude sigue esta instrucción y no aquella?".

Cuatro niveles

CLAUDE.md puede vivir en cuatro sitios, de más general a más específico:

NivelDóndePara qué¿Se comparte?
Managed (org)gestionado por IT (macOS: /Library/Application Support/ClaudeCode/CLAUDE.md · Linux/WSL: /etc/claude-code/CLAUDE.md · Windows: C:\Program Files\ClaudeCode\CLAUDE.md)políticas de empresatoda la organización
User~/.claude/CLAUDE.mdtus preferencias en todos tus proyectossolo tú
Project./CLAUDE.md o ./.claude/CLAUDE.mdinstrucciones del equipoel equipo, vía git
Local./CLAUDE.local.mdtus preferencias solo de este reposolo tú (va al .gitignore)

El reparto mental: lo de cómo trabajas tú (en ~/.claude/CLAUDE.md) viaja contigo a todos tus repos. Lo de cómo trabaja el equipo en este repo (en ./CLAUDE.md) lo commiteas y lo hereda quien clone.

Cómo se cargan: se suman, no se pisan

Todos los ficheros que apliquen se concatenan en contexto, de lo más general a lo más específico. Además, Claude recorre el árbol de directorios hacia arriba desde donde lanzas la sesión: si arrancas en apps/web/, carga el CLAUDE.md de la raíz y el de apps/web/, con el más cercano leído al final.

Subdirectorios por debajo del working dir: los CLAUDE.md que estén en carpetas dentro de donde arrancaste no se cargan al inicio — se incluyen cuando Claude lee un fichero de esa carpeta. Es carga bajo demanda, no al arrancar.

Esto te deja afinar por zonas del repo. Ejemplo en un monorepo:

mi-monorepo/
├── CLAUDE.md            # convenciones generales del repo
└── apps/
    └── web/
        └── CLAUDE.md    # "aquí usamos Server Components por defecto"

Imports con @

Un CLAUDE.md puede traer otros ficheros con @ruta. Se expanden y cargan al arrancar:

Consulta @README.md para el contexto y @package.json para los comandos.

# Workflow de git
@docs/git-instructions.md

Las rutas relativas se resuelven respecto al fichero que importa, y puedes anidar hasta cuatro saltos.

El patrón AGENTS.md

Si tu repo ya usa AGENTS.md para otros agentes, no dupliques: que tu CLAUDE.md lo importe y añada lo específico de Claude debajo.

@AGENTS.md

## Claude Code
Usa plan mode para cambios en `src/billing/`.

Este mismo repo de la academia lo hace así: su CLAUDE.md es una línea, @AGENTS.md. Una sola fuente de verdad para todos los agentes.

Lo personal que no se commitea

Para preferencias de este proyecto que no quieres en git (tus URLs de sandbox, datos de prueba), usa CLAUDE.local.md en la raíz y añádelo al .gitignore. Se carga igual que CLAUDE.md, pero solo en tu máquina.

Qué llevas hasta aquí

  • Hay cuatro niveles (managed / user / project / local) que se suman en contexto.
  • Lo tuyo va en ~/.claude/CLAUDE.md; lo del equipo, en ./CLAUDE.md versionado.
  • Encadenas ficheros con imports @ (hasta 4 saltos); el patrón @AGENTS.md evita duplicar.

En la siguiente lección, qué hacer cuando un solo CLAUDE.md se queda corto: las reglas de .claude/rules.

Fuente oficial: How Claude remembers your project

¿Quieres llevar la cuenta de las lecciones que has terminado?

Entrar para guardar progreso