El archivo que Claude lee antes que nada

Qué es y por qué importa

Cada sesión de Claude Code empieza con el contexto vacío. Lo que le explicaste ayer en el chat, hoy no está. Así que empiezas de cero: «a ver, mi app es…». Y las veces que se te olvida, él adivina: la herramienta, la carpeta, cuánto puede cambiar.

Para eso sirve el CLAUDE.md. Es un archivo de texto sencillo, en la carpeta del proyecto, con las reglas que quieres que valgan siempre. Claude Code lo lee al empezar cada sesión, antes incluso de tu primer mensaje. Por eso lo llamo el archivo que Claude lee antes que nada.

Importa porque escribes una sola vez lo que si no repetirías cada día. Él empieza sabiéndolo ya, y tú vas directo a lo que quieres hacer.

Una cosa que conviene saber desde ya: es una indicación, no un candado. Claude lo lee e intenta seguirlo, y cuanto más claras son las reglas, más las sigue. Pero para bloquear algo de verdad no basta: hablo de eso en las preguntas del final.

1. Mi archivo, para copiar

Aquí tienes mi archivo para copiar, sobre una app de ejemplo: un recetario. Son diez líneas. Cambia las partes entre < > por las de tu proyecto y quita los símbolos < >.

# <Recetario>: <app de recetas>
Stack: <Next.js y TypeScript>
Código en <src/>, tests en <tests/>
No toques <.env> ni <la carpeta de pagos>
Pregunta antes de borrar archivos
Lee antes de cambiar
Después de cada cambio: <npm test>, y dime el resultado
Un cambio a la vez
Háblame en español
Escribe el código en inglés

Las líneas sin < > las dejo iguales en todos los proyectos. Es más, las que valen en todas partes, como el idioma, las paso al archivo de mi usuario: lo vemos enseguida.

2. Las diez líneas explicadas

Cada línea está ahí porque me quitó un problema que tenía a menudo:

1. Qué es la app. Se acabó el «a ver, mi app es…» en cada sesión nueva.
2. Con qué está hecha. No te propone herramientas distintas de las que ya usas.
3. Dónde está el código y dónde los tests. No los busca cada vez.
4. Qué no debe tocar. Las claves y el dinero siguen siendo tuyos: las claves secretas suelen estar en el archivo .env, y los pagos son la parte donde un error hace más daño. Pero es una indicación, no un bloqueo: para bloquearlo de verdad hace falta una regla deny o un hook. Hablo de ello en la guía GUARDIA (strikt.fit/guardia).
5. Pregunta antes de borrar. Nada de borrados por sorpresa.
6. Lee antes de cambiar. Entiende lo que hay antes de reescribirlo.
7. El comando de los tests. Es el que demuestra que la app sigue funcionando. Y le pido el resultado, no solo que lo lance.
8. Un cambio a la vez. Cambios pequeños: si algo se rompe, sabes dónde.
9. El idioma. Te responde en tu idioma.
10. El código en inglés. Nombres, funciones y comentarios se quedan en inglés, como los lee cualquiera.

Son todas cosas que no se ven en el código, o que solo se ven buscando: es justo lo que vale la pena escribir.

3. Dónde va

El nombre es siempre CLAUDE.md. Lo que cambia es la carpeta, y la carpeta decide dónde vale:

• En la carpeta principal del proyecto: ./CLAUDE.md, o ./.claude/CLAUDE.md. Son equivalentes, elige uno. Contiene las reglas de ese proyecto, y si el proyecto está en git, las ve también quien trabaja en él contigo.
• En el archivo de tu usuario: ~/.claude/CLAUDE.md. Las reglas que valen para todos tus proyectos, como el idioma, van aquí. Solo las ves tú.

Claude Code los lee al empezar cada sesión, los dos: se suman, no se sustituyen. Así que en el proyecto no repitas lo que ya está en el archivo de tu usuario, y procura que no se contradigan: si dos líneas dicen cosas opuestas, Claude puede seguir una u otra.

Cuando cambies un archivo, abre una sesión nueva: así te aseguras de que trabaja con la versión actualizada.

4. Cómo crearlo y modificarlo

1. Abre Claude Code en la carpeta del proyecto y escribe /init. Mira tu código y te escribe un primer CLAUDE.md, con los comandos para compilar y probar el proyecto y las convenciones que encuentra. Si ya hay un CLAUDE.md, no lo sobrescribe: te propone mejoras.
2. Luego añades tú las reglas que no puede adivinar solo: qué no debe tocar, cómo quieres que trabaje, en qué idioma hablarte. Son las de mi archivo de arriba.
3. Para modificarlo, escribe /memory. Te enseña los archivos de memoria del proyecto y de tu usuario. Eliges el archivo y se abre en tu editor; si no existe, lo crea.
4. Para comprobar que lo ha cargado, en una sesión nueva escribe /context y mira la lista debajo de Memory files. Tienen que estar tus CLAUDE.md: si falta uno, Claude no lo ve.

Las reglas nuevas también puedes hacer que las escriba él. Cuando te das cuenta de que falta una:

Añade esta regla al CLAUDE.md del proyecto: [la regla]. Escríbela en una línea, corta y precisa.

Importa cómo lo dices. Con «añádelo al CLAUDE.md» acaba en el archivo. Si solo le dices «acuérdate de que…», normalmente lo guarda en su memoria automática, que es otra cosa: la explico en las preguntas del final.

5. Mantenlo corto

Mantenlo corto y preciso: cuanto más claras y pocas son las reglas, más las sigue. La documentación de Claude Code recomienda quedarse por debajo de las 200 líneas por archivo: por encima, las reglas se siguen peor.

Preciso quiere decir que se puede comprobar. «Después de cada cambio lanza npm test» funciona mejor que «prueba bien el código». «El código está en src/» funciona mejor que «ten los archivos ordenados».

Y luego hay que mantenerlo vivo. Yo sigo tres reglas:

• Si le repites lo mismo dos veces, es una línea que falta: añádela.
• Si una línea ya no es verdad, quítala.
• Si es algo que Claude ve solo abriendo el código, no hace falta escribirlo.

Errores comunes

• Dejar el archivo de /init tal cual. Es una base: añade las reglas que no se ven en el código, como qué no tocar y en qué idioma hablarte.
• Repetir en cada proyecto las reglas que valen en todas partes. Ponlas una sola vez en ~/.claude/CLAUDE.md.
• Escribir reglas vagas, tipo «ten cuidado». Escribe cosas que se puedan comprobar: un comando, una carpeta, un archivo.
• Tratarlo como un candado. Es una indicación: para bloquear de verdad un archivo hace falta una regla deny en los permisos de Claude Code o un hook.
• Cambiarlo y seguir en la misma sesión dando por hecho que lo ve. Abre una sesión nueva y compruébalo con /context.

Lista de comprobación

• El CLAUDE.md está en la carpeta principal del proyecto
• Las partes entre < > ya hablan de mi proyecto
• Está el comando que lanza los tests
• El idioma está en ~/.claude/CLAUDE.md, no en cada proyecto
• En una sesión nueva, /context lo muestra debajo de Memory files
• Es corto, sin líneas repetidas ni desfasadas

Preguntas frecuentes