CLAUDE.md: qué poner y buenas prácticas (Claude Code)

El CLAUDE.md es un archivo markdown donde escribes las instrucciones permanentes que quieres que Claude Code tenga presentes en tu proyecto: comandos de build, convenciones de código, arquitectura y reglas del tipo "siempre haz X". Claude lo lee al inicio de cada sesión, así dejas de repetir el mismo contexto una y otra vez.

Un matiz importante que casi nadie menciona: el CLAUDE.md se carga como un mensaje del usuario, no como parte del system prompt. Es guía, no configuración forzada. Claude lo lee y trata de seguirlo, pero no es una garantía de cumplimiento estricto. Para algo que debe ejecutarse sí o sí (por ejemplo, antes de cada commit), eso va en un hook, no en el CLAUDE.md.

Dónde va el CLAUDE.md

Puede vivir en varias ubicaciones, cada una con un alcance distinto. Se cargan de más general a más específico, así que lo más cercano a tu proyecto se lee al final y tiene prioridad:

Alcance	Ubicación	Para qué
Usuario	`~/.claude/CLAUDE.md`	Tus preferencias personales en todos los proyectos
Proyecto	`./CLAUDE.md` o `./.claude/CLAUDE.md`	Reglas del equipo, versionadas en git
Local	`./CLAUDE.local.md`	Preferencias personales de ese proyecto (va al `.gitignore`)

Claude recorre el árbol de directorios hacia arriba desde donde lo ejecutas y concatena todos los CLAUDE.md que encuentra. Los CLAUDE.md de subdirectorios no se cargan al inicio: se incluyen cuando Claude lee archivos de esa carpeta. El del directorio raíz, además, sobrevive a un /compact: Claude lo vuelve a leer del disco.

Qué poner (y qué dejar fuera)

La regla mental es simple: el CLAUDE.md es el lugar donde escribes lo que tendrías que volver a explicar. Agrega algo cuando:

Claude comete el mismo error por segunda vez.
Una review detecta algo que Claude debería haber sabido de este código.
Tecleas la misma corrección que ya tecleaste la sesión pasada.
Un compañero nuevo necesitaría ese contexto para ser productivo.

Buen contenido para un CLAUDE.md:

Comandos de build, test y lint del proyecto.
Convenciones: estilo de código, naming, estructura de carpetas.
Arquitectura: decisiones y dónde vive cada cosa.
Reglas "siempre/nunca" que aplican a todo el proyecto.

Qué no poner ahí:

Procedimientos de varios pasos o flujos que solo usas a veces: eso va mejor en un skill, que se carga bajo demanda.
Instrucciones que solo aplican a una parte del código: usa reglas con scope por ruta en .claude/rules/, que solo se cargan cuando Claude toca archivos que coinciden con el patrón.

Las buenas prácticas que de verdad importan

El CLAUDE.md consume tokens de tu ventana de contexto en cada sesión, y la forma en que lo escribes afecta cuánto te hace caso. Tres reglas:

1. Mantenlo corto. Apunta a menos de 200 líneas. Cuanto más largo, más contexto consume y peor lo sigue. Si crece, mueve cosas a reglas con scope por ruta en lugar de acumular todo en un archivo.

2. Sé específico y verificable. Las instrucciones concretas funcionan; las vagas no:

"Usa indentación de 2 espacios" en vez de "formatea bien el código".
"Corre npm test antes de commitear" en vez de "prueba tus cambios".
"Los handlers de API viven en src/api/handlers/" en vez de "mantén los archivos organizados".

3. Estructura y coherencia. Usa encabezados y listas markdown para agrupar instrucciones: Claude escanea la estructura igual que tú. Y revisa que no haya reglas que se contradigan entre el CLAUDE.md raíz, los de subcarpetas y .claude/rules/. Si dos reglas chocan, Claude elige una al azar.

Un extra útil: los comentarios HTML de bloque () se eliminan antes de inyectar el contenido en el contexto, así dejas notas para tu equipo sin gastar tokens.

Importar otros archivos con @ (y el truco con AGENTS.md)

Un CLAUDE.md puede importar otros archivos con la sintaxis @ruta/al/archivo. Se expanden y cargan en el contexto al inicio, junto al CLAUDE.md que los referencia. Aceptan rutas relativas y absolutas, y pueden importar a su vez otros archivos, con un máximo de 4 niveles de profundidad.

Revisa @README para el overview del proyecto.
 
# Instrucciones adicionales
- flujo de git @docs/git-instructions.md

Aquí está el detalle que más vale la pena: Claude Code lee CLAUDE.md, no AGENTS.md. Si tu repo ya usa AGENTS.md para otros agentes (como hago en este sitio), no dupliques nada: crea un CLAUDE.md que lo importe y, debajo, agrega lo específico de Claude.

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

Así ambas herramientas leen las mismas instrucciones desde una sola fuente.

CLAUDE.md, auto memory, skills y hooks: cuándo usar cada uno

Es fácil meter todo en el CLAUDE.md. Mejor reparte:

CLAUDE.md: instrucciones que escribes tú y quieres en cada sesión.
Auto memory: notas que Claude escribe solo a partir de tus correcciones y preferencias (build commands, hallazgos de debugging). No la escribes tú.
Skills: flujos repetibles que se cargan solo cuando hacen falta.
Hooks: comandos que se ejecutan en momentos fijos del ciclo de vida, pase lo que pase. Para enforcement real (no solo guía).

Y si lo que quieres es darle a Claude herramientas nuevas más allá de instrucciones, eso ya es terreno de los servidores MCP: lo explico paso a paso en cómo crear un servidor MCP en TypeScript.

Comandos útiles

/init: genera un CLAUDE.md inicial analizando tu código (comandos, tests, convenciones que detecta). Si ya existe uno, sugiere mejoras en vez de sobrescribir. Si tu repo ya tiene AGENTS.md (o .cursorrules), lo lee e incorpora lo relevante.
/memory: lista los CLAUDE.md y reglas cargados en la sesión y te deja abrirlos para editar. Si algo no aparece ahí, Claude no lo está viendo.

Preguntas frecuentes

¿Dónde se guarda el CLAUDE.md?

En el proyecto va en ./CLAUDE.md o ./.claude/CLAUDE.md (versionado en git). Tus preferencias personales para todos los proyectos van en ~/.claude/CLAUDE.md, y las personales de un proyecto en ./CLAUDE.local.md (añádelo al .gitignore).

¿CLAUDE.md o AGENTS.md?

Claude Code lee CLAUDE.md, no AGENTS.md. Si ya usas AGENTS.md, crea un CLAUDE.md que lo importe con @AGENTS.md y agrega debajo lo específico de Claude. Así no duplicas instrucciones.

¿Qué tan largo debe ser?

Menos de 200 líneas. Los archivos más largos consumen más contexto y reducen qué tanto Claude sigue las instrucciones. Si crece, parte el contenido en reglas con scope por ruta en .claude/rules/.

¿Por qué Claude no sigue mi CLAUDE.md?

Porque es guía, no enforcement: se entrega como mensaje del usuario, no como system prompt. Verifica con /memory que el archivo se está cargando, haz las instrucciones más específicas y elimina reglas que se contradigan. Si algo debe ejecutarse siempre en un momento exacto, escríbelo como un hook.

¿Cómo creo uno rápido?

Corre /init en tu proyecto: Claude analiza el código y genera un CLAUDE.md con comandos, tests y convenciones que detecta. Desde ahí lo refinas con lo que no podría adivinar solo.