Los asistentes de programación con inteligencia artificial han pasado de completar líneas sueltas a tocar repositorios completos, ejecutar comandos, escribir pruebas, refactorizar código y actuar durante varios pasos. Ese salto ha hecho que una idea aparentemente simple gane protagonismo entre desarrolladores: si un agente va a modificar software, necesita reglas persistentes, no instrucciones improvisadas en cada conversación.
En el caso de Claude Code, esa capa de reglas suele vivir en un archivo llamado CLAUDE.md. La propia documentación de Anthropic lo define como un mecanismo para dar a Claude instrucciones persistentes sobre un proyecto, el flujo de trabajo del usuario o incluso una organización completa. Claude Code lee esos archivos al inicio de cada sesión y los trata como contexto, no como una configuración rígida. Por eso Anthropic recomienda que las instrucciones sean concretas, concisas y bien estructuradas.
El debate se ha reactivado por una publicación en Reddit que recopila una plantilla de 12 reglas inspirada en las llamadas “reglas de Karpathy” para reducir errores de Claude en tareas de código. El texto asegura que, en una prueba no verificada con 30 bases de código durante seis semanas, una primera versión de cuatro reglas habría bajado la tasa de error del 41 % al 11 %, y que una ampliación a 12 reglas la habría reducido hasta el 3 %. Son cifras llamativas, pero conviene tratarlas como una experiencia comunitaria, no como un benchmark auditado.
Qué es un CLAUDE.md y por qué importa
Un CLAUDE.md funciona como una especie de manual operativo para el agente. No contiene el código del proyecto, sino las normas que el modelo debe recordar: cómo se ejecutan los tests, qué estilo sigue el equipo, qué patrones no debe romper, qué comandos se usan, qué decisiones arquitectónicas son importantes o qué tipo de cambios deben evitarse.
Anthropic recomienda añadir información a CLAUDE.md cuando Claude repite un error, cuando una revisión de código detecta algo que el agente debería haber sabido, cuando se repite una aclaración entre sesiones o cuando un nuevo miembro del equipo necesitaría el mismo contexto para ser productivo. También aconseja mantener estos archivos por debajo de unas 200 líneas, porque se cargan en la ventana de contexto y consumen tokens junto al resto de la conversación.
Esto cambia la forma de trabajar con agentes de código. El prompt puntual sigue siendo útil, pero no basta. Si cada tarea empieza explicando de nuevo las convenciones del repositorio, el modelo tiene más posibilidades de olvidar detalles, mezclar patrones o tomar decisiones demasiado creativas. Un archivo persistente reduce ese ruido.
| Elemento | Prompt puntual | CLAUDE.md |
|---|---|---|
| Duración | Solo para una tarea o conversación | Persistente entre sesiones |
| Contenido | Petición concreta del momento | Reglas, convenciones y flujo del proyecto |
| Riesgo | Se olvida o se formula de forma distinta cada vez | Puede crecer demasiado si no se mantiene |
| Uso ideal | “Cambia esta función” | “Así se trabaja en este repositorio” |
| Valor para equipos | Bajo si no se repite | Alto si está versionado y compartido |
De cuatro reglas básicas a doce reglas operativas
La plantilla publicada parte de cuatro principios sencillos: pensar antes de programar, preferir la solución simple, hacer cambios quirúrgicos y trabajar con criterios de éxito verificables. Son normas que cualquier desarrollador senior reconocería. El valor está en explicitarlas para un agente que, si no recibe límites, puede sobreactuar: refactorizar de más, tocar archivos vecinos, inventar abstracciones o asumir requisitos no confirmados.
La ampliación a 12 reglas intenta cubrir problemas más propios de agentes que trabajan durante ciclos largos. Ahí aparecen límites de tokens, checkpoints, lectura previa del código existente, respeto a convenciones, pruebas que verifiquen intención y errores que fallen de forma visible en vez de quedar ocultos.
| Regla | Qué intenta evitar |
|---|---|
| Pensar antes de programar | Suposiciones silenciosas y soluciones precipitadas |
| Primero lo simple | Abstracciones innecesarias y código sobrediseñado |
| Cambios quirúrgicos | Refactors no pedidos y modificaciones colaterales |
| Ejecución guiada por objetivo | Tareas “terminadas” sin verificación clara |
| Usar el modelo solo para criterio | Delegar en la IA decisiones deterministas como reintentos o códigos HTTP |
| Controlar tokens | Sesiones largas donde el modelo pierde contexto y repite errores |
| Señalar conflictos | Mezclar patrones incompatibles de la base de código |
| Leer antes de escribir | Duplicar funciones o ignorar utilidades existentes |
| Probar intención | Tests que pasan sin validar la lógica de negocio real |
| Hacer checkpoints | Seguir construyendo sobre un estado roto |
| Respetar convenciones | Introducir patrones ajenos al proyecto porque “parecen mejores” |
| Fallar fuerte | Ocultar incertidumbres, registros saltados o errores parciales |
La regla 5 es especialmente importante para productos reales: no usar el modelo para decisiones que el código puede resolver de forma determinista. Un LLM puede clasificar, resumir, redactar o extraer información. Pero decidir si se reintenta una petición HTTP tras un 503, transformar datos con una regla cerrada o enrutar errores según códigos de estado no debería depender de una respuesta probabilística. Si una condición puede expresarse con código, conviene expresarla con código.
La regla 9 también apunta a un problema común en el vibe coding: pruebas que solo comprueban que algo devuelve “algún valor”. Ese tipo de test da una falsa sensación de seguridad. Una prueba útil debe fallar cuando se rompe la intención de negocio, no solo cuando cambia una forma superficial de la respuesta.
El riesgo de convertir el CLAUDE.md en otro cajón desastre
El entusiasmo por estas plantillas tiene un peligro: llenar CLAUDE.md con demasiadas normas, deseos y recordatorios. Si el archivo crece sin control, consume contexto, crea conflictos internos y reduce la probabilidad de que el agente obedezca lo importante. Anthropic insiste en que Claude trata estas instrucciones como contexto, no como reglas infalibles. Cuanto más específicas y compactas sean, mejor.
Eso obliga a mantener el archivo como se mantiene el propio código. Si una regla ya no aplica, debe retirarse. Si dos instrucciones se contradicen, hay que resolver el conflicto. Si un patrón solo afecta a una carpeta, quizá convenga moverlo a reglas con alcance por ruta en vez de cargarlo siempre. La memoria del agente no debe convertirse en una lista infinita de frustraciones acumuladas.
En equipos profesionales, el archivo puede formar parte del repositorio y revisarse como cualquier otro cambio. Una modificación de CLAUDE.md puede tener tanto impacto como cambiar una guía de estilo o un script de despliegue, porque altera cómo trabajará el agente sobre el código.
Lo que revela esta tendencia sobre el desarrollo con IA
La popularidad de estas reglas dice algo más amplio sobre el estado del desarrollo con agentes. Al principio, muchos equipos usaron herramientas como Claude Code, Cursor, Codex o Copilot Agent como aceleradores individuales. El siguiente paso es convertirlos en participantes controlados del proceso de ingeniería.
Eso exige más disciplina, no menos. Los agentes pueden escribir mucho código, pero necesitan límites: alcance, criterios de éxito, pruebas, lectura previa, checkpoints, convenciones y visibilidad de incertidumbre. La productividad no viene de dejar que el modelo haga más cosas, sino de conseguir que haga las cosas correctas sin romper el contexto del proyecto.
También deja una lección para responsables técnicos. La calidad del resultado no depende solo del modelo. Depende del entorno que se le da: repositorios legibles, tests útiles, comandos claros, documentación actualizada, reglas de contribución y decisiones arquitectónicas visibles. Un agente mal guiado amplifica el desorden. Un agente bien encuadrado puede reducir trabajo repetitivo y acelerar tareas controladas.
El CLAUDE.md no es magia. No garantiza que Claude no se equivoque ni convierte un agente en un ingeniero senior. Pero sí puede funcionar como una barandilla. Le dice al modelo dónde están los límites, qué debe leer antes de tocar código, cuándo debe parar y cómo debe demostrar que algo funciona.
En la práctica, esa puede ser la diferencia entre usar IA para generar más código y usar IA para mantener mejor software. La primera opción parece rápida. La segunda es la que probablemente sobreviva en equipos reales.
Preguntas frecuentes
¿Qué es un archivo CLAUDE.md?
Es un archivo Markdown con instrucciones persistentes para Claude Code. Sirve para definir estándares, comandos, convenciones, arquitectura y reglas de trabajo de un proyecto.
¿Las reglas atribuidas a Karpathy están verificadas oficialmente?
La plantilla circula en la comunidad y se inspira en principios asociados a buenas prácticas de programación con IA. Las cifras de reducción de errores publicadas en Reddit deben leerse como experiencia no auditada.
¿Conviene copiar una plantilla de 12 reglas tal cual?
Puede servir como punto de partida, pero lo recomendable es adaptarla al repositorio, eliminar lo que no aplique y añadir reglas específicas del proyecto sin superar un tamaño razonable.
¿Un CLAUDE.md sustituye a los tests?
No. Ayuda a orientar al agente, pero los tests, revisiones de código, CI y criterios de aceptación siguen siendo necesarios para verificar cambios reales.
