CLAUDE.md

Fichero de instrucciones escritas por humanos que Claude Code carga al inicio de cada sesión y reinyecta desde disco cada vez que el contexto se resetea. En la práctica, es la pieza que distingue una sesión genérica de una sesión contextualizada con el repositorio: sin él, el modelo desconoce los comandos de build, las convenciones de código y las decisiones arquitectónicas que no son inferibles del árbol de ficheros.

Anatomía

Cuatro niveles componen la jerarquía y se concatenan en el contexto en orden de menos a más específico: managed policy, usuario, proyecto y local. La concatenación no es sobrescritura. Las instrucciones de un nivel inferior aparecen después en la secuencia y reciben más peso por sesgo de posición, pero no anulan las de los niveles previos. Tres aspectos del comportamiento de la jerarquía conviene precisar porque inducen a error con frecuencia.

Managed policy precede a todo y no es editable. Es la capa que Anthropic o el administrador de la organización publican mediante cuentas Claude for Work. Cuando está presente, ocupa la posición inicial del contexto y ninguna instrucción de niveles inferiores la sobrescribe; los conflictos los resuelve siempre la capa gestionada. En sesiones donde el comportamiento del modelo contradice una instrucción del repositorio, comprobar si una managed policy está imponiendo la regla opuesta evita diagnósticos erróneos.

CLAUDE.local.md sigue vigente. Pese a rumores periódicos de deprecación, el archivo continúa cargándose como cuarto nivel y es la vía oficial para preferencias personales sobre un repositorio concreto que no deben subir al control de versiones. Su comportamiento en worktrees, en cambio, tiene una particularidad operativa que se trata más adelante.

@imports. Cualquiera de los archivos anteriores puede referenciar ficheros adicionales con la sintaxis @ruta/al/archivo. La ruta se resuelve de forma relativa al archivo que contiene la referencia, no respecto al directorio de trabajo. La profundidad máxima de imports encadenados es cuatro niveles. Los archivos importados se cargan al inicio de la sesión y contribuyen al volumen total de tokens: dividir el contenido en imports mejora la organización del mantenimiento, pero no reduce el consumo de contexto.

Reglas modulares en .claude/rules/. Los archivos bajo este directorio siguen una semántica distinta. Cuando un archivo incluye frontmatter con el campo paths:, sus instrucciones solo se aplican cuando Claude lee o edita ficheros que coinciden con el glob especificado —por ejemplo, una regla con paths: ["src/components/**"] solo entra en el contexto cuando el modelo trabaja con componentes. Sin ese campo, el archivo se comporta como un CLAUDE.md adicional y se carga siempre. El mecanismo permite mantener convenciones específicas que solo ocupan espacio cuando el modelo actúa sobre el área que las requiere.

Frontera con settings.json. Una instrucción en CLAUDE.md se lee, pero su cumplimiento depende de la atención del modelo turno a turno y de su posición en el contexto; un hook declarado en settings.json se ejecuta de forma determinista. Las reglas que deben aplicarse siempre —bloquear escrituras fuera de ciertos directorios, ejecutar el linter antes de un commit— pertenecen al segundo artefacto, no al primero. CLAUDE.md es contexto influyente; settings.json es contrato del cliente.

Funcionamiento

Claude Code carga los archivos CLAUDE.md mediante dos mecanismos distintos según la dirección de navegación.

Al arrancar, Claude Code sube desde el directorio de trabajo hasta la raíz del sistema de archivos buscando archivos CLAUDE.md. Cada uno que encuentra se añade al contexto. Después aplica el nivel de usuario desde ~/.claude/CLAUDE.md. El resultado es una concatenación ordenada de todos los niveles aplicables al directorio de trabajo actual.

La carga en subdirectorios es perezosa: los CLAUDE.md situados en directorios por debajo del CWD no se cargan al inicio, sino cuando el modelo lee un archivo situado bajo ellos. Esto tiene consecuencias directas en monorepos. Un repositorio con múltiples paquetes puede tener un CLAUDE.md en la raíz con instrucciones transversales y otro en packages/api/ con las convenciones específicas de ese paquete. Las instrucciones de packages/api/CLAUDE.md solo entran en el contexto cuando el modelo trabaja con archivos de ese subárbol, lo que permite mantener instrucciones específicas sin que ocupen espacio en tareas que no las necesitan.

El contenido concatenado se inyecta en el contexto como mensaje de usuario, no como system prompt del binario claude. Esta distinción es operativamente importante: el system prompt del binario tiene precedencia absoluta y no es editable; CLAUDE.md ocupa una posición posterior en la secuencia de mensajes y compite con el resto del historial por la atención del modelo. Tras una compactación, CLAUDE.md se reinyecta desde disco, no desde el historial, lo que garantiza que las instrucciones del proyecto se conserven incluso cuando el detalle de la conversación anterior se condensa.

El recordatorio de sistema que acompaña al contenido cargado incluye la nota “this context may or may not be relevant to your tasks”. Este aviso indica al modelo que el contenido puede tener alcance parcial respecto a la tarea actual y que no debe aplicarse indiscriminadamente. Es una razón adicional por la que las instrucciones críticas tienen mayor garantía de cumplimiento cuando se implementan como hooks en settings.json.

El sesgo de posición afecta a qué partes del archivo reciben más atención. El inicio y el final del archivo concentran más peso que el contenido intermedio. Las instrucciones de mayor importancia —los comandos de build, las restricciones de seguridad, las convenciones que no deben omitirse— conviene situarlas cerca del inicio. El contenido auxiliar o de referencia puede ir en la parte media.

Construcción

El archivo inicial generado por /init es un punto de partida que el comando produce a partir del árbol de ficheros, el manifest del proyecto y el historial reciente. La parte interesante empieza después: el borrador suele incluir convenciones estándar del ecosistema —patrones de React, scripts típicos de npm— que el modelo ya conoce por entrenamiento, y omite las decisiones específicas del repositorio que el archivo realmente debe capturar. Las secciones que siguen tratan ese trabajo posterior: qué corregir, qué descartar y qué añadir con mecanismos que no aparecen en la salida automática.

Añadir memoria con el prefijo almohadilla

Cuando una convención emerge durante la sesión —el equipo usa pnpm en lugar de npm, un directorio concreto está fuera de límites, un patrón de nombrado es obligatorio—, la vía más directa para capturarla es escribir el mensaje con un # al inicio seguido de la nota. Por ejemplo: # usamos pnpm, no npm. Claude Code intercepta esa entrada, la interpreta como una instrucción de memoria y abre un selector con los destinos disponibles: los tres niveles de CLAUDE.md —proyecto, usuario o local— o la auto-memoria, un almacén de notas que Claude mantiene en disco al margen del CLAUDE.md. El archivo elegido se actualiza sin necesidad de abrirlo manualmente.

El mecanismo está pensado para notas breves que surgen turno a turno. Para ediciones más extensas —reorganizar secciones, añadir un bloque de convenciones, revisar la estructura completa— el comando /memory abre el archivo en el editor configurado en el entorno, y /memory sin más argumentos lista los CLAUDE.md activos en la sesión con sus rutas y orden de carga, lo que permite verificar que la jerarquía funciona como se espera.

Criterio de omisión

El archivo cumple su función cuando contiene lo que el modelo no puede inferir y omite lo que ya tiene disponible por otra vía. Reglas de estilo que el linter ya aplica, convenciones estándar del ecosistema, esquemas de base de datos completos o descripciones archivo por archivo del árbol no pertenecen al archivo: el modelo los lee directamente cuando los necesita, y duplicarlos en prosa solo consume contexto y se desfasa con la primera modificación. Las preferencias personales no compartidas tampoco entran en el CLAUDE.md del proyecto; su lugar es CLAUDE.local.md o el nivel de usuario.

Anti-patrones recurrentes

Los errores que siguen aparecen con regularidad en proyectos reales y tienen en común que añaden volumen sin aportar información útil al modelo.

Volcar el contenido del README dentro de CLAUDE.md duplica texto que el modelo puede leer directamente del archivo fuente. El resultado son dos versiones del mismo contenido que divergen con el tiempo y generan inconsistencias.

Listar todas las dependencias del proyecto reproduce información que ya está en package.json, pyproject.toml o el equivalente del ecosistema. El modelo accede a esos archivos cuando los necesita; copiar su contenido en prosa solo consume tokens y queda desfasado en la primera actualización de dependencias.

Repetir las reglas del linter o del formateador en CLAUDE.md produce el mismo problema: ESLint, Prettier, Ruff y equivalentes están configurados en archivos que el modelo puede leer. La instrucción en prosa no añade precisión y se vuelve una fuente de contradicciones cuando la configuración del linter cambia y el CLAUDE.md no se actualiza.

Redactar las instrucciones en primera persona como si el texto fuera la voz del modelo —“Soy un asistente que prefiere respuestas cortas”— no corresponde a la función del archivo. CLAUDE.md contiene instrucciones de un humano al modelo, no una autodescripción del modelo. El estilo en primera persona del modelo confunde la autoría y puede interferir con las instrucciones del system prompt del binario.

Documentar decisiones obvias del ecosistema —“usamos React con hooks”, “el estado local se gestiona con useState”— rellena el archivo sin aportar contexto específico del proyecto. El modelo conoce esos patrones por entrenamiento; señalarlos explícitamente no mejora el comportamiento.

Acumular notas de tareas concluidas en CLAUDE.md —“ya se migró el módulo X al nuevo sistema”, “la rama Y está fusionada”— convierte el archivo en un registro de actividad, no en un conjunto de instrucciones activas. Esas notas ocupan espacio en el contexto turno a turno aunque hayan perdido toda relevancia operativa.

Ejemplo real: el CLAUDE.md de anthropics/claude-cookbooks

El repositorio anthropics/claude-cookbooks —la colección oficial de notebooks y ejemplos Python para la API de Claude— incluye un CLAUDE.md que ilustra los criterios anteriores aplicados sobre un proyecto real mantenido por el propio equipo de Anthropic. El archivo es breve, orientado a comandos y concentra las reglas que no son deducibles del código. Sus bloques principales cubren el arranque rápido con los pasos de instalación (uv sync --all-extras, instalación de hooks de pre-commit y configuración del .env), los comandos de desarrollo expuestos como targets de make, las reglas críticas que el modelo podría pasar por alto y apartados adicionales con slash commands del repositorio y descripción de la estructura del proyecto.

## Quick Start

- uv sync --all-extras
- Install pre-commit hooks: uv run pre-commit install
- Copy .env.example to .env and add your ANTHROPIC_API_KEY

## Development Commands

- make format — format with ruff
- make lint — lint with ruff
- make check — format-check + lint (no type-checking)
- make fix — auto-fix issues and format
- make test — run pytest

## Key Rules

- Never commit .env files; load keys via dotenv + os.environ
- Add dependencies with uv add <package>, not by editing pyproject.toml
- Use model aliases without date suffix: claude-sonnet-4-6, claude-haiku-4-5, claude-opus-4-6 — Bedrock IDs follow a separate format documented in the repo
- Keep outputs in notebooks (intentional for demonstration); one concept per notebook
- Run make check before committing; pre-commit hooks validate formatting and notebook structure

El bloque de reglas críticas es el que justifica la existencia del archivo: la prohibición de commitear archivos .env no es inferible del código; la instrucción de usar uv add en lugar de editar pyproject.toml directamente evita un error frecuente que el modelo cometería sin la indicación; el uso de alias de modelo sin fecha de corte es una decisión de mantenimiento que no tiene señal en el árbol de archivos; y conservar las salidas de los notebooks invierte la convención por defecto del ecosistema Jupyter, por lo que sin la regla escrita el modelo las eliminaría. Ninguna de esas reglas se solapa con lo que Ruff ya verifica.

El archivo está disponible públicamente; el extracto reproducido se verificó por última vez el 2026-05-27. La referencia bibliográfica completa se centraliza en content/recursos/referencias-del-sector.md.

Escalado con imports y reglas modulares

Cuando el proyecto crece, la opción recomendada es mantener CLAUDE.md breve y mover el detalle a archivos referenciados. Los archivos en .claude/conventions/ pueden contener guías extensas sobre dominios concretos —estilo de tests, convenciones de API, instrucciones de UI— que el modelo lee bajo demanda cuando trabaja en esa área. La forma habitual es dejar en CLAUDE.md una línea por dominio que apunte al archivo correspondiente e instruya al modelo a leerlo antes de tocar esa zona del código.

Para contenido que solo aplica a partes del árbol de archivos, usa .claude/rules/ con frontmatter paths:. El mecanismo garantiza que esas instrucciones entran en el contexto precisamente cuando son relevantes y no consumen espacio en el resto de la sesión.

AGENTS.md y compatibilidad con otros agentes

Claude Code carga CLAUDE.md, no AGENTS.md. En repositorios que usan ambos agentes y mantienen un AGENTS.md con instrucciones para Codex u otros sistemas, la solución directa es importar ese archivo desde CLAUDE.md mediante una línea @AGENTS.md. De este modo las instrucciones son visibles para todos los agentes sin duplicarlas. Una alternativa es un symlink de CLAUDE.md a AGENTS.md, útil cuando ambos archivos deben ser idénticos.

CLAUDE.local.md en worktrees

CLAUDE.local.md presenta un comportamiento particular en flujos con worktrees paralelos: cada worktree tiene su propio CLAUDE.local.md, lo que significa que una preferencia personal configurada en uno no está disponible en los demás. La solución es centralizar esas preferencias en ~/.claude/CLAUDE.md y referenciarlas desde el nivel de usuario, o importarlas explícitamente con una línea del tipo @~/.claude/preferencias.md.

Límites

Cumplimiento no garantizado. CLAUDE.md se inyecta como mensaje de usuario, no como system prompt. El modelo puede no seguir una instrucción incluida en él, especialmente cuando la instrucción entra en tensión con información más reciente en el historial o con los tool results acumulados en los últimos turnos. El recordatorio “this context may or may not be relevant” refuerza esa no garantía. Las instrucciones que deben cumplirse siempre —ejecutar el linter antes de un commit, bloquear escrituras fuera de ciertos directorios— son más fiables implementadas como hooks en settings.json.

Sesgo de posición en archivos extensos. El modelo presta más atención al inicio y al final del archivo que al contenido intermedio. En archivos que superan las 200 líneas, las instrucciones situadas en la parte media pierden efectividad de forma progresiva. La mitigación es mantener el archivo breve y mover el detalle a archivos de convención con carga bajo demanda.

Los imports no reducen tokens. Dividir el contenido en múltiples archivos referenciados mejora la organización pero no el consumo de contexto: todos los archivos importados se cargan al inicio de la sesión. Si el objetivo es reducir el volumen inicial de instrucciones, la opción correcta es el mecanismo de carga bajo demanda mediante indicaciones explícitas en la prosa, no los imports.

Tiempo de carga y profundidad de imports. La cadena de imports tiene una profundidad máxima de cuatro niveles. Una jerarquía de imports muy profunda prolonga el tiempo de arranque de la sesión y dificulta el diagnóstico cuando una instrucción no se aplica correctamente. La práctica recomendada es mantener la jerarquía plana: un CLAUDE.md de proyecto que importa archivos en .claude/conventions/, sin encadenar más niveles.

Los subagentes heredan CLAUDE.md por defecto

Los subagentes definidos en .claude/agents/ heredan automáticamente la jerarquía completa de memoria —managed policy, ~/.claude/CLAUDE.md, CLAUDE.md del proyecto y CLAUDE.local.md— además del system prompt declarado en su propio frontmatter. La consecuencia operativa es que un subagente personalizado conoce las convenciones del repositorio sin necesidad de replicarlas en su prompt, y respeta las restricciones de nombrado, los comandos de build o las reglas de seguridad declaradas en CLAUDE.md con el mismo nivel de adherencia —no garantizada, pero presente— que la sesión principal.

Las excepciones explícitas son los agentes integrados Explore y Plan: ambos omiten intencionadamente el CLAUDE.md del proyecto y el estado de git para mantener la investigación rápida y reducir el consumo de contexto. Esto introduce un patrón de fallo concreto: delegar en Explore o Plan tareas en las que las convenciones del repositorio son relevantes —por ejemplo, una búsqueda cuyo resultado se usará para escribir código— puede producir salidas que ignoran reglas declaradas en CLAUDE.md. La práctica habitual es reservar esos dos agentes para investigación pura y, cuando el resultado deba aplicarse al código, devolver la decisión al hilo principal o a un subagente personalizado que sí hereda la jerarquía.