Escribir un buen CLAUDE.md

En el post anterior vimos cómo dirigir sesiones largas con Claude Code, que es el primer capítulo del curso Claude Code in Action de Anthropic.

El segundo capítulo entra en un fichero que cualquiera que use Claude Code para sus proyectos acaba teniendo en sus proyectos: CLAUDE.md.

Para mi era como una mezcla entre documentación del repositorio y manual de instrucciones para Claude Code. Y más o menos puede ser así, pero no al pie de la letra. Al final el bueno de Claudio va haciendo cosas y muchas veces se equivoca.

Para esto la tendencia que vamos a tener es añadir instrucciones a CLAUDE.md. Tipo no commitees y pushees directamente a main. pregunta antes de pushear o las sql para dev serán todas formateadas me lo invento eh, por poner algo. Entonces si cada vez que nos encontramos algo así, le ponemos la instrucción. El fichero CLAUDE.md acabará siendo un fichero enorme donde hasta el bueno de Claude Code se perderá y acabará omitiendo datos.

La propuesta de esta parte del curso es bastante sensata. CLAUDE.md tiene que contener el contexto que Claude necesita en todas las sesiones, escrito de la forma más concreta y breve posible. No es una enciclopedia del proyecto ni un lugar donde acumular cada detalle que alguna vez podría resultar útil.

CLAUDE.md orienta, pero no obliga

Lo primero que hay que tener claro es que CLAUDE.md no es un archivo de configuración estricto. Claude Code carga su contenido en la ventana de contexto y utiliza esas instrucciones para decidir cómo trabajar, pero siguen siendo instrucciones para un modelo.

Eso significa que una regla puede interpretarse mal, entrar en conflicto con otra o perder peso entre cien indicaciones más. Si algo tiene que cumplirse siempre, no deberíamos dejar la seguridad en manos de una frase escrita en Markdown.

Imagina que en el repositorio está prohibido hacer push directamente a main. Podemos escribir esto:

- Nunca hagas push directamente a main.

Ayuda, pero no impide que el comando se ejecute. Para una restricción estricta es mejor utilizar los permisos o un hook previo que compruebe la rama y bloquee la operación.

CLAUDE.md sirve para guiar decisiones. Los mecanismos deterministas sirven para hacer cumplir restricciones.

• Los controladores HTTP viven en src/api/handlers es contexto del proyecto y encaja en CLAUDE.md.

• Ejecuta el formateador después de editar un archivo puede automatizarse con un hook.

• No permitas comandos que lean el directorio de secretos debería aplicarse mediante permisos.

• Crea una release siguiendo estos siete pasos tiene más sentido como skill que solo se carga cuando se necesita.

Si intentamos resolverlo todo con CLAUDE.md, el fichero crece y aun así las reglas realmente críticas no quedan garantizadas.

Cuatro lugares con cuatro alcances

No existe un único CLAUDE.md. Claude Code puede cargar instrucciones desde varios niveles y las acumula de lo más general a lo más específico.

Política administrada

Es el archivo que despliega la organización para todos los usuarios de una máquina. Sirve para convenciones corporativas, requisitos de seguridad y normas de cumplimiento compartidas por todos los proyectos.

El usuario no puede excluirlo, aunque su contenido sigue siendo una guía de comportamiento. Las restricciones técnicas que la empresa necesite imponer deben vivir en la configuración administrada, no solamente en este Markdown.

Instrucciones del usuario

El archivo ~/.claude/CLAUDE.md se aplica a todos tus proyectos. Aquí encajan tus preferencias personales y las herramientas que utilizas siempre.

# Preferencias personales

- Responde en español.
- Utiliza `rg` para buscar texto y archivos.
- No crees commits salvo que te lo pida expresamente.

No metería aquí decisiones que solo tienen sentido en un repositorio. Si escribes usa pnpm como preferencia global, seguro que se lo acabarás diciendo también en un proyecto que funciona con npm.

Instrucciones del proyecto

El equipo puede guardar el archivo en ./CLAUDE.md o ./.claude/CLAUDE.md y versionarlo con Git. Este es el lugar para la arquitectura, los comandos de desarrollo y las convenciones que debería conocer cualquiera que trabaje en el repositorio.

# Comandos

- `pnpm test`: ejecuta los tests.
- `pnpm build`: genera la aplicación para producción.

# Arquitectura

- Las rutas están en `src/pages`.
- Los componentes reutilizables están en `src/components`.
- El contenido del blog está en `src/content/posts`.

Debería explicar lo que no resulte evidente al explorar el código. Copiar el README entero o enumerar cada carpeta aporta contexto, pero no necesariamente contexto útil.

Instrucciones locales

./CLAUDE.local.md contiene preferencias personales para un proyecto concreto y normalmente se añade a .gitignore. Es útil para una URL de pruebas propia, datos locales o notas temporales de la rama en la que estás trabajando.

# Entorno local

- Para las pruebas manuales utiliza `http://tienda.local`.
- La base de datos disponible contiene datos ficticios.

Así no obligas al resto del equipo a cargar unas instrucciones que solo sirven en tu máquina.

Además de estos cuatro niveles, puede haber archivos CLAUDE.md dentro de subdirectorios. Los que están por debajo del directorio desde el que arrancaste se cargan cuando Claude trabaja con archivos de esa zona. Esto permite colocar las reglas del frontend junto al frontend y las del backend junto al backend en vez de inflar el archivo raíz.

Corto no quiere decir que sea incompleto

La documentación de memoria de Claude Code recomienda intentar mantener cada CLAUDE.md por debajo de 200 líneas. No es un límite técnico ni ocurre ninguna desgracia en la línea 201. Es una referencia para recordar que todo el archivo ocupa contexto en cada sesión y que, cuanto más ruido tenga alrededor, menos destacarán las instrucciones importantes.

La pregunta que yo haría a cada línea es: ¿Claude necesita saber esto en la mayoría de las sesiones? Si la respuesta es no, seguramente exista un sitio mejor para ella.

Una explicación extensa de cómo publicar una versión puede convertirse en una skill. Las convenciones exclusivas de los tests pueden vivir junto a ese directorio. Un documento de arquitectura puede quedarse en docs y consultarse cuando haga falta. Una restricción técnica debería implementarse con permisos o hooks.

Mantener el archivo corto tampoco consiste en escribir mensajes cripticos imposibles de entender. Hay instrucciones que necesitan explicar el motivo para que Claude Code pueda aplicarlas cuando aparece un caso dudoso.

- No añadas una segunda librería de fechas; el proyecto ya utiliza date-fns.

Esa línea ocupa un poco más que no instales librerías, pero dice qué se quiere evitar y cuál es la alternativa.

Dividir con imports no ahorra contexto

Cuando el archivo se hace incómodo de mantener, podemos separar su contenido mediante imports con @.

# CLAUDE.md

Consulta @README.md para los comandos principales.

# Convenciones

- API: @.claude/conventions/api.md
- Tests: @.claude/conventions/tests.md
- Accesibilidad: @.claude/conventions/accessibility.md

Esto deja el documento principal bastante más ordenado, pero no reduce el contexto utilizado. Claude Code expande los archivos importados y carga su contenido al iniciar la sesión.

Los imports van genial para organizarnos, pero no nos va a reducir el tamaño del contexto.

Si las instrucciones solo se aplican a determinados archivos, las reglas con rutas de .claude/rules/ sí permiten cargarlas cuando Claude Code trabaja con esa parte del proyecto. Y si el contenido solo es necesario para una tarea concreta, una skill evita tenerlo presente durante todas las conversaciones.

Escribir reglas que se puedan comprobar

Escribe código limpio, sigue buenas prácticas o haz tests suficientes suenan genial, pero cada persona puede entender una cosa distinta por cada una de ellas y Claude Code también.

Una buena regla describe un comportamiento que se puede comprobar viéndolo.

# Demasiado ambiguo

- Organiza bien las rutas de la API.
- Prueba los cambios.
- Mantén los componentes pequeños.

# Concreto y verificable

- Crea cada ruta de la API en un archivo dentro de `src/api/handlers`.
- Antes de terminar, ejecuta `pnpm test` y `pnpm build`.
- Extrae un componente cuando se reutilice en dos páginas.

No hace falta convertir cada preferencia en una especificación de la NASA. Es suficiente con reducir el espacio para las interpretaciones que no nos sirven.

También ayuda escribir la alternativa junto a la prohibición.

- Usa exports con nombre; no utilices default exports.
- Usa los componentes de `src/ui`; no escribas controles HTML equivalentes desde cero.
- Devuelve errores con `ApiError`; no construyas respuestas de error manualmente.

Decir solamente no uses default exports obliga a Claude Code a deducir qué patrón queremos. Si incluimos el reemplazo, le estamos dando una dirección en lugar de prohibirle y ya.

Si todo es IMPORTANTE, nada lo es

Las mayúsculas, IMPORTANTE, NUNCA y OBLIGATORIO sirven para llamar la atención sobre una norma especialmente crítica. El problema viene cuando medio documento está redactado como si estuviera evacuando un edificio en llamas.

# Seguridad

- IMPORTANTE: nunca incluyas valores reales de `.env` en respuestas, logs o commits.

Ese énfasis tiene sentido porque señala una excepción entre instrucciones normales. Si lo aplicamos también al formato de las comas, al nombre de los tests y al orden de los imports, Claude Code deja de tener pistas sobre qué debe priorizar cuando dos reglas compiten.

Primero hay que eliminar contradicciones y después, reservar el énfasis para las pocas normas cuyo incumplimiento tenga consecuencias serias de verdad.

Un ejemplo aproximado de lo que interesa tener

Con lo visto en el capítulo, un CLAUDE.md inicial podría ser algo así:

# Proyecto

Aplicación Astro con contenido MDX y estilos Tailwind.

# Comandos

- Instala dependencias con `pnpm install`.
- Ejecuta `pnpm test` para los tests.
- Ejecuta `pnpm build` antes de terminar cambios de producción.

# Convenciones

- Usa TypeScript para el código nuevo.
- Guarda los componentes compartidos en `src/components`.
- Usa exports con nombre; no utilices default exports.
- Reutiliza los componentes existentes antes de crear uno nuevo.

# Límites

- No modifiques archivos ajenos a la tarea.
- No instales dependencias sin explicar antes por qué son necesarias.
- No crees commits ni hagas push salvo que el usuario lo pida.

# Verificación

- Ejecuta los tests relacionados con los archivos modificados.
- Comprueba `pnpm build` cuando el cambio afecte a la aplicación.

Es corto pero permite saber qué proyecto tenemos delante y cómo trabajar en él, qué evitar y cómo comprobar el resultado. A partir de aquí solo añadiría una regla cuando resuelva un problema real y recurrente.

Trátalo como si fuese código crítico del proyecto

Un CLAUDE.md no se escribe una tarde y luego ya te olvidas de el, hay que mantenerlo. Las herramientas cambian, la arquitectura evoluciona y algunas reglas dejan de tener sentido. Si no se revisa, termina dando instrucciones para un proyecto que ya no existe.

Cuando Claude Code cometa un error, puede ser útil tratarlo como un bug del propio archivo.

1. Comprueba si ya había una instrucción y Claude Code no la siguió.

2. Si existía, revisa si era ambigua, estaba duplicada o contradecía otra regla.

3. Si no existía y el error puede repetirse, añade una instrucción concreta.

4. Si debe ser imposible saltársela, implementa un mecanismo que la haga cumplir.

También puedes pedirle al propio Claude Code que proponga la modificación.

Actualiza CLAUDE.md con una regla breve y verificable para que no vuelvas a crear
migraciones sin su test de reversión. Revisa antes si ya existe una instrucción
relacionada y evita duplicarla.

La última frase es importante. Pedir añade esto a CLAUDE.md después de cada corrección sin revisar nada es precisamente la receta para acabar con un CLAUDE.md inútil y lleno de mierda.

La idea con la que me quedo

Después de este capítulo, no mediría un buen CLAUDE.md por todo lo que contiene, sino por la cantidad de decisiones correctas que ayuda a tomar sin estorbar el resto del trabajo.

Las preferencias generales van en el archivo del usuario. Las normas compartidas, en el del proyecto. Mis particularidades para ese repositorio, en el archivo local. Lo que solo afecta a una parte del código se acerca a esa parte, y lo que necesita cumplirse sí o sí se automatiza o se bloquea.

Luego quedan tres reglas para redactar las reglas: ser concreto, indicar la alternativa y reservar el énfasis para lo importante de verdad.

No hay que escribirle a Claude Code una constitución de 400 artículos. Consiste en dejarle las señales necesarias para que no tengamos que recordar y repetir lo más importante en cada sesión.

EA! Nos vemos en los bares! 🍻