CLAUDE.md. El archivo que Claude Code lee en cada sesión

Un archivo CLAUDE.md guarda las reglas que quieres que Claude Code cumpla en tu proyecto. Cuando existe, cada sesión arranca sabiendo cómo trabajas y dejas de repetir lo mismo en el primer mensaje.

La cosa tiene algo más de miga, porque el archivo puede vivir en varios sitios y cada uno cambia a quién afecta. Además, Claude Code guarda por su cuenta una segunda memoria con lo que aprende de ti, y hay que saber distinguirlas.

Aquí tienes dónde guardarlo, una plantilla para copiar y qué revisar si no te hace caso, para que funcione desde la primera sesión.

Un archivo de texto que Claude Code lee antes de la primera pregunta

Cada vez que empiezas una sesión, la conversación arranca desde cero. Lo que le contaste ayer sobre tu app, con qué la construiste o qué carpeta no debe tocar, ya no está en la conversación de hoy.

Con el archivo, las normas de estilo y las decisiones del proyecto se cargan solas al arrancar. Escribes una vez "los textos van en español y de tú" y listo. Se redacta en lenguaje corriente, sin sintaxis que aprender, en un archivo de texto plano al que puedes poner títulos y listas.

Al arrancar, Claude Code carga el CLAUDE.md de la carpeta donde lo abres y los de las carpetas que la contienen. Si hay uno dentro de una subcarpeta, se lee solo cuando Claude entra a trabajar ahí.

Y algo que hay que saber desde ya, el archivo por sí solo no obliga a nada. Claude lo lee y trata de seguirlo, no es un ajuste que se aplique a la fuerza.

Guarda el archivo donde Claude Code va a buscarlo

Hay tres ubicaciones que vas a usar, y cada una cambia el alcance de las reglas. La de usuario está en ~/.claude/CLAUDE.md, donde ~ es tu carpeta personal, y se aplica a todos tus proyectos.

La del proyecto admite dos rutas. Puedes ponerlo directamente en la carpeta principal del proyecto, ./CLAUDE.md, o dentro de una carpeta .claude que suele estar oculta por empezar con punto, ./.claude/CLAUDE.md. Ahí van las reglas que comparte todo el que trabaje en el proyecto.

La local, ./CLAUDE.local.md, va en la misma carpeta y guarda tus preferencias personales. Si el proyecto usa Git, la herramienta que comparte una copia del proyecto con el resto del equipo, ese archivo se subiría con todo lo demás. Para que se quede en tu ordenador, añádelo al .gitignore, la lista de lo que Git no sube.

Cuando hay varios archivos, las instrucciones se suman en vez de sustituirse. Claude Code las junta todas, de la más general a la del proyecto, y trabaja con el conjunto.

Crea tu primer archivo sin escribirlo desde cero

Tienes dos vías para tenerlo listo, una automática en la que Claude Code lo escribe por ti y otra manual con una plantilla que ajustas a lo que construyes. Empieza por la automática, que te da una base sobre la que corregir en lugar de una página en blanco.

Deja que /init lo redacte leyendo tu proyecto

Con Claude Code abierto en la carpeta de tu proyecto, escribe /init. Claude recorre los archivos, detecta con qué está construido y cómo se organiza, y prepara un primer CLAUDE.md. Después te toca añadir lo que no puede deducir solo, como el tono de los textos.

Si el archivo ya existe, /init propone mejoras en lugar de sobrescribirlo. Y si antes usabas Cursor o Copilot, otras herramientas de programación con IA, /init lee por su cuenta las reglas que tuvieras escritas para ellas e incorpora lo que aplique.

Un caso aparte es AGENTS.md, el archivo equivalente que usan esas otras herramientas. Claude Code lee CLAUDE.md y no AGENTS.md, así que si ya tienes uno, crea un CLAUDE.md con una sola línea, @AGENTS.md. Esa arroba carga el otro archivo como si estuviera copiado ahí, y debajo añades lo que solo aplique a Claude.

Copia esta plantilla y ajústala a lo que construyes

La plantilla recoge lo que Claude Code necesita saber antes de tocar nada, en siete apartados. Qué es el proyecto, con qué está hecho, qué tareas se repiten, dónde va cada archivo, cómo se escribe, qué no se toca y en qué punto está. La clave es que cada línea lleve una regla que pueda seguir, más que una descripción.

"Es una app de reservas" informa, mientras que "comprueba que se puede reservar antes de dar por terminado un cambio" se cumple. El modelo de abajo está escrito sobre una app sencilla de reservas construida con Lovable. Cámbialo por lo tuyo y borra lo que no aplique.

# Reservas Sol

## Identidad del proyecto
Trabajas en una app de reservas para un estudio de yoga con clientes reales. Evita cambios que rompan lo que ya funciona.

## Herramientas
La app está hecha con Lovable y guarda los datos en Supabase. No añadas otra herramienta sin preguntarme.

## Tareas que se repiten
Antes de dar un cambio por terminado, comprueba que se puede crear, editar y cancelar una reserva.

## Organización de archivos
Las pantallas van en src/pages y los elementos reutilizables en src/components. Crea los nuevos ahí.

## Convenciones de estilo
Escribe los textos visibles en español, de tú y sin tecnicismos.

## Zonas que no se tocan
No edites el archivo .env ni la configuración de pagos sin pedírmelo antes.

## Estado actual
La reserva ya funciona y estamos con los recordatorios por email. Consúltame cualquier cambio fuera de eso.
Revisa esto si Claude Code no hace caso a tus instrucciones

Esta parte es para cuando ya tienes el archivo escrito y no notas ninguna diferencia, con dos cosas que revisar en este orden. Al final de la sección tienes la explicación de por qué Claude puede saltarse una regla aunque el archivo esté bien.

Comprueba antes que el archivo se ha cargado

Lo primero es confirmar que Claude Code ha leído el archivo, y para eso está el comando /context. Escríbelo dentro de la sesión y busca la lista "Memory files", que muestra qué archivos de instrucciones ha cargado en esa conversación. Si el tuyo no aparece, Claude no lo ve.

En ese caso, revisa que esté en una de las ubicaciones de la tabla anterior y que se llame exactamente CLAUDE.md, no CLAUDE.txt ni claude.md.txt.

Para abrirlo y corregirlo sin buscar la carpeta, escribe /memory. Ese comando lista todas las ubicaciones posibles, incluidas las de archivos que todavía no existen, y abre la que elijas en tu editor. Lo que no hace es decirte cuál se ha cargado, eso solo lo sabe /context.

Repasa si la regla es vaga o choca con otra

Si el archivo carga pero la regla no se cumple, mira cómo está escrita. Una instrucción como "cuida el diseño" deja margen, y Claude decide a su manera cómo aplicarla. Pídele en cambio que use los colores y la tipografía de la pantalla de inicio en cualquier pantalla nueva, y podrás comprobar si lo hace.

La otra causa habitual es que tu archivo de usuario diga una cosa y el del proyecto otra sobre el mismo punto, y entonces Claude Code puede quedarse con cualquiera de las dos. Abre los dos a la vez y busca la regla que se pisa con otra.

Tus reglas entran como mensaje y no como configuración

Claude Code recibe primero un prompt de sistema, las instrucciones internas que definen cómo se comporta la herramienta, y el contenido de tu CLAUDE.md entra después como un mensaje tuyo, como si lo hubieras escrito al empezar la conversación.

Eso lo convierte en contexto, la información que Claude tiene delante, y no en una configuración que garantice el cumplimiento. Cuando algo tiene que cumplirse siempre, la vía es un hook de Claude Code, una acción que se ejecuta sola en un momento fijo, haga lo que haga Claude.

Claude Code también guarda memoria por su cuenta

Además del CLAUDE.md, que escribes tú con las reglas que quieres que se cumplan, existe una memoria automática que escribe Claude con tus correcciones y con lo que aprende trabajando contigo.

Esa memoria vive en ~/.claude/projects/<proyecto>/memory/, con un índice llamado MEMORY.md que se carga al empezar cada sesión. Se queda en tu ordenador y no viaja con el repositorio, así que un compañero que abra el mismo proyecto no la tiene.

Claude no guarda ahí lo que puede deducir del código ni lo que ya dice tu CLAUDE.md. Es un apoyo, y las reglas que quieres que se cumplan siguen teniendo que estar en tu archivo.

Como también condiciona las respuestas, échale un vistazo cada cierto tiempo. Desde /memory puedes abrir la carpeta, editar o borrar cualquier nota y desactivar la memoria automática si prefieres que no guarde nada.

No todo tiene que ir dentro de CLAUDE.md

Dentro va lo que hace falta en casi todas las sesiones, como con qué está hecho el proyecto y tus convenciones. Fuera va lo que solo se usa de vez en cuando y lo que tiene que cumplirse aunque Claude no haga caso.

Un procedimiento que solo sigues a veces, como publicar una versión nueva, sale a una skill, una instrucción guardada que Claude carga cuando la invocas con /nombre o cuando ve que hace falta. Una tarea larga, como revisar decenas de archivos, va a un subagente de Claude Code, que trabaja aparte y te devuelve solo el resumen.

Lo que tiene que ejecutarse siempre sale a un hook, como viste en el diagnóstico. Y las instrucciones que solo aplican a una parte del proyecto salen a la carpeta .claude/rules/, con un archivo por tema que indica a qué rutas afecta.

La documentación larga, como una guía de estilo, va aparte y se trae con un import, la misma línea con @ y la ruta que viste con AGENTS.md, por ejemplo @docs/guia-estilo.md. Se pueden encadenar hasta cuatro archivos. Sirve para tener el CLAUDE.md ordenado, no para aligerar la sesión, porque lo importado se carga igual.

Errores que van dejando tus instrucciones sin efecto

Ninguno de estos errores rompe el archivo, Claude Code lo sigue cargando y por eso cuesta darse cuenta de que las reglas han dejado de funcionar.

El archivo crece y Claude deja de hacer caso

El archivo ya tiene cientos de líneas y Claude se salta reglas que antes cumplía. La documentación oficial de Claude Code recomienda mantenerlo por debajo de 200 líneas, porque cuanto más largo, más espacio ocupa en cada sesión y menos caso hace.

Para corregirlo, escribe /doctor, que revisa el CLAUDE.md del proyecto y propone qué recortar. Después mueve tú lo que solo se usa a veces a los sitios de la sección anterior y borra lo que Claude puede deducir del código, como la lista de carpetas.

Datos privados que acaban en el repositorio

Alguien encuentra una clave de acceso o una contraseña en el CLAUDE.md compartido, y ya es tarde. Es un archivo que viaja con el proyecto, así que todo lo que escribas dentro lo ve quien tenga acceso al repositorio.

Las claves se quedan en archivos de configuración como el .env que aparece en la plantilla, y lo personal va al CLAUDE.local.md añadido al .gitignore, que ya tienes en la tabla de ubicaciones.

Reglas que nunca llegan al resto del equipo

A ti Claude te hace caso y a un compañero no, en el mismo proyecto. La causa suele estar en la ubicación, porque la regla está en tu archivo de usuario o en el local, y ninguno de los dos se comparte.

Revisa con /memory en qué archivo está cada regla y mueve al CLAUDE.md del proyecto todo lo que deba cumplir cualquiera que trabaje en él.

Un archivo que se queda viejo y ya no describe el proyecto

Claude insiste en una herramienta que dejaste de usar o busca carpetas que ya no existen. El archivo sigue describiendo el proyecto tal como era al escribirlo, y Claude trabaja sobre uno que ya no es el tuyo.

Ponte un recordatorio para revisarlo cada cierto tiempo, junto a las reglas de .claude/rules/ y a la memoria automática, y borra lo que ya no aplique. Volver a ejecutar /init también ayuda.

‍

Para que Claude Code siga tu CLAUDE.md hacen falta pocas cosas, que esté donde lo busca, que aparezca en la lista de /context, que cada línea sea una regla concreta, que quepa en menos de 200 líneas y que no choque con otro archivo. Lo demás tiene mejor sitio en una skill, un hook o la carpeta de reglas.

Si quieres aprender a construir con Claude Code de principio a fin, en el curso de Claude Code te enseñamos a montar tu primer proyecto sin necesidad de programar. Empieza gratis.