CLAUDE.md en Claude Code: qué es, dónde se carga y qué poner

CLAUDE.md es el archivo Markdown donde escribes las instrucciones que Claude Code debe tener presentes en cada sesión: comandos de build y test, convenciones del repositorio, decisiones de arquitectura que no se deducen del código. Esta guía explica dónde lo busca Claude Code, en qué orden lo carga, qué conviene poner y qué no, cómo se relaciona con /init, /memory, AGENTS.md, skills y settings, y cómo comprobar si el agente lo está aplicando. Todo está contrastado con la documentación oficial de Claude Code a octubre de 2026 (la última versión del changelog en esa fecha es la 2.1.292).

Qué es CLAUDE.md y qué no es

Cada sesión de Claude Code empieza con una ventana de contexto vacía. Hay dos mecanismos que llevan conocimiento de una sesión a otra:

• CLAUDE.md: instrucciones que escribes tú. Claude Code las carga al inicio de cada sesión.
• Auto memory: notas que Claude escribe para sí mismo a partir de tus correcciones y preferencias, guardadas en un MEMORY.md por repositorio.

Lo importante es cómo se tratan esas instrucciones. Según la documentación, el contenido de CLAUDE.md se entrega como un mensaje de usuario después del prompt de sistema, no como parte de él, y Claude lo trata como contexto, no como configuración obligatoria. Claude lo lee e intenta seguirlo, pero no hay garantía de cumplimiento estricto, sobre todo si las instrucciones son vagas o se contradicen. Si algo tiene que ocurrir siempre o no debe ocurrir nunca, el sitio es un hook o una regla de permisos, no CLAUDE.md.

Dónde se carga: la jerarquía completa

Claude Code busca CLAUDE.md en varios ámbitos. La tabla los recoge en el orden en que se cargan, del más amplio al más concreto:

Orden de carga y qué pasa si dos archivos se contradicen

Claude Code carga CLAUDE.md y CLAUDE.local.md del directorio de trabajo y de todos los directorios superiores. Si arrancas en foo/bar/, lee foo/bar/CLAUDE.md, foo/CLAUDE.md y los CLAUDE.local.md que haya junto a ellos.

Los archivos no se sobrescriben entre sí: se concatenan. El orden va de la raíz del sistema de archivos hacia tu directorio de trabajo, así que las instrucciones más cercanas a donde lanzaste Claude se leen al final, y dentro de cada directorio CLAUDE.local.md va después de CLAUDE.md. Que algo se lea más tarde no le da prioridad formal: la documentación avisa de que, si dos instrucciones se contradicen, Claude puede elegir una de forma arbitraria. La solución es no tener contradicciones, no confiar en el orden.

CLAUDE.md en subdirectorios

Los CLAUDE.md que están por debajo del directorio de trabajo no se cargan al arrancar. Claude Code los incluye cuando Claude usa las herramientas Read, Write o Edit sobre un archivo de ese subdirectorio. Por eso sirven para instrucciones que solo importan en una parte del repositorio (un paquete de un monorepo, por ejemplo), y por eso no conviene poner ahí nada que deba regir toda la sesión.

En monorepos grandes donde se cuelan CLAUDE.md de otros equipos, el setting claudeMdExcludes permite excluir archivos por ruta o patrón glob. El CLAUDE.md de política gestionada no se puede excluir.

CLAUDE.local.md sigue existiendo

CLAUDE.local.md se carga junto a CLAUDE.md y se trata igual. Sirve para lo que no debe ir al repositorio: URLs de tu entorno de pruebas, datos de test que prefieres. Claude Code no lo añade a .gitignore por su cuenta: tienes que hacerlo tú, salvo que uses el flujo interactivo de /init (con CLAUDE_CODE_NEW_INIT=1) y elijas la opción personal, que sí lo hace.

Si trabajas con varios git worktrees del mismo repositorio, un CLAUDE.local.md ignorado por git solo existe en el worktree donde lo creaste. Para compartir instrucciones personales entre worktrees, la documentación propone importar un archivo de tu home (ver la sección siguiente).

Imports con @

Un CLAUDE.md puede importar otros archivos con la sintaxis @ruta/al/archivo:

Visión general del proyecto en @README y comandos disponibles en @package.json.

# Instrucciones adicionales
- Flujo de git: @docs/git-instructions.md
- Preferencias personales: @~/.claude/mi-proyecto.md

Reglas que conviene conocer:

• Las rutas relativas se resuelven respecto al archivo que contiene el import, no respecto al directorio de trabajo. También valen rutas absolutas.
• Un archivo importado puede importar otros, hasta una profundidad máxima de cuatro saltos.
• Los imports dentro de bloques de código o entre comillas invertidas no se procesan: escribir `@README` deja el texto literal.
• Para una ruta con espacios, escapa cada espacio con una barra invertida (@Design\ Docs/api.md).
• La primera vez que un CLAUDE.md de proyecto importa algo fuera del directorio de trabajo, Claude Code muestra un diálogo de aprobación. Si lo rechazas, esos imports quedan desactivados.
• Los archivos importados se cargan al arrancar, junto al CLAUDE.md que los referencia. Los imports organizan un archivo largo, pero no reducen lo que ocupa en contexto.

Reglas por ruta con .claude/rules/

Para repositorios grandes, puedes repartir instrucciones en archivos dentro de .claude/rules/. Una regla sin frontmatter se carga al arrancar, con la misma prioridad que .claude/CLAUDE.md. Una regla con el campo paths solo entra en contexto cuando Claude lee, escribe o edita un archivo que coincide con el patrón:

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

# Reglas de la API
- Todos los endpoints validan la entrada
- Usa el formato de error estándar del proyecto

Es la herramienta indicada para lo que solo afecta a un lenguaje o a un directorio, y lo que permite mantener corto el CLAUDE.md principal. También existen reglas de usuario en ~/.claude/rules/, que se cargan antes que las del proyecto.

Qué poner en CLAUDE.md y qué dejar fuera

La guía de buenas prácticas oficial resume el criterio en una pregunta para cada línea: ¿si la quito, Claude cometería errores? Si no, sobra. Su tabla de qué incluir y qué excluir:

Además, la documentación da estas pautas concretas:

• Tamaño: apunta a menos de 200 líneas por archivo. Los archivos más largos consumen más contexto y reducen la adherencia. Claude Code carga un CLAUDE.md de hasta 4 MiB y se salta uno mayor, pero ese es el límite técnico, no un objetivo.
• Instrucciones verificables: "Usa indentación de 2 espacios" en lugar de "formatea bien el código"; "Ejecuta npm test antes de hacer commit" en lugar de "prueba tus cambios".
• Estructura: encabezados y viñetas, no párrafos densos.
• Énfasis con moderación: si Claude se salta una instrucción concreta, añade un "IMPORTANT" solo a esa línea. Si enfatizas muchas, ninguna destaca.
• Comentarios para humanos: los comentarios HTML a nivel de bloque (<!-- nota -->) se eliminan antes de inyectar el archivo en el contexto, así que puedes dejar notas a los mantenedores sin gastar tokens.
• Cuándo ampliarlo: cuando Claude repite un error, cuando una revisión de código detecta algo que debería haber sabido, o cuando escribes en el chat la misma aclaración que en la sesión anterior.

Un CLAUDE.md de ejemplo que sigue esas pautas (ilustrativo; los comandos y rutas dependen de tu proyecto):

# Comandos
- Tests: `pnpm test`
- Lint: `pnpm lint`
- Ejecuta lint y los tests afectados antes de dar una tarea por terminada

# Convenciones
- Módulos ES (import/export), nunca CommonJS (require)
- Los handlers de la API viven en `src/api/handlers/`
- Nombres de rama: `feat/...`, `fix/...`

# Trampas conocidas
- Los tests de integración necesitan la variable `DATABASE_URL`
- IMPORTANT: usa pnpm, nunca npm, para instalar o añadir dependencias

<!-- Revisar esta sección cuando cambie el ORM -->

Si un procedimiento de varios pasos o una guía solo importa a veces (cómo hacer un despliegue, cómo escribir una migración), no lo metas aquí: va en una skill o en una regla por ruta.

Cómo se relaciona con /init, /memory, AGENTS.md, skills y settings

/init

/init analiza el código y genera un CLAUDE.md inicial con comandos de build, instrucciones de test y convenciones que detecta. Si ya existe un CLAUDE.md, propone mejoras en lugar de sobrescribirlo. También lee reglas de otras herramientas (.cursor/rules/, .cursorrules, .github/copilot-instructions.md) e incorpora lo relevante. Con la variable CLAUDE_CODE_NEW_INIT=1, /init pasa a un flujo interactivo que pregunta qué configurar (CLAUDE.md, skills, hooks), explora el código con un subagente y presenta una propuesta revisable antes de escribir nada.

Trata el resultado como un borrador: revísalo línea a línea con el criterio de la tabla anterior y añade lo que Claude no podría descubrir solo.

/memory y auto memory

/memory lista tus CLAUDE.md, CLAUDE.local.md y demás archivos de memoria de usuario y proyecto (incluso los que aún no existen), los abre en tu editor y permite activar o desactivar auto memory y abrir su carpeta.

Auto memory está activada por defecto en sesiones locales. Guarda las notas en ~/.claude/projects/<proyecto>/memory/, con un índice MEMORY.md del que se cargan al inicio las primeras 200 líneas o los primeros 25 KB, lo que llegue antes. Se desactiva desde el propio /memory, con "autoMemoryEnabled": false en los settings o con CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Ojo con la diferencia al pedir que recuerde algo: si dices "recuerda que los tests de la API necesitan Redis local", Claude lo guarda en auto memory. Para que vaya a CLAUDE.md, pídelo explícitamente ("añade esto a CLAUDE.md") o edítalo tú con /memory. El antiguo atajo de empezar un mensaje con # para añadir una memoria se eliminó en la versión 2.0.70; la nota del changelog indica que ahora se le pide a Claude que edite el CLAUDE.md.

AGENTS.md

Desde la versión 2.1.277, Claude Code puede leer AGENTS.md directamente. El comportamiento por defecto:

Para ese chequeo no cuentan tu ~/.claude/CLAUDE.md, el CLAUDE.md gestionado ni los archivos de .claude/rules/. Un detalle que pilla desprevenido: crear un CLAUDE.local.md en un proyecto que depende de AGENTS.md hace que Claude deje de leer AGENTS.md. El comportamiento se cambia en /config con el ajuste Project instructions (por ejemplo, claude-md-and-agents-md para leer ambos).

Si quieres un único archivo para varias herramientas y además instrucciones solo para Claude, la opción que recomienda la documentación es un CLAUDE.md que importa AGENTS.md:

@AGENTS.md

## Claude Code

Usa plan mode para cambios en `src/billing/`.

Un enlace simbólico CLAUDE.md → AGENTS.md también funciona, pero la documentación desaconseja esa vía si alguien trabaja en Windows: crear symlinks requiere privilegios de administrador o modo desarrollador, y Git hace checkout del symlink como un archivo de texto de una línea si core.symlinks no está activado.

Skills

Una skill es un archivo SKILL.md dentro de .claude/skills/<nombre>/ (o ~/.claude/skills/<nombre>/ para las personales), con un frontmatter cuyo campo description ayuda a Claude a decidir cuándo cargarla. La diferencia con CLAUDE.md es cuándo entra en contexto: CLAUDE.md se carga en todas las sesiones; de una skill solo se carga la descripción, y el contenido completo cuando la invocas con /nombre o Claude la considera relevante. Los antiguos comandos de .claude/commands/ se han fusionado con las skills y siguen funcionando.

La regla práctica de la documentación: en CLAUDE.md lo que Claude debe saber siempre; en una skill el material de referencia que necesita a veces o el flujo que lanzas con un comando.

Settings y hooks

Los archivos de settings (~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json y los gestionados) los aplica el cliente al margen de lo que decida Claude. CLAUDE.md orienta el comportamiento, pero no es una capa de imposición. La documentación lo reparte así:

Cómo comprobar si Claude está aplicando tu CLAUDE.md

Escribir una instrucción no garantiza que se cumpla. Conviene separar dos preguntas: si el archivo se ha cargado y si, cargado, se sigue.

1. ¿Se ha cargado?

• /context: muestra el uso de contexto; en la lista Memory files aparecen los CLAUDE.md y CLAUDE.local.md cargados al arrancar. Si uno no está ahí, Claude no lo ve.
• Subdirectorios: un CLAUDE.md de subdirectorio no sale en Memory files, porque se carga bajo demanda. Cuando se carga aparece en el terminal una línea Loaded con su ruta. Para probar uno nuevo, créalo desde tu shell (no pidiéndoselo a Claude) y luego pide a Claude que lea un archivo de ese subdirectorio.
• AGENTS.md: comprueba con /memory que su ruta aparece en la lista.
• Hook InstructionsLoaded: se dispara cada vez que se carga un CLAUDE.md o un archivo de .claude/rules/, e incluye la ruta, el ámbito (memory_type) y el motivo (load_reason: session_start, nested_traversal, path_glob_match, include o compact). Útil para depurar reglas por ruta y archivos de subdirectorios.

Un ejemplo de configuración para registrar las cargas en un log, escrito según el formato de la referencia de hooks y pensado para .claude/settings.local.json. Necesita jq en el PATH; pruébalo en tu entorno antes de fiarte de él:

{
  "hooks": {
    "InstructionsLoaded": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{file_path, memory_type, load_reason}' >> \"$HOME/.claude/instructions-loaded.log\""
          }
        ]
      }
    ]
  }
}

2. ¿Se está siguiendo?

• Observa el comportamiento: la guía de buenas prácticas propone tratar CLAUDE.md como código y probar cada cambio comprobando si el comportamiento de Claude cambia de verdad. Si Claude te pregunta algo que ya está respondido en el archivo, la redacción probablemente es ambigua.
• Busca contradicciones entre el CLAUDE.md de usuario, el de proyecto, los de subdirectorios y las reglas. /doctor prompt-audit (desde la versión 2.1.283) revisa tus archivos de instrucciones en busca de contenido obsoleto, referencias a archivos o comandos que no existen y contradicciones, y propone cambios sin aplicarlos hasta que se lo pidas.
• Revisa el tamaño: si un archivo supera la longitud recomendada, Claude Code muestra un aviso al arrancar y en /status. /doctor propone recortes en un CLAUDE.md versionado eliminando lo que Claude puede deducir del código.
• Comprueba si compites con instrucciones integradas: si tu CLAUDE.md fija reglas de commits o pull requests, la documentación indica desactivar las instrucciones de git integradas con el setting includeGitInstructions y fijar el texto de atribución con attribution.
• Si tiene que pasar siempre, conviértelo en hook: una instrucción que debe ejecutarse en un momento fijo funciona mejor como hook, que se ejecuta independientemente de lo que decida Claude.

3. ¿Desaparece tras /compact?

El CLAUDE.md de la raíz del proyecto sobrevive a la compactación: tras /compact, Claude Code lo vuelve a leer del disco y lo reinyecta. Los CLAUDE.md de subdirectorios y las reglas con paths: se vuelven a cargar bajo demanda, cuando se toca un archivo que los activa. Si una instrucción se pierde tras compactar, la documentación apunta a tres causas: que solo se diera en la conversación, que viva en un CLAUDE.md anidado que aún no se ha recargado o en una regla por ruta que no ha vuelto a coincidir con ningún archivo.

Preguntas frecuentes

¿Dónde se guarda el CLAUDE.md global de Claude Code?

En ~/.claude/CLAUDE.md. Se aplica a todos tus proyectos en esa máquina y se carga antes que el CLAUDE.md del proyecto. Por encima solo está el CLAUDE.md de política gestionada que despliega una organización, que no se puede excluir.

¿Cuántas líneas debería tener un CLAUDE.md?

La documentación oficial recomienda apuntar a menos de 200 líneas por archivo, porque los archivos más largos consumen más contexto y reducen la adherencia. Lo que solo importa en una parte del código va mejor en reglas con paths o en CLAUDE.md de subdirectorios, que se cargan bajo demanda.

¿Los imports con @ ahorran contexto?

No. Los archivos importados con @ se expanden y se cargan al arrancar, junto al CLAUDE.md que los referencia. Ayudan a organizar, pero ocupan lo mismo que si el contenido estuviera escrito en el propio archivo.

¿Claude Code lee AGENTS.md?

Sí, desde la versión 2.1.277. Por defecto lo lee solo si no hay ningún CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo o por encima. Para leer ambos, cambia el ajuste Project instructions en /config o importa @AGENTS.md desde tu CLAUDE.md.

¿CLAUDE.md garantiza que Claude cumpla una regla?

No. La documentación lo define como contexto, no como configuración impuesta, y advierte de que no hay garantía de cumplimiento estricto. Para bloquear acciones usa permissions.deny en los settings o un hook PreToolUse; para acciones que deben ocurrir siempre, un hook.

¿Qué diferencia hay entre CLAUDE.md y MEMORY.md?

CLAUDE.md lo escribes tú y contiene instrucciones; MEMORY.md es el índice de auto memory, lo escribe Claude con lo que aprende de tus correcciones y vive en ~/.claude/projects/<proyecto>/memory/. Ambos se cargan al inicio de cada sesión, MEMORY.md solo hasta 200 líneas o 25 KB.