Cómo escribir un buen CLAUDE.md para un proyecto Laravel

Hola, bienvenido. En la lección anterior generamos el primer CLAUDE.md de claude-tasks con /init y lo guardamos en un commit tal y como salió, y en esta lección vamos a convertirlo en el CLAUDE.md definitivo del proyecto. Veremos qué merece estar en él y qué no, cómo usar /doctor para recortar lo que Claude puede deducir del código, qué información de un proyecto Laravel con Sail no va a descubrir nunca por su cuenta y cómo comprobar que la sigue. Al terminar tendremos un archivo corto y factual, versionado en el repositorio, que Claude va a leer al empezar cada sesión.

¿Por qué no dejar el que generó /init? Porque ese archivo se escribe a partir de lo que Claude encuentra en el código, y un buen CLAUDE.md sirve sobre todo para contar lo que no está en el código. Y hay un segundo motivo que tiene que ver con el coste: como vimos en la lección de ventana de contexto, CLAUDE.md se carga entero al principio de cada sesión y viaja en cada petición, así que cada línea que sobra la pagas en todas las conversaciones. La documentación añade otro efecto: los archivos largos reducen lo bien que Claude sigue las instrucciones. Si Claude sigue haciendo algo que tu CLAUDE.md le pide que no haga, lo más probable, según la propia documentación, es que el archivo sea demasiado largo y la instrucción se esté perdiendo.

La recomendación oficial es quedarse por debajo de 200 líneas por archivo, y la pregunta que propone para decidir cada línea es muy buena: si la quitas, ¿Claude cometería errores? Si la respuesta es que no, esa línea sobra.

La documentación da una tabla con lo que conviene incluir y lo que conviene dejar fuera. Esta es, con ejemplos de un proyecto Laravel como el nuestro:

Además, cada instrucción tiene que ser lo bastante concreta como para poder comprobarla. La documentación lo ilustra con ejemplos como «ejecuta npm test antes de hacer el commit» en lugar de «prueba tus cambios». Y da una pista para saber cuándo añadir algo: cuando Claude comete el mismo error por segunda vez, cuando una revisión de código detecta algo que Claude debería haber sabido, cuando escribes en el chat la misma corrección que escribiste en la sesión anterior o cuando un compañero nuevo necesitaría ese contexto para ser productivo.

Hay 2 detalles de forma que también ayudan. Los títulos y las listas de markdown funcionan mejor que los párrafos densos, porque Claude recorre la estructura igual que lo haría una persona. Y si hay una instrucción que Claude se salta una y otra vez, puedes marcarla con algo como IMPORTANT delante, pero solo esa: si enfatizas muchas líneas, ninguna destaca.