CLAUDE.md: qué es y cómo se configura

CLAUDE.md es un archivo Markdown que Claude Code lee al empezar cada sesión para saber cómo trabajar en tu proyecto. No se instala ni se configura: basta con crearlo y escribir en él lo que, si no, tendrías que volver a explicarle al agente en cada conversación.

Qué es CLAUDE.md

Cada sesión de Claude Code arranca con el contexto vacío. El agente no recuerda que ayer le dijiste que los tests se lanzan con pnpm test, que el proyecto no usa dark mode o que no debe tocar las migraciones. CLAUDE.md es la forma de que lo sepa siempre: Claude Code lo carga en el contexto antes de tu primer mensaje.

El archivo es Markdown normal, sin sintaxis especial ni esquema obligatorio. Encabezados para agrupar, listas para las reglas y bloques de código para los comandos. Si sabes escribir un README, sabes escribir un CLAUDE.md, y si no, la sintaxis básica de Markdown es todo lo que necesitas.

Hay un matiz importante que conviene tener claro desde el principio: Claude trata el CLAUDE.md como contexto, no como configuración obligatoria. Es una instrucción muy fuerte, pero no un candado. Si algo no debe ocurrir nunca, como un git push a la rama principal, la herramienta correcta son los permisos o los hooks de Claude Code, que se aplican pase lo que pase.

Dónde se coloca

Puede haber varios CLAUDE.md a la vez, cada uno con un alcance distinto. Estos son los niveles que documenta Anthropic, del más general al más concreto:

El de proyecto es el que más vas a usar. Se commitea con el código, así que todo el equipo trabaja con las mismas instrucciones. El CLAUDE.local.md es para lo que solo te afecta a ti, como la URL de tu entorno de pruebas, y debe ir en el .gitignore.

El de usuario es más útil de lo que parece. Ahí van las cosas que repites en todos los proyectos: en qué idioma quieres que te hable, qué stack usas por defecto o qué librerías propias debe considerar antes de añadir dependencias.

Cómo lo carga Claude Code

Claude Code busca CLAUDE.md en el directorio donde lo lanzas y en todos los directorios superiores. Si arrancas en proyecto/web/, carga tanto proyecto/web/CLAUDE.md como proyecto/CLAUDE.md.

Los archivos no se sustituyen entre sí, se concatenan. Todo lo que encuentra entra en el contexto, de lo más general a lo más concreto, así que las instrucciones más cercanas al directorio de trabajo se leen las últimas. Esto tiene una consecuencia práctica: si el CLAUDE.md de usuario y el de proyecto se contradicen, Claude puede seguir cualquiera de los dos. Mantenlos coherentes.

Los CLAUDE.md de subdirectorios funcionan de otra forma. No se cargan al arrancar, sino cuando Claude lee o edita un archivo de esa carpeta. Es una forma cómoda de dar instrucciones específicas a una parte del código sin cargar el contexto de la sesión con ellas.

Cómo crear tu primer CLAUDE.md

La forma más rápida es ejecutar /init dentro de una sesión de Claude Code. El agente analiza el repositorio y genera un CLAUDE.md de partida con los comandos de build, la forma de lanzar los tests y las convenciones que detecta. Si ya existe uno, propone mejoras en lugar de sobrescribirlo.

Ese primer borrador es un punto de partida, no el resultado final. /init solo puede escribir lo que se deduce del código. Lo valioso de un buen CLAUDE.md es justo lo que no se deduce: decisiones tomadas, errores que ya se cometieron y cosas que no hay que tocar.

Si prefieres hacerlo a mano, crea el archivo en la raíz igual que cualquier otro archivo .md. Esta es una estructura que funciona bien:

# Nombre del proyecto

## Stack
- Next.js con pages router y salida estatica
- Tailwind CSS 3
- Contenido en archivos .mdx dentro de src/pages/

## Comandos
- `npm run dev`: servidor de desarrollo
- `npm run lint`: linter, fuera del build

## Convenciones
- Todo el contenido y la UI en espanol
- Los commits, en espanol

## No hacer
- No subir Tailwind a v4: el sitio usa la API de la v3
- No borrar las fuentes de src/fonts/: las usa el generador de imagenes OG

Un ejemplo real

Este mismo sitio tiene su CLAUDE.md, y la parte que más trabajo ahorra no es la del stack, sino la de las trampas que solo se conocen después de haber caído en ellas. Un fragmento:

## Convenciones

- npm install requiere --legacy-peer-deps por conflicto de peer deps
- Los code blocks con code fences anidados necesitan 4 backticks
  en el bloque exterior para evitar que MDX rompa
- tailwindcss esta pineado a 3.2.4 exacto en package.json.
  NO subir a v4: el sitio usa la API v3 de PostCSS

## Deploy en Vercel

- El Build Command esta overrideado en el dashboard y NO coincide
  con el de package.json. Cambiar package.json no cambia lo que
  ejecuta Vercel

Fíjate en el patrón: cada regla dice qué hacer y por qué. Sin el porqué, el agente cumple la regla al pie de la letra pero no sabe aplicarla a un caso parecido. Con el porqué, generaliza bien.

Cómo escribir instrucciones que se cumplan

La documentación de Anthropic insiste en que la forma de escribir las instrucciones influye en lo fielmente que se siguen. Estos son los principios que más diferencia marcan en la práctica.

Reglas concretas y verificables

Una regla que no se puede comprobar no sirve de mucho. Compara estas dos formas de decir lo mismo:

• "Formatea bien el código" frente a "Usa indentación de 2 espacios".
• "Prueba los cambios" frente a "Ejecuta npm test antes de hacer commit".
• "Mantén el proyecto ordenado" frente a "Los handlers de la API van en src/api/handlers/".

La segunda versión de cada par deja claro cuándo se ha cumplido y cuándo no, y eso es lo que permite al agente seguirla.

Corto, mejor que completo

Anthropic recomienda no pasar de unas 200 líneas por archivo. Un CLAUDE.md largo ocupa más contexto en cada sesión y, sobre todo, hace que las instrucciones se cumplan peor: todas compiten por la atención del modelo.

Si algo solo importa en una parte del código, no lo pongas en el archivo principal. Para eso están las reglas por rutas y las skills, que veremos más abajo.

Añade reglas a partir de errores reales

El momento de añadir una línea no es cuando se te ocurre, sino cuando el agente comete el mismo error por segunda vez. Las otras señales que propone Anthropic son igual de prácticas: cuando una revisión de código detecta algo que el agente debería haber sabido, cuando escribes en el chat la misma corrección que la sesión anterior o cuando un compañero nuevo necesitaría ese mismo contexto.

Usa la estructura de Markdown

Agrupar las instrucciones bajo encabezados y en listas no es una cuestión estética. Un bloque denso de párrafos es más difícil de seguir para el modelo que secciones claras. Es la misma idea que explicamos en Markdown en prompts: la estructura le dice al modelo qué va con qué.

Funciones avanzadas

Cuando el proyecto crece, un solo archivo se queda corto. Claude Code tiene varias formas de organizar las instrucciones sin perder el control.

Importar otros archivos con @

Un CLAUDE.md puede incluir otros archivos con la sintaxis @ruta/al/archivo. El contenido importado se carga junto al archivo que lo referencia:

Resumen del proyecto en @README.md y comandos disponibles en @package.json.

## Flujo de trabajo
- Git: @docs/git-instructions.md

Las rutas relativas se resuelven desde el archivo que hace la importación, y los archivos importados pueden importar a su vez otros, con un máximo de cuatro saltos. Ojo con una cosa: importar organiza, pero no ahorra contexto, porque todo lo importado se carga igualmente al arrancar.

Reglas por rutas en .claude/rules/

Para proyectos grandes puedes repartir las instrucciones en archivos temáticos dentro de .claude/rules/. Lo interesante es que cada regla puede limitarse a ciertos archivos con un campo paths en el frontmatter:

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

# Reglas de la API

- Todos los endpoints validan la entrada
- Usa el formato de error estandar

Esta regla solo entra en el contexto cuando Claude trabaja con archivos que coinciden con el patrón. Las reglas sin paths se cargan siempre, igual que el CLAUDE.md.

Comentarios para humanos

Los comentarios HTML de bloque (<!-- nota -->) se eliminan antes de pasar el archivo a Claude. Sirven para dejar notas a quien mantiene el archivo sin gastar contexto en ellas. Es la misma sintaxis que usamos para añadir comentarios en Markdown.

CLAUDE.md y AGENTS.md

AGENTS.md es la convención que comparten varias herramientas de programación con IA para no tener un archivo distinto por cada una. Claude Code puede leerlo directamente: si en el proyecto hay un AGENTS.md y ningún CLAUDE.md, usa el AGENTS.md como instrucciones del proyecto.

Si tienes los dos, por defecto Claude Code lee solo el CLAUDE.md. Para tener un único archivo que valga para todas las herramientas y añadir encima lo específico de Claude, la solución que documenta Anthropic es importar uno desde el otro:

@AGENTS.md

## Claude Code

Usa el modo plan para cambios en src/billing/.

Así el contenido común vive en AGENTS.md, que leen las demás herramientas, y CLAUDE.md solo añade lo que es propio de Claude.

CLAUDE.md, memoria automática y skills

Claude Code tiene otros dos mecanismos que se confunden con CLAUDE.md y que conviene distinguir.

La memoria automática son notas que escribe el propio Claude a partir de tus correcciones, sin que tengas que hacer nada. CLAUDE.md lo escribes tú; la memoria automática, el agente. Se gestiona con el comando /memory. Si te interesa el concepto, lo comparamos con las memorias de los chatbots en memorias persistentes en ChatGPT y Claude.

Las skills son instrucciones que solo se cargan cuando hacen falta. Si una entrada de tu CLAUDE.md es un procedimiento de varios pasos, como publicar una versión o escribir un artículo siguiendo una plantilla, probablemente debería ser una skill. Lo explicamos en SKILL.md, cómo escribir skills de Claude.

La regla para decidir dónde va cada cosa es sencilla: en CLAUDE.md va lo que Claude debe saber en todas las sesiones. Lo demás, fuera.

Errores comunes

Estos son los fallos que más se repiten al escribir un CLAUDE.md:

• Reglas vagas: "escribe código limpio" no se puede verificar. Sustitúyela por un criterio concreto.
• Archivo kilométrico: pasar de 200 líneas diluye las instrucciones. Mueve lo específico a reglas por rutas o a skills.
• Contradicciones entre niveles: una regla en el CLAUDE.md de usuario y la contraria en el de proyecto. El agente elegirá una cualquiera.
• Reglas sin porqué: el agente las cumple al pie de la letra, pero no sabe aplicarlas a un caso parecido.
• No actualizarlo: un CLAUDE.md que menciona comandos o archivos que ya no existen confunde más que ayuda.
• Usarlo como candado: si algo no debe pasar nunca, configúralo en los permisos o con un hook, no solo en el texto.

Para los detalles que cambian con las versiones de Claude Code, como nuevas opciones o rutas, consulta la documentación oficial de memoria de Claude Code.

Recursos relacionados

• AGENTS.md, el estándar para agentes de IA: el archivo equivalente que comparten varias herramientas
• SKILL.md, cómo escribir skills de Claude: instrucciones que solo se cargan cuando hacen falta
• Cómo usar MarkItDown con Claude: convertir documentos a Markdown y conectarlos a Claude Code
• Guía Markdown de Claude: cómo renderiza Claude el Markdown y qué sintaxis admite
• System prompts con Markdown: cómo escribir instrucciones persistentes para agentes
• Markdown en prompts: por qué la estructura mejora las respuestas del modelo
• llms.txt: el archivo Markdown que ayuda a los agentes a leer tu web