CCAR-F · Claude Code
CLAUDE.md: jerarquía, alcance e imports
CLAUDE.md es un archivo de instrucciones que Claude Code lee al empezar cada sesión: comandos de build y test, convenciones, decisiones de arquitectura. Son contexto, no configuración obligatoria. Casi todas las preguntas del examen sobre este tema se resuelven sabiendo dónde vive cada archivo y quién lo recibe.
La jerarquía
La jerarquía de configuración (configuration hierarchy) tiene tres niveles que se suman, no se pisan:
| Nivel | Dónde | Quién lo recibe |
|---|---|---|
| Usuario (user-level) | ~/.claude/CLAUDE.md |
Solo esa persona, en todos sus proyectos |
| Proyecto (project-level) | CLAUDE.md o .claude/CLAUDE.md en la raíz del repo |
Todo el equipo, por git |
| Directorio | CLAUDE.md dentro de una subcarpeta |
Todo el equipo, cuando se trabaja en esa carpeta |
Al arrancar se cargan el de usuario, el del proyecto y los de las carpetas por encima del directorio de trabajo. Los de subcarpetas se cargan bajo demanda, cuando Claude lee o edita archivos de esa carpeta. Por eso un packages/frontend/CLAUDE.md puede no aparecer al arrancar en la raíz, y no es un error.
El problema clásico
Una desarrolladora pasó meses afinando las convenciones de nombres y a ella le salen perfectas. Un compañero nuevo clona el mismo repo y le salen inconsistentes. La causa: las convenciones están en su ~/.claude/CLAUDE.md, que es personal y no viaja por git. La solución es moverlas al CLAUDE.md del proyecto. Lo mismo pasa en CI: el runner no tiene el archivo personal de nadie.
Al revés, una preferencia personal (el idioma de las explicaciones) va en ~/.claude/CLAUDE.md, no en el repo. Y un secreto nunca va en CLAUDE.md: es un archivo más del repo.
Imports para no duplicar
CLAUDE.md puede importar archivos (@import) escribiendo @ seguido de la ruta, por ejemplo @./standards/naming.md o @docs/architecture.md. La ruta se resuelve desde el archivo que contiene el import, y el contenido se carga junto con ese CLAUDE.md. En un monorepo, los estándares compartidos viven en un solo lugar y el CLAUDE.md de cada paquete importa los que le corresponden según lo que sabe su equipo. No existe una palabra clave @import: es @ruta.
Ojo: importar ordena, pero no ahorra contexto, porque lo importado se carga igual.
Partir un archivo grande
Un CLAUDE.md de cientos de líneas sobre muchos temas se parte en reglas por tema (.claude/rules/): un archivo por tema, como testing.md, api-conventions.md y deployment.md, versionados con el repo. Una regla sin paths en el frontmatter se carga siempre, igual que CLAUDE.md; con paths, solo al tocar archivos que coinciden (lo ve la lección 3).
El CLAUDE.md raíz se queda con lo que aplica a casi todas las tareas. Una checklist de release de 40 pasos que se usa una vez por semana va mejor en una skill.
Diagnosticar con /memory
/memory muestra los archivos de memoria del usuario y del proyecto y permite abrirlos. Diagnostica, no carga ni recarga nada: no hay --reload ni --all. Si una regla esperada no aparece, revisá la ruta, el frontmatter y el glob de paths. En las versiones recientes, /context también lista qué archivos se cargaron.
Las trampas típicas
- Pensar que lo de
~/.claude/llega al equipo. - Pedirle al compañero que corra
/memory“para cargar” la configuración. - Instalar un servidor MCP para pasar convenciones: MCP da herramientas, no instrucciones.
- Duplicar las convenciones en cada paquete.
- Poner convenciones universales en una skill, que se carga bajo demanda.
En el examen
Si alguien del equipo no recibe una instrucción, buscá si está a nivel de usuario. Si hay que compartir sin duplicar, @ruta. Si el archivo creció demasiado, .claude/rules/.
Pregunta rápida
Una pregunta del simulacro sobre este dominio. Cuenta para tu progreso.
A payments start-up with eight engineers uses Claude Code across a single TypeScript monorepo. The API lead, Developer A, has spent months refining how Claude Code names endpoints, DTOs and error codes, and the output in her sessions now matches the team's API naming conventions perfectly. The repository has a root CLAUDE.md that covers build commands and the test runner, but says nothing about naming.
Developer B joined last week, cloned the same repository and works on the same branch. In his sessions Claude Code produces inconsistent names: some endpoints are camelCase, others snake_case, and error codes ignore the agreed prefix. He has already reinstalled Claude Code and checked that he is on the latest commit, with no change.
What is the most likely root cause?