CLAUDE.md: cómo conseguir que Claude Code recuerde tu proyecto

Abres Claude Code un lunes y vuelves a explicarle lo mismo que el viernes: que la web es para una clínica, que los textos van en español, que el proyecto se arranca con npm run dev y que la carpeta de facturas no se toca. Cada sesión empieza en blanco.

El reel del 9 de noviembre lo resumía en una frase: lo que pongas en CLAUDE.md, lo recuerda. Aquí va lo que no cabía en 30 segundos: dónde se guarda, qué poner y qué no, y cómo comprobar que de verdad lo está leyendo.

Qué es CLAUDE.md

Es un archivo de texto en Markdown que Claude Code lee al empezar cada sesión. Piensa en el documento que le darías a alguien que entra nuevo en tu empresa el primer día: de qué va el proyecto, cómo se arranca y qué normas hay.

La diferencia con un prompt es que no lo tienes que repetir. La diferencia con una base de datos es que no es memoria exacta: es contexto. Claude lo lee y lo tiene en cuenta, pero no es una regla que el programa obligue a cumplir. Eso tiene consecuencias que verás más abajo.

Créalo en un minuto con /init

Dentro de tu proyecto, abre Claude Code y escribe:

/init

Claude revisa el código y crea un CLAUDE.md con los comandos de arranque, los tests y las convenciones que detecta. Si ya tienes uno, no lo pisa: te propone mejoras.

Deberías ver un archivo CLAUDE.md nuevo en la raíz. Ábrelo y léelo: es un borrador, no la versión final. Lo que /init no puede adivinar (para quién es la web, qué no se toca, cómo te gusta trabajar) lo tienes que añadir tú.

Dónde puede vivir (y por qué importa)

No hay un solo CLAUDE.md. Según la documentación de Claude Code, hay varios sitios y se leen todos, del más general al más concreto:

Archivo	Para qué sirve	¿Se comparte?
`~/.claude/CLAUDE.md`	Tus preferencias en todos tus proyectos	No, solo en tu ordenador
`./CLAUDE.md` o `./.claude/CLAUDE.md`	Las normas del proyecto	Sí, va en el repositorio
`./CLAUDE.local.md`	Tus notas personales de ese proyecto	No, añádelo al `.gitignore`

Hay un detalle útil: si arrancas Claude en una subcarpeta, también lee los CLAUDE.md de las carpetas de arriba. Y los de las subcarpetas los carga cuando trabaja con archivos de esa subcarpeta, no antes. Así puedes tener normas generales en la raíz y normas solo para el backend en backend/CLAUDE.md.

Cambia dónde arrancas Claude en la figura para verlo:

Dónde arrancas ClaudeRaíz del proyectobackend/

Claude ha tocado un archivo de backend/

~/.claude/CLAUDE.md25 líneas
CLAUDE.md120 líneas
CLAUDE.local.md15 líneas
backend/CLAUDE.md60 líneas

La baraja que se está leyendoCajones: de arriba abajo, del archivo más general al más concretoCorredera: hasta dónde se carga al arrancarClaude lee los archivos de memoria del más general al más concreto y los junta en ese orden: el de tu usuario, luego el CLAUDE.md de cada carpeta desde la raíz hasta donde arrancas, y el CLAUDE.local.md justo detrás del CLAUDE.md de su carpeta. El de backend/ no se carga al arrancar en la raíz: entra cuando Claude lee o edita un archivo de esa carpeta. Proyecto de ejemplo, en líneas: ~/.claude/CLAUDE.md con 25, CLAUDE.md con 120, CLAUDE.local.md con 15, backend/CLAUDE.md con 60. La regla mide en líneas y el calibre marca las 200 que la documentación recomienda no pasar por archivo.

Lo que acabas de ver: cada cajón es un archivo de memoria y cada baraja, sus líneas. Al arrancar se abren los cajones que quedan por encima de la corredera, de arriba abajo, y sus fichas pasan a la bandeja en el orden en que Claude las lee. La última que entra es la más concreta.

Si arrancas en la raíz, el cajón de backend/ se queda cerrado hasta que Claude toca un archivo de esa carpeta. Si arrancas dentro de backend/, entra desde el principio. Fíjate también en la regla: todo lo que hay en la bandeja ocupa contexto en cada sesión, y el calibre marca las 200 líneas que conviene no pasar en ningún archivo.

Mi forma de repartirlo: en el global, cómo me gusta trabajar ("propón un plan antes de un cambio grande", "resume al final qué has comprobado"). En el del proyecto, todo lo que necesitaría saber cualquiera que tocase ese código.

Qué poner

La documentación lo deja claro: instrucciones concretas que se puedan comprobar. Compara:

Vago	Concreto
"Formatea bien el código"	"Indenta con 2 espacios"
"Prueba los cambios"	"Ejecuta `npm test` antes de dar algo por terminado"
"Mantén los archivos ordenados"	"Los endpoints van en `src/api/handlers/`"

Para la web de una clínica dental, un CLAUDE.md útil se parece a esto:

# Web Clínica Sonrisa

## Qué es
Web de una clínica dental en Sevilla. Objetivo: que los pacientes pidan cita.

## Comandos
- Arrancar: `npm run dev`
- Comprobar antes de terminar: `npm run build`

## Normas
- Textos en español de España, tono cercano, tuteando.
- Colores y tipografías solo los de `styles/tokens.css`.
- No toques `content/precios.json` sin preguntar: los precios los decide la clínica.
- Antes de un cambio de más de 3 archivos, propón un plan y espera mi OK.

Tienes la plantilla completa para copiar en el recurso de CLAUDE.md.

Un buen momento para añadir una línea: cuando Claude comete el mismo error dos veces, o cuando te descubres corrigiéndole lo mismo en cada sesión.

Qué no poner

Novelas. La recomendación oficial es mantener cada CLAUDE.md por debajo de unas 200 líneas. Todo lo que pongas ocupa contexto en cada sesión, lo uses o no.
Procedimientos largos. Si es "cómo se publica un post, paso a paso", eso es una skill o un comando, que solo se carga cuando lo pides. Lo cuento en la entrada sobre comandos personalizados.
Contradicciones. Si una línea dice "usa npm" y otra "usa pnpm", Claude elegirá una de las dos, y no sabrás cuál. Revisa el archivo de vez en cuando y borra lo que ya no vale.
Claves y contraseñas. El CLAUDE.md del proyecto va al repositorio. Nada que no publicarías.

Importa otros archivos en vez de copiarlos

Si ya tienes un README o un documento de normas, no lo dupliques. Escribe la ruta con @ delante y Claude lo carga junto al CLAUDE.md:

Visión general del proyecto en @README.md y comandos disponibles en @package.json.
Normas de git: @docs/git.md

Las rutas son relativas al propio CLAUDE.md. Ojo: importar no ahorra contexto, solo evita tener la misma información en dos sitios.

Comprueba que lo está leyendo

Dos comandos te lo dicen:

/memory muestra qué archivos de memoria hay en tu proyecto y en tu usuario, y te deja abrir cualquiera para editarlo.
/context enseña cómo se reparte el contexto de la sesión, incluidos los archivos de memoria cargados.

Si un CLAUDE.md no aparece, lo normal es que esté en una carpeta que Claude todavía no ha tocado o que el nombre esté mal escrito.

Lo que CLAUDE.md no hace

Aquí está la trampa: CLAUDE.md es contexto, no una cerradura. Si escribes "nunca hagas push a main", lo normal es que lo respete, pero nada se lo impide. Para lo que tiene que cumplirse siempre, la documentación recomienda los hooks, que son comandos que Claude Code ejecuta él mismo antes o después de cada acción, o las reglas de permisos.

Además, Claude Code tiene una memoria automática que guarda por su cuenta cosas que aprende de ti (por ejemplo, que prefieres pnpm). Es útil, pero vive solo en tu ordenador y la gestiona Claude. Lo que tiene que saber todo el equipo va en CLAUDE.md.

Tu siguiente paso

Abre tu proyecto, escribe /init, lee lo que genera y añade tres normas que hoy repites a mano. Con eso ya no empiezas cada sesión desde cero. Si todavía no tienes Claude Code instalado, empieza por la guía de instalación y los primeros prompts.