Cómo escribir tu CLAUDE.md para que la IA no se pierda

Hubo una época en la que abría el portátil, arrancaba una sesión nueva y me pasaba los primeros diez minutos explicando lo mismo de siempre.

Que el proyecto va de esto. Que los textos van en español de España. Que no toque esa carpeta. Que antes de dar nada por terminado ejecute los tests. Todos los días. Como el día de la marmota, pero con una IA muy educada al otro lado que no se acordaba de nada.

Hasta que entendí que ese trabajo se hace una vez y se guarda en un archivo. Ese archivo es el CLAUDE.md.

¿Qué es exactamente el CLAUDE.md y dónde vive?

Es un archivo de texto plano, en formato Markdown, que vive en la raíz de tu proyecto. Nada más. No hay configuración rara, no hay sintaxis mágica, no hay que instalar nada aparte de Claude Code.

Lo que lo hace especial es cuándo se lee. Cada vez que arrancas una sesión en esa carpeta, Claude se lee ese archivo entero antes de responderte a nada. Va delante de tu primera pregunta. O sea, no es documentación para humanos: son las instrucciones que la máquina tiene en la cabeza mientras trabaja.

La comparación que uso siempre es la del becario nuevo. Un becario muy competente, muy rápido, que se ha leído medio internet, pero que llega el lunes sin saber nada de tu empresa. Puedes explicárselo cada mañana de viva voz, o puedes dejarle una hoja encima de la mesa. El CLAUDE.md es esa hoja.

Y ojo, esto no va de saber programar. Yo lo uso también para carpetas de notas, de documentación y de borradores de contenido. Si estás empezando y te suena todo a chino, tengo una guía de Claude Code para no programadores que te sitúa antes de meterte aquí.

El `/init` te da un borrador, no el archivo final

Dentro de Claude tienes un comando que se llama /init. Lo escribes, le das a enter, y la IA se pone a leerse tu carpeta entera: los archivos, la estructura, el package.json, lo que haya. Con eso te escribe un primer CLAUDE.md.

Está muy bien y te ahorra la página en blanco. Pero es un borrador. Punto.

Lo que sale de ahí describe lo que la IA ha podido deducir mirando el código. Y describir no es instruir. Te va a poner qué framework usas y cómo se arranca el servidor, cosas que además puede ver por su cuenta. Lo que no puede saber es lo que solo está en tu cabeza: que esa carpeta está muerta pero no se toca, que ese cliente pidió una excepción rara, que hay una convención que no está escrita en ningún sitio pero que tú aplicas siempre.

Mi consejo: lanza el /init, quédate con el esqueleto, borra la mitad y escribe tú la parte que importa. Diez minutos bien invertidos.

¿Qué tiene que llevar un buen CLAUDE.md?

Después de reescribir el mío unas cuantas veces, he acabado siempre con las mismas cinco secciones. No hace falta más.

Qué es el proyecto, en dos líneas. Sin épica. Qué hace, para quién, y con qué está montado. Si necesitas un párrafo de quince líneas para explicarlo, el problema no es el archivo.

Cómo se arranca y cómo se prueba. Los comandos exactos. Cómo se levanta el entorno local, cómo se lanzan los tests, cómo se compila. Esto es lo que más tiempo te ahorra, porque sin ello la IA se inventa comandos plausibles que no existen en tu proyecto.

Convenciones. El estilo de la casa. Idioma de los textos, dónde van los componentes, cómo se nombran los archivos, qué librería usáis para las fechas. Todo lo que en un equipo se aprende por ósmosis y que una IA no puede adivinar.

Reglas duras y qué no tocar. La parte que más valor tiene. Carpetas prohibidas, código legacy que aún factura, migraciones que no se modifican, acciones que requieren tu permiso explícito.

Dónde va cada cosa. Si no se lo dices, cada archivo nuevo aparece donde le pilla. Con dos líneas de mapa, todo cae en su sitio.

Un ejemplo genérico, para que veas el tamaño y el tono:

`markdown # Proyecto: Tienda de café

Qué es esto

Web de venta de café en grano. Next.js + Postgres. El cliente compra, recibe un correo y se genera la etiqueta de envío.

Cómo se arranca

• npm run dev levanta el entorno local en el puerto 3000.
• npm test lanza los tests. Tienen que pasar todos antes de dar algo por terminado.
• La base de datos local se levanta con docker compose up db.

Convenciones

• Todo en TypeScript. Nada de archivos .js nuevos.
• Los componentes van en src/components, uno por archivo.
• Los textos de cara al cliente, siempre en español de España.
• Las fechas, siempre en zona horaria Europe/Madrid.

Reglas duras

• No tocar src/legacy/. Es código viejo que sigue facturando.

Si algo de ahí falla, avísame en vez de arreglarlo por tu cuenta.

• No modificar migraciones ya aplicadas. Crear una nueva.
• No hacer commit ni push a menos que yo lo pida.

Dónde va cada cosa

• Documentación técnica → docs/
• Decisiones y sus motivos → docs/decisiones.md
• Scripts sueltos → scripts/

`

Eso es un CLAUDE.md decente para un proyecto normal. Si quieres arrancar desde algo ya montado en vez de desde cero, hay plantillas de CLAUDE.md que puedes copiar y adaptar en un rato.

¿Cómo se escribe una regla que la IA respete de verdad?

Aquí está el 90% de la diferencia entre un archivo que funciona y uno decorativo.

Una regla que funciona tiene tres cosas: es concreta, va en imperativo y lleva el motivo detrás.

Concreta significa que no admite interpretación. "Escribe código limpio" no es una regla, es un deseo. "Cada función en su propio archivo, máximo 50 líneas" sí lo es, porque se puede comprobar si se ha cumplido o no.

En imperativo significa que es una orden, no una descripción del mundo. "Solemos usar TypeScript" invita a excepciones. "Todo el código nuevo va en TypeScript" no.

Y el motivo detrás es el truco que más me ha sorprendido. Cuando explicas por qué, la regla se generaliza sola a los casos que no habías previsto. Compara estas dos:

• "No toques la carpeta legacy."
• "No toques la carpeta legacy. Es el código del checkout viejo, sigue cobrando a clientes reales y no tiene tests. Si algo de ahí falla, avísame en vez de arreglarlo."

Con la primera, la IA respeta la carpeta y punto. Con la segunda, entiende el peligro y también te avisa cuando otro cambio suyo la afecta de rebote. Ese matiz vale oro.

¿Cada cuánto hay que actualizar el CLAUDE.md?

Tengo una regla de dedo muy simple: si corriges lo mismo dos veces, va al archivo.

La primera vez que la IA hace algo que no quieres, se lo dices y ya. Puede ser un despiste. La segunda vez ya no es un despiste, es que falta información. Así que en vez de volver a corregirlo en el chat, paras y añades la línea.

Es un poco antinatural, porque en ese momento te apetece seguir con lo tuyo. Pero es la diferencia entre un archivo que envejece bien y uno que se queda congelado el día que lo creaste.

El otro momento de actualizar es cuando cambia algo estructural: nuevo comando de tests, carpeta que se reorganiza, decisión técnica que se revierte. Si el archivo miente, es peor que si no existiera.

Por qué conviene que sea corto

Un CLAUDE.md de 500 líneas no es cinco veces mejor que uno de 100. Es peor.

Todo lo que metes ahí ocupa espacio en la ventana de contexto, ese espacio va delante de tu pregunta, y cuanto más ruido metas, más se diluye lo importante. Las cinco reglas críticas del proyecto pierden fuerza cuando están enterradas entre cuarenta líneas de relleno.

Mi criterio: si algo no cambia una decisión concreta de la IA, fuera. La historia del proyecto, fuera. La lista de dependencias que ya está en el package.json, fuera. Los agradecimientos, fuera (sí, he visto agradecimientos).

Si el proyecto crece tanto que el archivo se te desmadra, la solución no es apretar la letra: es repartir el contexto en documentos por área que se carguen solo cuando hacen falta. Eso lo cuento a fondo en cómo darle contexto a Claude en un proyecto grande.

Lo que se te va a atascar

El archivo que crece hasta que ya no lo lee nadie. Empieza con 40 líneas útiles y en dos meses tiene 400. Cuando llegues ahí, no lo edites: reescríbelo desde cero mirando el viejo. Se queda en la mitad y funciona el doble.

Reglas que se contradicen. Pasa siempre en archivos que han crecido a parches. Arriba pones "no hagas commits sin permiso" y abajo, tres meses después, "cuando termines una tarea, commit y push". La IA elige una, normalmente la que menos te conviene, y tú te enfadas con ella cuando la culpa es del archivo. Cada vez que añadas una regla, busca si ya hay otra hablando del mismo tema.

Escribir deseos en vez de instrucciones. "Sé cuidadoso", "haz las cosas bien", "piensa antes de actuar". Eso no le dice nada a nadie. Si no puedes comprobar si se ha cumplido, no es una instrucción.

Meter secretos o claves. Nunca. Ni contraseñas, ni tokens, ni cadenas de conexión, ni la IP del servidor con el usuario root al lado. El CLAUDE.md normalmente va al repositorio, y eso significa que va a acabar en sitios donde tú no miras. Las credenciales viven en variables de entorno, y en el archivo pones como mucho el nombre de la variable.

Y ahora qué

Abre tu proyecto, lanza el /init y quédate con el esqueleto. Borra todo lo que la IA ya puede deducir sola mirando el código.

Añade a mano las tres o cuatro reglas duras que ahora mismo repites de viva voz cada sesión. Con su motivo detrás.

Y a partir de ahí, la regla de las dos veces. Cada vez que te pilles corrigiendo lo mismo por segunda vez, para y súbelo al archivo. En dos semanas tienes un proyecto donde la IA arranca sabiendo lo que hace, y tú te ahorras el día de la marmota.

Si lo que quieres es ver esto funcionando de verdad, con un proyecto real montado de principio a fin y no con ejemplos de juguete, es exactamente lo que hacemos en el curso de crear tu web con Claude Code.

Ver el curso