Admitámoslo: le coges el gusto a la terminal con esteroides, arrancas Claude Code por primera vez, la herramienta te suelta un guiño en plan «oye, dale a /init«, y tú, con toda la fe del mundo, le das enter.

(Grave error, amigo mío).

Te crea un archivo CLAUDE.md en la raíz del proyecto y, de repente, sientes una especie de revelación divina. Te crees que has descubierto el Santo Grial del desarrollo moderno. Empiezas a meterle ahí dentro las directrices de estilo, la arquitectura de carpetas, cómo configuras el Nginx, la historia de tu vida y casi hasta la receta de las albóndigas de tu abuela. «¿Para que tenga contexto, sabes?».

Spoiler: lo único que has conseguido es montar un cajón de sastre infumable que la IA se pasa por el forro.

Hoy nos vamos a tomar un café bien cargado y te voy a explicar por qué tu archivo de contexto está haciendo exactamente lo contrario de lo que pretendes, y cómo dejarlo fino filipino.

🛑 La gran mentira del /init y el síndrome de Diógenes digital

Cuando estas herramientas de terminal salieron al ruedo, meter todo el contexto posible a martillazos tenía cierto sentido. Los modelos necesitaban que les llevaras de la mano como a un niño de tres años en la feria para que no rompieran nada. Pero hoy en día, los modelos le pegan veinte vueltas a eso.

Si tu proyecto usa Laravel, Magento, Symfony, React o cualquier cosa medianamente estandarizada, Claude ya sabe cómo huele ese código nada más oler el composer.json o el package.json. No necesitas meterle 80 líneas explicándole qué es un controlador.

El comando /init te va a generar un tocho infumable lleno de obviedades. ¿Mi consejo de perro viejo? Pasa olímpicamente del /init. Hazte un touch CLAUDE.md a mano y escribe únicamente lo que de verdad aporta valor.

🧠 Entiende el bicho: Es contexto, no un archivo de configuración

Aquí es donde patina el 90% del personal.

Un archivo CLAUDE.md no es un fichero de configuración. No es un .eslintrc, ni un phpcs.xml, ni una directiva de Nginx que el sistema va a obligar a cumplir bajo pena de pantallazo rojo.

Lo que hace la herramienta por debajo es coger ese Markdown y metérselo a Claude como un mensaje más al principio de la conversación. Punto. Se lo lee exactamente igual que cuando tú le pegas una bronca por chat diciéndole que no toque esa tabla de la base de datos.

Y de aquí sale la regla de oro más contraintuitiva del desarrollo asistido por IA:

A más líneas le metas al archivo, con menos fiabilidad te va a hacer caso.

Una regla crítica metida entre un muro de texto de 400 líneas compite en atención con todo lo demás. ¿El resultado? La regla se pierde como una lágrima en la lluvia. Si necesitas que algo ocurra sí o sí en el 100% de los casos (como pasar el linter o los tests antes de comitear), eso no va en el markdown: eso va en un Git Hook o en la CI/CD. No le pidas a la IA que haga de policía jurado cuando tienes herramientas nativas para eso.

🛠️ Las reglas del juego para no volverte loco

Si quieres que este invento sume en lugar de meter ruido, aplícate estas directrices de guerrilla:

1. Por debajo de las 250 líneas (y si son 60, mejor)

Trátalo como si cada línea que escribes te costase un cubata. Poner reglas a lo loco da una falsa sensación de control, pero cada párrafo extra diluye la atención del modelo.

2. Sé quirúrgico, no un manual de autoayuda

• Mal: «Escribe código limpio y formatea bien.» (Claude: «Gracias, bro, ahora mismo me invento lo que para mí significa limpio»).
• Bien: «Usa indentación de 4 espacios. Prohibido usar tabs.»
• Mal: «Prueba los cambios antes de decir que has terminado.»
• Bien: «Ejecuta vendor/bin/pest antes de dar por cerrada la tarea.»

Instrucciones verificables. Si la IA no puede evaluar un booleano (se cumple o no se cumple), la instrucción sobra.

3. Estructura con Markdown limpio

Usa encabezados (##), listas claras y pon en MAYÚSCULAS Y NEGRITA lo que sea innegociable. Claude responde sorprendentemente bien al énfasis visual cuando está bien dosificado.

## Estilo y Convenciones
- **PROHIBIDO** commitear llamadas a `dump()`, `dd()` o `console.log`.
- Los endpoints de la API deben responder siempre en camelCase.

## Comandos Habituales
- Tests: `npm test`
- Limpieza de caché: `bin/magento cache:flush`

4. Poda las ramas secas periódicamente

Heredar un CLAUDE.md viejo es peor que abrir una caja de cables por detrás de la tele. Te encuentras reglas de paquetes que se desinstalaron hace seis meses o directrices contradictorias. Si dos reglas se pegan entre sí, el modelo va a tirar una moneda al aire y hará lo que le dé la gana. Pasa la tijera sin piedad.

Borrar cosas de este fichero suele mejorar el rendimiento del asistente el doble que añadir cosas nuevas.

Al final, esto del código asistido por agentes sigue siendo un poco el Salvaje Oeste, y cada maestrillo tiene su librillo. Pero quédate con la copla: el CLAUDE.md son cuatro instrucciones para no perderse en tu proyecto, no la enciclopedia Espasa.

Haz la prueba hoy mismo: abre tu archivo, bórrate la mitad de la paja que le metiste el primer día y mira cómo empieza a hacerte caso de verdad.

¡Suerte revisando código! 🤘🔥