Empecemos por lo que sí es esa cifra, porque el título la trae y no quiero que la uses mal. El salto de 65% a 94% viene de una anécdota que circuló en redes: alguien midió sus propias corridas antes y después de poner un archivo de reglas. No es un estudio, no es una medición de Anthropic, y no hay forma de que reproduzcas esos porcentajes en tu repositorio. Trátalo como lo que es: la señal de que alguien encontró una mejora grande, no un número que puedas prometerle a nadie.
Lo que sí se puede copiar tal cual es el archivo. Y ese es el punto de esta guía.
El origen es Andrej Karpathy quejándose en público de lo que hacen mal los agentes que escriben código. Sus quejas se resumen en tres, y alguien tuvo la buena idea de convertirlas en instrucciones permanentes en vez de repetirlas en cada chat.
Las tres quejas
- Código defensivo de más. El agente envuelve todo en manejo de errores, valida cosas que no pueden fallar y agrega respaldos silenciosos. El resultado se ve robusto y es lo contrario: cuando algo truena, el error queda enterrado y tú te enteras tres días después.
- Ignora lo que ya existe en tu proyecto. Escribe su propia función para algo que ya tenías resuelto, agrega una dependencia nueva teniendo una equivalente instalada, y usa un estilo distinto al del resto del repositorio.
- Sobreingeniería. Pides un script de treinta líneas y recibes tres clases, una interfaz y una capa de configuración. Más código del que pediste, con la excusa de que "así queda listo para producción".
Las tres tienen la misma raíz: el modelo optimiza para que su respuesta se vea completa e impresione. Y las tres se corrigen con instrucciones, no con mejores prompts.
El archivo
Va en la raíz del proyecto, se llama CLAUDE.md, y Claude Code lo lee solo al abrir la sesión. No hay que invocarlo ni recordárselo.
# Reglas del proyecto
## Principio general
Escribe el código mínimo que resuelve lo que se pidió. Nada más.
Si crees que hace falta algo adicional, dilo en texto y espera; no
lo escribas por tu cuenta.
## Manejo de errores
- No agregues try/except a menos que yo lo pida o que el error sea
esperable y recuperable.
- Prohibido capturar una excepción para registrarla y seguir como
si nada. Si algo falla, que falle fuerte y de inmediato.
- Prohibidos los valores de respaldo silenciosos. Un dato que no
llegó es un error, no un cero.
- No valides argumentos que solo puede pasar el propio código.
## Antes de escribir código nuevo
- Busca primero en el repositorio si ya existe algo que haga eso.
Si existe, úsalo. Si está mal, dímelo antes de reemplazarlo.
- No agregues dependencias nuevas. Si de verdad hace falta una,
para y pregunta, con el motivo y la alternativa que descartaste.
- Copia el estilo del código que ya está: nombres, estructura de
carpetas, formato. Aunque tú lo harías distinto.
## Alcance
- No refactorices código que no te pedí tocar.
- No renombres variables, archivos ni funciones fuera del alcance.
- No agregues compatibilidad hacia atrás si no te la pedí.
- No agregues opciones de configuración "por si acaso".
- No crees abstracciones para un solo caso de uso. Tres usos reales
antes de abstraer.
## Comentarios y documentación
- Comenta solo lo que no es obvio: por qué, nunca qué.
- Prohibidos los comentarios que repiten el nombre de la función.
- No generes archivos README, resúmenes ni documentación salvo que
se pidan.
## Cambios
- Un cambio a la vez. No mezcles el arreglo con la limpieza.
- No borres código que no entiendas. Pregunta.
- Si tu cambio rompe algo existente, dilo antes de aplicarlo.
## Cómo me reportas
- Empieza por lo que hiciste, en dos líneas. Sin preámbulo.
- Después, qué NO hiciste y por qué.
- Marca explícitamente lo que no probaste.
- Si asumiste algo, ponlo en una lista de supuestos al final.
- Prohibido afirmar que algo funciona si no lo corriste.
## Prohibido
- Emojis en el código, en los commits y en la salida.
- Reescribir archivos completos cuando basta con editar unas líneas.
- Cambiar el formato de un archivo entero por un cambio de dos
líneas.Cómo se pone
- Crea el archivo
CLAUDE.mden la carpeta raíz del proyecto y pega el contenido. - Ajusta lo que no aplique a tu lenguaje o a tu equipo. Es una plantilla, no un dogma.
- Si quieres las mismas reglas en todos tus proyectos, la misma instrucción vive en el archivo global de tu usuario. Lo específico de cada proyecto se queda en el archivo del proyecto.
- Súbelo al control de versiones. Si el resto del equipo usa Claude Code, todos trabajan con las mismas reglas y las mejoras se comparten.
El paso que todo mundo se salta: mantenerlo vivo. La primera versión es la que copias; la que sirve es la de dentro de un mes. Cada vez que el agente haga algo que te moleste, no lo corrijas nada más en el chat: agrega la regla que lo evita para siempre. Un archivo de reglas que no ha cambiado en tres meses es un archivo que ya nadie está leyendo, empezando por ti.
Por qué esto funciona más que un buen prompt
Un prompt aplica a un mensaje. Un archivo de reglas aplica a todas las sesiones, para todos los que trabajan en el proyecto, sin que nadie se acuerde de nada. La diferencia no es de calidad, es de consistencia.
Y hay un efecto secundario que vale más que el ahorro de tiempo: las revisiones de código se vuelven cortas. Cuando el agente entrega el cambio mínimo y te dice qué no probó y qué supuso, revisar toma minutos. Cuando entrega cuatrocientas líneas con refactor incluido, nadie lo revisa de verdad y todos lo aprueban.
Lo que el archivo no arregla
No te va a salvar de pedir mal las cosas. Si tu instrucción es ambigua, el agente va a elegir por ti, y ninguna regla del mundo adivina qué querías.
Tampoco sustituye las pruebas. Que el modelo tenga prohibido decir que algo funciona sin correrlo es una regla que él mismo tiene que respetar, y a veces no lo hace. Verifica igual.
Si quieres ir más a fondo en cómo estructurar este archivo por proyecto y por equipo, el archivo más importante de Claude Code tiene la versión larga, y la plantilla que se mejora sola es lo que uso para que las reglas nuevas se agreguen sin que yo abra el editor.