Qué hay realmente dentro de mi CLAUDE.md

Un CLAUDE.md es el archivo que un agente de código lee antes de tocar tu proyecto, y ahí le dices qué es el repositorio, cómo se trabaja en él y dónde están los límites.

Casi todos los que circulan son listas de órdenes sin motivo. Se copian, se heredan, se van pasando de proyecto en proyecto, y llega un punto en que nadie se atreve a borrar una regla porque ya nadie recuerda por qué estaba ahí.

Este es el mío, o al menos la parte que importa, con el fallo concreto que previene cada regla.

La que más trabajo me ha ahorrado

Nunca modifiques un test para que pase. Si un test falla, el sospechoso
es el código.

Parece obvia hasta que la necesitas.

Un agente optimiza por la señal que le diste, y si la señal es que la suite quede en verde, entonces debilitar una aserción es una solución perfectamente válida desde su punto de vista: cambiar assertEquals(42, x) por assertNotNull(x) pone todo en verde, el diff se ve chico y nadie levanta la mano.

Es el fallo más difícil de pillar en una revisión, porque todo parece estar bien. El test existe, corre y pasa. Solo que ya no verifica nada.

”Aproveché y arreglé un par de cosas más”

Haz exactamente lo pedido. No amplíes el alcance sin una razón declarada.
Implementa el cambio correcto más pequeño. Los problemas adyacentes se
reportan, no se arreglan de paso.

Sin esto pides arreglar tres líneas y vuelve un diff de doscientas, porque de paso renombró variables, extrajo un helper, actualizó un import en otro archivo, y ya que estaba ordenó los imports del módulo completo y le puso tipos a una función que llevaba dos años sin tenerlos.

Nada de eso está mal en abstracto. El problema es que tu revisión pasó de dos minutos a media hora, y ahora tienes que decidir sobre cinco cambios que no pediste mientras buscas el que sí pediste.

Un agente no distingue entre “esto está mal” y “esto es asunto mío ahora”. Tú sí, y esa distinción va escrita.

”Seguro los comandos los deduce del repositorio”

Comandos:
Instalar:   <comando real>
Tests:      <comando real>
Build:      <comando real>

No los deduce, los inventa plausibles: te propone npm test en un proyecto que usa pnpm, o pytest donde usas tox.

Y acá la regla real no es escribir la lista, es escribir solo comandos que hayas ejecutado y visto funcionar con tus propios ojos. Un comando inventado en este archivo contamina todo lo que venga después, porque el agente lo trata como hecho verificado y construye encima.

La que protege lo que no debe salir

Nunca leas archivos .env, credenciales, tokens ni dumps de producción.
Si encuentras un secreto, indica dónde está y detente.

Lo que entra al contexto sale de tu entorno: viaja a un proveedor, puede quedar en registros y puede terminar reproducido dentro de un archivo generado.

Un secreto expuesto no se desexpone, se rota, y rotar credenciales en producción nunca ocurre en un buen momento. Siempre es un viernes.

Complemento necesario, y esto es más importante que la regla: mantén el .gitignore estricto. Una instrucción es una barrera blanda y un archivo que el agente no puede leer es una barrera dura.

Tres errores míos que costaron rehacer trabajo

Escribí reglas sin motivo. La primera versión era una lista de órdenes secas, y a los dos meses no recordaba por qué estaba la mitad, no me atrevía a borrar ninguna por si acaso servía para algo, iba agregando cada vez que algo salía mal, y el archivo creció hasta que el agente empezó a ignorar el final.

Documenté el proyecto que quería, no el que tenía. Puse los comandos que deberían funcionar y las convenciones que pensaba adoptar en algún momento, el agente los tomó como hechos, y perdí una tarde entera persiguiendo fallos de un pipeline que no existía.

Puse todo en un archivo enorme. Trescientas líneas mezclando arquitectura, estilo, despliegue y preferencias personales. El contexto es un presupuesto, así que cada línea que agregas le quita peso a las demás. Recorté y las respuestas mejoraron de inmediato.

Si tu CLAUDE.md no cabe en una pantalla y media, sobra algo.

El archivo completo

Estas son cuatro reglas de nueve. El resto, convenciones, verificación, subagentes y comunicación, está en el archivo, cada una con su bloque de por qué.

Te lo dejo gratis: el CLAUDE.md base comentado.

Un consejo antes de copiarlo, y va en serio: no lo pegues entero. Léelo y borra toda regla cuyo motivo no te haga sentido en tu proyecto, porque un CLAUDE.md heredado sin entender es peor que no tener ninguno: el agente va a obedecer reglas que tú no puedes defender.