karpathy se quejó de claude en x. forrest chang convirtió la queja en cuatro reglas y un repositorio de github. el repo alcanzó 120,000 estrellas en semanas. la mayoría de los desarrolladores que leen esto todavía usan solo esas cuatro reglas. el problema es que fueron escritas en enero. ahora es mediados de 2026 y el ecosistema de claude code ha cambiado.
este artículo te da la CLAUDE.md completa de 12 reglas, por qué existe cada regla, qué fallo resuelve, y qué es lo que la plantilla original se equivoca en silencio. pégala al final.
¿Qué es CLAUDE.md y por qué la mayoría la tiene mal?
CLAUDE.md es un archivo que colocas en la raíz de tu repositorio. claude code lo lee antes de cada sesión. no es un prompt. no es una lista de preferencias. es un sistema operativo para cómo se comporta claude en tu código base.
la mayoría de los desarrolladores hacen una de tres cosas incorrectas. meten cada preferencia que han tenido en el archivo hasta que se infla más de 4,000 tokens, momento en el que el cumplimiento cae al 30% porque las reglas importantes quedan enterradas. lo omiten por completo y vuelven a hacer prompt en cada sesión, lo que desperdicia cinco veces los tokens y produce cero consistencia. pegan una plantilla una vez, la olvidan, y la ven romperse en silencio a lo largo de semanas a medida que su código base cambia.
la documentación oficial de anthropic es explícita: CLAUDE.md es consultivo. claude lo sigue aproximadamente el 80% del tiempo cuando tiene menos de 200 líneas. pasadas las 200 líneas, el cumplimiento cae drásticamente. el techo para archivos CLAUDE.md útiles es corto, preciso y reforzado mediante reglas directas, no sugerencias.
Las 4 reglas originales: empieza aquí si no tienes nada
andrej karpathy, ex director de IA en tesla y cofundador de openai, publicó un hilo en enero de 2026 después de semanas de trabajo intensivo con claude code. no un marco de trabajo. una queja. tres modos de fallo que seguía encontrando: claude asume en silencio en lugar de preguntar, claude sobreconstruye en lugar de resolver el mínimo, y claude toca código que nunca se le pidió tocar.
forrest chang leyó el hilo y lo escribió como reglas. un archivo, 65 líneas, en github al día siguiente. aquí están las cuatro:
Regla 1 – Piensa antes de codificar
expón tus suposiciones antes de escribir código. saca a la superficie las compensaciones. pregunta antes de adivinar. rechaza cuando exista un enfoque más simple. nunca construyas sobre una suposición no verificada.
Regla 2 – Simplicidad primero
escribe el código mínimo que resuelve el problema. sin funciones especulativas. sin abstracciones para código usado una sola vez. si un ingeniero senior lo llamaría demasiado complicado, simplifícalo.
Regla 3 – Cambios quirúrgicos
toca solo lo que requiere la tarea. no mejores código adyacente, comentarios o formato. no refactorices lo que no está roto. adáptate exactamente al estilo existente.
Regla 4 – Ejecución orientada a objetivos
define cómo se ve el éxito antes de empezar. itera hasta que el éxito se verifique. no enumeres pasos para que claude los siga. dile a claude cómo se ve «terminado» y deja que encuentre el camino.
estas cuatro reglas resuelven aproximadamente el 40% de los modos de fallo en sesiones no supervisadas de claude code. el 60% restante vive en huecos que la plantilla original no aborda, porque esos problemas no existían completamente cuando karpathy publicó su hilo.
Por qué la plantilla original necesita ampliarse
Las cuatro reglas de karpathy se hicieron para arreglar una sesión de escritura de código con un solo agente. El ecosistema de claude code en 2026 ejecuta configuraciones multiagente, hooks, librerías de habilidades y flujos de trabajo de varios pasos que abarcan sesiones. La plantilla original no tiene nada que decir sobre nada de eso.
Aparecen cuatro vacíos específicos en las reglas originales. Primero, peleas entre agentes: dos agentes editando los mismos archivos sin reglas de propiedad, pisándose sus cambios en silencio. Segundo, cascadas de hooks: hooks que se disparan en cada llamada de herramienta, convirtiendo una solicitud de 200 tokens en 8,000 tokens sin presupuesto para detenerlo. Tercero, conflictos de carga de habilidades: múltiples habilidades con descripciones similares confunden al despachador y cargan la incorrecta. Cuarto, roturas de sesión en varios pasos: una refactorización de 6 pasos falla en el paso 4, pero los pasos 5 y 6 se ejecutan de todos modos y se basan en un estado roto.
Las cuatro reglas originales no están mal. Están incompletas. Las 8 reglas adicionales a continuación cierran estos vacíos específicos.
Las 8 nuevas reglas: qué cierra cada una
Regla 5 – No uses el modelo para trabajo no lingüístico
Las decisiones deterministas pertenecen al código determinista. Lógica de reintento, umbrales de enrutamiento, reglas de escalado, ramificación basada en estado: nada de esto debería ser llamadas LLM. El modelo decide diferente cada semana según lo que haya en la ventana de contexto. Lo que parece un comportamiento consistente es en realidad varianza que aún no ha salido a la superficie.
El incidente específico: una llamada LLM de «decidir si reintentar en un 503» funcionó durante dos semanas, luego comenzó a producir comportamiento aleatorio porque el modelo empezó a leer el cuerpo de la solicitud como contexto para la decisión de reintento. La política se volvió aleatoria porque la entrada efectiva era aleatoria.
Agrega esto a tu CLAUDE.md:
Las decisiones de enrutamiento, lógica de reintento, ramificación basada en estado y umbrales pertenecen al código, no a llamadas al modelo. Si el resultado de una decisión es binario o sigue una regla fija, escribe la regla en código.
Regla 6 – Presupuestos de tokens duros, sin excepciones
Cada bucle de agente tiene la posibilidad de descontrolarse. Claude no detendrá por sí solo una sesión de depuración de 90 minutos. Seguirá iterando porque se le ha dicho que itere. Los presupuestos de tokens son el único mecanismo que impone una parada forzosa.
El incidente específico: una sesión de depuración dando vueltas sobre el mismo mensaje de error de 8KB durante 90 minutos. Al final, claude sugería correcciones que ya había intentado y abandonado dos horas antes. El contexto estaba tan lleno que había perdido el hilo de su propio razonamiento.
Agrega esto:
Cada sesión de agente tiene un presupuesto de tokens duro. Si se alcanza el presupuesto sin una solución verificada, detente, resume los hallazgos en un archivo y sal. No continúes más allá del presupuesto.
Regla 7 – Un agente, un directorio
Cuando dos agentes tocan el mismo directorio simultáneamente, obtienes corrupción de estado silenciosa. Un agente escribe un archivo mientras otro lo está leyendo. El resultado son datos que ninguno de los agentes espera y que ninguno nota.
Usa git worktrees. Ejecuta git worktree add ../agent-2-branch feature-branch antes de lanzar un segundo agente. Cada agente obtiene su propio directorio de trabajo aislado apuntando a su propia rama. Los agentes nunca comparten un sistema de archivos.
Agrega esto:
Los agentes que se ejecutan en paralelo trabajan en worktrees de git separados. Ningún dos agentes tocan el mismo directorio al mismo tiempo. Cada agente es dueño de su rama.
Regla 8 – Escribe archivos de punto de control en trabajos de varios pasos
Cualquier tarea de más de tres pasos necesita un archivo de punto de control. Claude escribe el archivo después de cada paso con lo que se completó, lo que se encontró y lo que viene después. Si la sesión muere o se rompe en el paso 4, la siguiente sesión lee el punto de control y continúa desde el paso 4. Sin el punto de control, cada reinicio vuelve al paso 1.
Crea un archivo llamado PROGRESS.md en tu directorio de trabajo antes de comenzar cualquier tarea de varios pasos. Dile a claude en tu CLAUDE.md:
Para tareas con más de tres pasos, escribe un archivo PROGRESS.md después de cada paso. Incluye: qué se hizo, qué se encontró, qué viene después y qué está bloqueado. Si una sesión termina antes de completarse, la siguiente sesión lee PROGRESS.md primero y continúa desde donde se detuvo.
Regla 9 – Falla fuerte o no falles en absoluto
Claude tiene un fuerte sesgo a parecer exitoso. Pasará una prueba que en realidad no prueba lo que te interesaba. Completará una migración mientras salta silenciosamente archivos que dieron error. Reportará «hecho» en una tarea que está al 80%.
La regla: si los criterios de éxito no se pueden verificar, la tarea no está hecha. Si un paso falla, detente e informa el fallo con detalles antes de continuar. No encubras errores.
Agrega esto:
Nunca continúes más allá de un paso que falló. Si una prueba pasa pero no cubre el comportamiento real, dilo. Si una migración salta archivos, lista los archivos saltados y detente. Éxito significa verificable, no reportado.
Regla 10 – Las descripciones de habilidades deben ser únicas
Las habilidades se cargan por coincidencia de descripción. Si dos habilidades tienen descripciones superpuestas, el despachador elige una arbitrariamente. Se carga la habilidad incorrecta, la tarea se ejecuta con malas instrucciones y nunca ves un error porque no se lanza ningún error.
Nombra el trabajo de cada habilidad con un lenguaje que no pueda coincidir con ninguna otra habilidad. «ayudante de consulta de base de datos» y «ayudante de migración de base de datos» entrarán en conflicto. «ejecutar consultas SQL de solo lectura contra la base de datos de producción» y «ejecutar y verificar scripts de migración de esquema con rollback» no lo harán.
Agrega esto:
Cada descripción de habilidad debe identificar de manera única su trabajo. No dos habilidades deben tener descripciones que puedan aplicarse a la misma tarea. Si dos habilidades suenan similares, una de ellas necesita renombrarse antes de ser desplegada.
Regla 11 – Separa al investigador del escritor
La contaminación del contexto es real. Cuando claude hace investigación y escritura en la misma sesión, el ruido de la investigación degrada la escritura. Incorpora tangentes, matiza conclusiones que no necesita matizar y pierde la línea de argumentación limpia que habría tenido si empezara de nuevo.
Lanza un subagente de investigación para cualquier tarea que requiera leer más de cinco archivos o consultar más de dos fuentes. Obtén un informe estructurado. Inicia una sesión limpia para la escritura o implementación con solo el informe en el contexto.
Agrega esto:
Investigación e implementación son sesiones separadas. Un subagente investigador lee archivos, ejecuta consultas y devuelve un resumen estructurado. La sesión de implementación comienza de nuevo con ese resumen como su única entrada. Nunca mezcles investigación y escritura en una sola sesión.
Regla 12 – Los hooks también necesitan presupuesto
Los hooks se disparan en cada llamada de herramienta. Un hook que ejecuta un linter, un formateador, un escritor de registros y un escaneo de seguridad en cada escritura de archivo está ejecutando cuatro procesos por llamada de herramienta. En una sesión con 200 llamadas de herramienta, eso son 800 procesos ejecutándose en segundo plano, la mayoría redundantes, todos consumiendo tokens.
Cada hook que agregues necesita una condición de alcance: ejecutarse solo en escrituras de archivos en directorios específicos, solo cuando se toque una extensión de archivo específica, solo después del final de la sesión en lugar de después de cada llamada de herramienta. Los hooks sin condiciones de alcance degradarán el rendimiento de la sesión de manera invisible.
Agrega esto:
Cada hook tiene una condición de alcance explícita. Ningún hook se ejecuta incondicionalmente en cada llamada de herramienta. Agrupa el registro al final de la sesión. Ejecuta linters solo en archivos modificados. Ejecuta comprobaciones de seguridad solo en archivos fuera del directorio de pruebas.
La CLAUDE.md completa de 12 reglas – Pega esto
Copia este archivo en la raíz de tu repositorio. Rellena las secciones marcadas con corchetes. Todo el archivo se mantiene por debajo de 100 líneas, lo que mantiene el cumplimiento por encima del 80%.
CLAUDE.md
Proyecto
[una frase: qué hace este código base y qué pila tecnológica usa]
Reglas de comportamiento
Piensa antes de codificar
Expón tus suposiciones antes de escribir código. Sacar a la superficie las compensaciones. Pregunta antes de adivinar cualquier cosa que afecte la arquitectura o los datos. Rechaza cuando exista un enfoque más simple.
Simplicidad primero
Escribe el código mínimo que resuelve el problema. Sin funciones especulativas. Sin abstracciones para código de un solo uso. Si un ingeniero senior lo llamaría demasiado complicado, simplifica.
Cambios quirúrgicos
Toca solo lo que requiere la tarea. No mejores código adyacente, formato, comentarios o nombres que no formaban parte de la solicitud. Adáptate exactamente al estilo de código existente.
Ejecución orientada a objetivos
Define cómo se ve el éxito antes de empezar. Itera hasta que esa definición se cumpla y verifique. No pidas instrucciones paso a paso. Encuentra el camino.
Sin llamadas al modelo para decisiones deterministas
Las decisiones de enrutamiento, lógica de reintento, ramificación basada en estado y umbrales pertenecen al código, no a llamadas LLM. Si se puede escribir una regla, escríbela.
Presupuestos de tokens duros
Cada sesión tiene un límite de tokens duro: [establece tu número, ej., 50,000 tokens]. Si se alcanza el límite sin una solución verificada, escribe los hallazgos en un archivo y detente. No continúes más allá del presupuesto.
Un agente, un directorio
Los agentes que se ejecutan en paralelo trabajan en worktrees de git separados. No dos agentes comparten un directorio. Si necesitas un segundo agente, ejecuta: git worktree add ../agent-2 [nombre-de-rama]
Punto de control para trabajo de varios pasos
Para cualquier tarea de más de tres pasos, crea PROGRESS.md en el directorio de trabajo. Escribe en él después de cada paso: qué se hizo, qué se encontró, qué viene después, qué está bloqueado. Si la sesión termina antes de completarse, la siguiente sesión lee PROGRESS.md primero.
Falla fuerte
Si un paso falla, detente e informa el fallo con detalles antes de continuar. Si una prueba pasa pero no cubre el comportamiento real, dilo. Éxito significa verificable, no reportado.
Descripciones de habilidades únicas
Cada habilidad cubre exactamente un trabajo. Su descripción no puede aplicarse a ninguna otra habilidad en el proyecto. Si dos habilidades se superponen en descripción, renombra antes de desplegar.
Investigación e implementación son sesiones separadas
Usa un subagente para cualquier tarea que requiera leer más de cinco archivos o consultar más de dos fuentes. Obtén un informe estructurado. Inicia una sesión limpia para la implementación con solo ese informe como entrada.
Solo hooks con alcance
Cada hook tiene una condición explícita: extensión de archivo, ruta de directorio o evento de sesión. Ningún hook se ejecuta incondicionalmente en cada llamada de herramienta. Agrupa el registro al final de la sesión cuando sea posible.
Qué no tocar
[lista directorios o archivos que claude nunca debe modificar: ej., /secrets, /migrations/archive, /prod-config]
Criterio de éxito predeterminado
Cuando tengas dudas sobre si una tarea está hecha: ¿pasa la prueba, tiene éxito la compilación y es el resultado verificable por algo distinto al propio juicio de claude? Si la respuesta es no a cualquiera de esos, no está hecho.
Cuatro lugares donde la plantilla original se rompe en silencio
Incluso solo con las cuatro reglas originales, hay cuatro condiciones específicas donde la plantilla produce el comportamiento incorrecto y no te lo dice.
Primero: sesiones largas con contexto acumulado. La regla de ejecución orientada a objetivos de karpathy le dice a claude que itere hasta que se verifique. En una sesión larga, «verificado» se vuelve turbio a medida que el contexto se llena. Claude comienza a verificar contra un modelo degradado de lo que se suponía que debía hacer. La solución es la regla 6 (presupuesto de tokens) que fuerza una parada dura.
Segundo: configuraciones multiagente. La regla de cambios quirúrgicos le dice a cada agente que toque solo lo que debe. Pero con dos agentes y sin una regla de propiedad de directorio, «lo que debe» se superpone. La regla 7 (un agente, un directorio) es la pieza faltante.
Tercero: habilidades paralelas con trabajos similares. La plantilla original no tiene nada sobre habilidades. La regla 10 (descripciones de habilidades únicas) cierra el vacío de ambigüedad del despachador.
Cuarto: sesiones que terminan a mitad de tarea. La ejecución orientada a objetivos asume que la sesión se ejecuta hasta completarse. No tiene instrucción sobre qué hacer si la sesión muere en el paso 4 de 8. La regla 8 (archivos de punto de control) le da a la siguiente sesión un punto de partida.
Ninguno de estos son errores en las reglas originales. Son vacíos que las reglas originales no fueron escritas para cubrir.
El número que explica las estrellas de GitHub
120,000 desarrolladores marcaron con estrella un archivo de texto de 65 líneas. Sin código. Sin librería. Sin marco de trabajo. Un archivo con cuatro reglas.
El número que lo explica: 41% de tasa de error en sesiones no supervisadas de claude code sin CLAUDE.md. 11% con las cuatro reglas originales. 3% con las doce completas.
Una reducción de 38 puntos en errores no es una mejora marginal. Para cualquier equipo que ejecute claude code en trabajo real de producción, es la diferencia entre un agente en el que puedes confiar para que se ejecute durante la noche y uno al que tienes que supervisar constantemente.
El archivo al final de este artículo toma cinco minutos pegarlo y rellenarlo. La primera sesión después de hacerlo se sentirá diferente. No porque el modelo haya cambiado. Porque el modelo finalmente sabe cómo funciona tu mundo.
Marca esto como favorito y pega las 12 reglas en tu CLAUDE.md esta noche.
Republica si te resultó útil.
