karpathy se quejó de claude en X. forrest chang convirtió la queja en cuatro reglas y un repositorio de GitHub. el repositorio 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 el CLAUDE.md completo de 12 reglas, por qué existe cada regla, qué falla soluciona y qué es lo que la plantilla original hace mal en silencio. pégalo al final.
¿Qué es CLAUDE.md y por qué la mayoría lo 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 base de código.
la mayoría de los desarrolladores hacen una de tres cosas incorrectas. meten todas las preferencias que han tenido en el archivo hasta que se infla más allá 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 dar el prompt 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 durante semanas a medida que su base de código cambia.
la documentación oficial de anthropic es explícita: CLAUDE.md es consultivo. claude lo sigue aproximadamente el 80% del tiempo con menos de 200 líneas. más allá de 200 líneas, el cumplimiento cae drásticamente. el límite para archivos CLAUDE.md útiles es corto, preciso y se aplica a través de reglas directas, no sugerencias.
Las 4 Reglas Originales: Empieza Aquí Si No Tienes Nada
andrej karpathy, exdirector 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 construye en exceso en lugar de resolver lo 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
expresa tus suposiciones antes de escribir código. saca a relucir las compensaciones. pregunta antes de adivinar. objeta 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 que se usa una vez. si un ingeniero senior lo consideraría demasiado complicado, simplifícalo.
Regla 3 - Cambios Quirúrgicos
toca solo lo que requiere la tarea. no mejores el código, comentarios o formato adyacente. no refactorices lo que no está roto. respeta el estilo existente exactamente.
Regla 4 - Ejecución Orientada a Objetivos
define cómo se ve el éxito antes de empezar. itera hasta que el éxito esté verificado. 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 cierran aproximadamente el 40% de los modos de fallo en sesiones de claude code no supervisadas. el 60% restante vive en vacíos que la plantilla original no aborda, porque esos problemas no existían completamente cuando karpathy publicó su hilo.
Por Qué la Plantilla Original Necesita Extenderse
las cuatro reglas de karpathy fueron construidas 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, bibliotecas de habilidades y flujos de trabajo de varios pasos que abarcan sesiones. la plantilla original no tiene nada que decir sobre nada de eso.
cuatro vacíos específicos aparecen en las reglas originales. primero, peleas de agentes: dos agentes editando los mismos archivos sin reglas de propiedad, pisándose los cambios en silencio. segundo, cascadas de hooks: hooks que se activan 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, rupturas de sesión de 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. la lógica de reintento, los umbrales de enrutamiento, las reglas de escalamiento, la ramificación basada en estado: nada de esto deberían ser llamadas LLM. el modelo decide de manera diferente cada semana según lo que haya en la ventana de contexto. lo que parece un comportamiento consistente es en realidad una varianza que aún no ha salido a la superficie.
el incidente específico: una llamada LLM para "decidir si reintentar en un 503" funcionó durante dos semanas, luego comenzó a producir un 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:
el enrutamiento, la lógica de reintento, la ramificación basada en estado y las decisiones de umbral pertenecen al código, no a las llamadas del modelo. si la salida de una decisión es binaria 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 salirse de control. claude no detendrá una sesión de depuración de 90 minutos por sí solo. seguirá iterando porque la iteración es lo que se le dice que haga. los presupuestos de tokens son el único mecanismo que impone una parada forzosa.
el incidente específico: una sesión de depuración repitiendo el mismo mensaje de error de 8KB durante 90 minutos. al final, claude estaba sugiriendo correcciones que ya había intentado y abandonado dos horas antes. el contexto estaba tan lleno que había perdido el rastro 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 una corrupción de estado silenciosa. un agente escribe un archivo mientras otro lo está leyendo. el resultado son datos que ninguno de los agentes esperaba y ninguno nota.
usa git worktrees. ejecuta git worktree add ../agent-2-branch feature-branch antes de generar 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 git worktrees separados. no hay dos agentes que toquen el mismo directorio al mismo tiempo. cada agente es dueño de su rama.
Regla 8 - Escribe Archivos de Punto de Control en Trabajo 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: lo que se hizo, lo que se encontró, lo que viene después y lo que 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 Ruidosamente o No Falle en Absoluto
claude tiene un fuerte sesgo hacia parecer exitoso. pasará una prueba que en realidad no prueba lo que te importaba. completará una migración mientras omite 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 y reporta la falla 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 omite archivos, enumera los archivos omitidos y detente. éxito significa verificable, no reportado.
Regla 10 - Las Descripciones de Habilidades Deben Ser Únicas
las habilidades se cargan mediante la coincidencia de descripciones. si dos habilidades tienen descripciones superpuestas, el despachador elige una arbitrariamente. la habilidad incorrecta se carga, la tarea se ejecuta con instrucciones incorrectas 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 consultas a la 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 reversión" no lo harán.
agrega esto:
cada descripción de habilidad debe identificar de manera única su trabajo. no debe haber dos habilidades con descripciones que puedan aplicarse a la misma tarea. si dos habilidades suenan similares, una de ellas necesita ser renombrada antes de ser implementada.
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. introduce tangentes, matiza conclusiones que no necesita matizar y pierde la línea de argumentación limpia que habría tenido si empezara de nuevo.
genera 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:
la investigación y la 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 combines investigación y escritura en una sola sesión.
Regla 12 - Los Hooks También Necesitan Presupuestos
los hooks se activan 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, ejecutarse solo cuando se toque una extensión de archivo específica, ejecutarse 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 prueba.
El CLAUDE.md Completo de 12 Reglas - Pega Esto
copia este archivo en la raíz de tu repositorio. completa 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 oración: qué hace esta base de código y qué pila tecnológica usa]
Reglas de Comportamiento
Piensa Antes de Codificar
expresa tus suposiciones antes de escribir código. saca a relucir las compensaciones. pregunta antes de adivinar sobre cualquier cosa que afecte la arquitectura o los datos. objeta 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 consideraría demasiado complicado, simplifícalo.
Cambios Quirúrgicos
toca solo lo que requiere la tarea. no mejores el código, formato, comentarios o nombres adyacentes que no eran parte de la solicitud. respeta el estilo de código existente exactamente.
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
el enrutamiento, la lógica de reintento, la ramificación basada en estado y las decisiones de umbral pertenecen al código, no a las 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 git worktrees separados. no hay dos agentes que compartan un directorio. si necesitas un segundo agente, ejecuta: git worktree add ../agent-2 [nombre-de-la-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: lo que se hizo, lo que se encontró, lo que viene después, lo que está bloqueado. si la sesión termina antes de completarse, la siguiente sesión lee PROGRESS.md primero.
Falla Ruidosamente
si un paso falla, detente y reporta la falla 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 la descripción, renómbralas antes de implementarlas.
La Investigación y la 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
[enumera los directorios o archivos que claude nunca debe modificar: ej., /secretos, /migraciones/archivo, /config-prod]
Criterio de Éxito Predeterminado
cuando tengas dudas sobre si una tarea está hecha: ¿la prueba pasa, la compilación tiene éxito y la salida es verificable por algo que no sea el propio juicio de claude? si la respuesta es no a alguna de esas, no está hecha.
Cuatro Lugares Donde la Plantilla Original se Rompe en Silencio
incluso con solo 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 esté verificado. 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 forzosa.
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 la brecha de ambigüedad del despachador.
cuarto: sesiones que terminan a mitad de la tarea. la ejecución orientada a objetivos asume que la sesión se ejecuta hasta completarse. no tiene instrucciones 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 biblioteca. sin marco de trabajo. un archivo con cuatro reglas.
el número que lo explica: 41% de tasa de error en sesiones de claude code no supervisadas 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 de producción real, es la diferencia entre un agente en el que puedes confiar para que funcione toda la noche y uno al que tienes que supervisar.
el archivo al final de este artículo toma cinco minutos para pegar y completar. 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.
Recomparte si te resultó útil.
