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. Define 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 y nadie se atreve a borrar una regla porque nadie recuerda por qué está.

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

La regla 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. Si la señal es «que la suite pase en verde», 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 y el diff se ve pequeño.

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

La que evita que una corrección vuelva como refactor

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: de paso renombró variables, extrajo un helper y actualizó un import en otro archivo.

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í.

Un agente no distingue entre «esto está mal» y «esto es asunto mío ahora». Tú sí. Esa distinción va escrita.

La que impide que invente comandos

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

Sin esta lista, el agente propone comandos plausibles: npm test en un proyecto que usa pnpm, pytest donde usas tox.

La regla real no es escribir la lista. Es escribir solo comandos que hayas ejecutado y visto funcionar. Un comando inventado aquí contamina todo lo que venga después, porque el agente lo trata como un hecho verificado.

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 en un archivo generado.

Un secreto expuesto no se «desexpone». Se rota. Y rotar credenciales en producción nunca ocurre en un buen momento.

Complemento necesario: mantén el .gitignore estricto. Una instrucción es una barrera blanda; un archivo que el agente no puede leer es una barrera dura.

Los tres errores que me costaron rehacer trabajo

Escribí reglas sin motivo. La primera versión era una lista de órdenes. A los dos meses no recordaba por qué estaba la mitad, no me atrevía a borrarlas, 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. El agente los usó como hechos. Perdí una tarde persiguiendo fallos de un pipeline inexistente.

Puse todo en un archivo enorme. Trescientas líneas mezclando arquitectura, estilo, despliegue y preferencias. El contexto es un presupuesto: 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, 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: no lo pegues entero. Léelo y borra toda regla cuyo motivo no te haga sentido en tu proyecto. Un CLAUDE.md heredado sin entender es peor que no tener ninguno, porque el agente obedece reglas que tú no puedes defender.