Nota del editor: En enero de 2026, las quejas de Andrej Karpathy sobre Claude generando código dieron lugar a un archivo aparentemente pequeño, pero extremadamente clave en los flujos de trabajo de programación con IA: CLAUDE.md. Forrest Chang posteriormente organizó estos problemas en cuatro reglas de comportamiento, intentando limitar los errores comunes de Claude al codificar: suposiciones silenciosas, sobreingeniería, daño a código no relacionado y falta de criterios claros de éxito.

Pero meses después, los escenarios de uso de Claude Code ya no se limitan a «hacer que el modelo escriba un fragmento de código». Con la normalización de agentes de múltiples pasos, activación en cadena de hooks, carga de habilidades y colaboración entre múltiples repositorios de código, también han surgido nuevos patrones de fallo: el modelo se descontrola en tareas largas, las pruebas pasan sin validar la lógica real, la migración se completa pero omite errores en silencio, y se mezclan incorrectamente estilos de código distintos.

El autor del artículo probó 30 repositorios de código en 6 semanas y añadió 8 nuevas reglas a las 4 originales de Karpathy, intentando abordar los nuevos problemas surgidos cuando la programación de IA evoluciona desde la completación individual hasta la colaboración basada en agentes.

A continuación se encuentra el texto original:

A finales de enero de 2026, Andrej Karpathy publicó una serie de tweets criticando la forma en que Claude escribe código. Señaló tres tipos de problemas típicos: hacer suposiciones erróneas sin especificarlas, complicar en exceso y causar daños irrelevantes en código que originalmente no debía modificarse.

Forrest Chang vio esta cadena de tweets, organizó las quejas en 4 reglas de comportamiento, las escribió en un archivo separado llamado CLAUDE.md y lo publicó en GitHub. El proyecto obtuvo 5.828 estrellas en su primer día, fue guardado 60.000 veces en dos semanas y ahora tiene 120.000 estrellas, convirtiéndose en el repositorio de código de un solo archivo con el crecimiento más rápido de 2026.

Luego, lo probé durante 6 semanas con 30 repositorios de código.

Estas 4 reglas realmente funcionan. El error, que antes ocurría aproximadamente el 40 % de las veces, ha disminuido por debajo del 3 % en tareas donde estas reglas tienen efecto. Pero el problema es que esta plantilla se creó originalmente para resolver los errores que Claude cometía al escribir código en enero.

Para mayo de 2026, los problemas a los que se enfrenta el ecosistema Claude Code son diferentes: conflictos entre agentes, activación en cadena de hooks, conflictos de carga de habilidades y interrupciones de flujos de trabajo multietapa entre sesiones.

Entonces, volví a añadir 8 reglas. A continuación, la versión completa de 12 reglas de CLAUDE.md: por qué cada una merece ser incluida y en qué 4 lugares el modelo original de Karpathy falla silenciosamente.

Si deseas omitir la explicación y copiar directamente, el archivo completo se encuentra al final.

¿Por qué es importante esto?

El archivo CLAUDE.md de Claude Code es el más subestimado de toda la pila de tecnología de programación con IA. La mayoría de los desarrolladores suelen cometer tres tipos de errores:

Primero, trátalo como una papelera de preferencias, mete todos tus hábitos dentro y finalmente se infla hasta más de 4000 tokens, reduciendo la tasa de cumplimiento de las reglas al 30%.

En segundo lugar, simplemente no usarlo en absoluto y volver a hacer el prompt cada vez. Esto provocaría un desperdicio de 5 veces más tokens y una falta de consistencia entre sesiones.

Tercero, copiar una plantilla y luego ignorarla por completo. Podría funcionar durante dos semanas, pero con el tiempo, a medida que cambia la base de código, dejará de funcionar sin que te des cuenta.

La documentación oficial de Anthropic lo dice claramente: CLAUDE.md es esencialmente sugerencial. Claude sigue sus instrucciones aproximadamente el 80 % del tiempo. Una vez que supera las 200 líneas, la tasa de cumplimiento disminuye notablemente, ya que las reglas importantes se pierden entre el ruido.

La plantilla de Karpathy resuelve este problema: un archivo, 65 líneas, 4 reglas. Este es el mínimo básico.

Pero el límite superior aún puede ser más alto. Después de agregar estas 8 reglas adicionales, no solo abarca los problemas de escritura de código que Karpathy comentó en enero de 2026, sino también los problemas de orquestación de Agentes que surgieron recién en mayo de 2026, los cuales aún no existían cuando se escribió la plantilla original.

Las 4 reglas originales

Si aún no has visto el repositorio de Forrest Chang, primero revisa esta versión básica:

Regla 1: Piensa antes de codificar.

No asumas silenciosamente. Explica tus suposiciones y revela los puntos de compromiso. Haz preguntas antes de adivinar. Cuando exista una solución más sencilla, plantea objeciones activamente.

Regla 2: Prioriza la simplicidad.
Usa el mínimo código necesario para resolver el problema. No añadas funciones imaginarias. No diseñes capas de abstracción para código de un solo uso. Si un ingeniero experimentado lo consideraría excesivamente complejo, entonces debes simplificarlo.

Regla 3: Modificaciones quirúrgicas.
Cambia solo lo que sea necesario. No optimices automáticamente el código, comentarios o formato adyacentes. No reestructures nada que no esté roto. Mantén la coherencia con el estilo existente.

Regla 4: Ejecuta con orientación a objetivos.
Defina los criterios de éxito primero, luego itere en bucle hasta completar la validación. No le diga a Claude cómo hacer cada paso, sino qué aspecto debe tener el resultado exitoso, y déjelo iterar por sí mismo.

Estas 4 reglas pueden resolver aproximadamente el 40% de los patrones de fallo que veo en sesiones de Claude Code sin supervisión. El resto, aproximadamente el 60%, se encuentra oculto en estos espacios en blanco.

I added 8 new rules, and why

Cada regla proviene de un momento real: las cuatro reglas originales de Karpathy ya no son suficientes. A continuación, primero describiré el escenario y luego daré la regla correspondiente.

Las reglas de Karpathy no cubren este punto. Por lo tanto, el modelo comenzó a decidir problemas que deberían haberse manejado con código determinista: si volver a intentar una llamada a la API, cómo enrutar un mensaje o cuándo actualizar el procesamiento. El resultado es que los juicios semanales varían. Obtienes un if-else inestable que cuesta $0.003 por token.

Ese momento fue así: había un fragmento de código que llamaba a Claude para «determinar si se debía reintentar al encontrarse con un 503». Al principio funcionaba bien y se mantuvo así durante dos semanas, pero luego se volvió inestable porque el modelo comenzó a incluir el cuerpo de la solicitud como parte del contexto de evaluación. La estrategia de reintentos se volvió aleatoria porque el prompt mismo era aleatorio.

CLAUDE.md sin límites de presupuesto es como un cheque en blanco. Cada ciclo puede descontrolarse y convertirse en una descarga de 50,000 tokens. El modelo no se detendrá por sí solo.

En ese momento, una sesión de depuración duró 90 minutos. El modelo continuó iterando repetidamente sobre el mismo fragmento de 8 KB de mensaje de error y poco a poco olvidó qué soluciones ya había intentado. Al final, comenzó a proponer soluciones que ya había rechazado hace 40 mensajes. Si se hubiera aplicado un presupuesto de tokens, este proceso debería haberse detenido en el minuto 12.

Cuando dos partes del repositorio de código se contradicen, Claude intenta complacer a ambas al mismo tiempo, resultando en un código incoherente.

Ese momento fue así: en el repositorio de código existían dos patrones de manejo de errores, uno basado en async/await con try/catch explícito y otro en límites globales de errores. El nuevo código escrito por Claude utilizó ambos. Como resultado, el manejo de errores se realizó dos veces. Me llevó 30 minutos entender por qué los errores se descartaban dos veces.

La "modificación quirúrgica" de Karpathy le dice a Claude que no modifique el código adyacente, pero no le dice a Claude: primero entienda el código adyacente. Sin esto, Claude escribirá nuevo código que entre en conflicto con el código existente a 30 líneas de distancia.

En ese momento, Claude añadió una función completamente idéntica junto a una función existente, porque no leyó primero la función original. Ambas funciones realizan exactamente lo mismo. Sin embargo, debido al orden de importación, la nueva función reemplazó a la antigua, que había sido el estándar de facto durante seis meses.

La "ejecución orientada a objetivos" de Karpathy sugiere que las pruebas pueden servir como criterio de éxito. Sin embargo, en la práctica, Claude trata "aprobar las pruebas" como el único objetivo, lo que lleva a escribir código que pasa pruebas superficiales pero que daña otras partes.

En ese momento, Claude escribió 12 pruebas para una función de autenticación, todas aprobadas. Pero la lógica de autenticación en producción falló. Esas pruebas solo verificaban que la función «devolviera algo», no que devolviera lo correcto. La función pasó las pruebas porque devolvía una constante.

La plantilla de Karpathy tiene interacciones predeterminadas de un solo uso. Sin embargo, el trabajo real de Claude Code suele ser multietapa: refactorizar a través de 20 archivos, construir funciones en una sola sesión, depurar a través de múltiples commits. Sin puntos de control, un solo error puede hacer que se pierda todo el progreso anterior.

En ese momento, una tarea de reestructuración de 6 pasos falló en el paso 4. Cuando me di cuenta, Claude ya había continuado y completado los pasos 5 y 6 sobre el estado de error. El tiempo que llevó desarmar y corregir fue más largo que volver a hacer toda la tarea. Si hubiera habido puntos de control, se habría detectado el problema en el paso 4.

En un repositorio de código con un modelo ya establecido, Claude tiende a introducir su propia forma de escribir. Incluso si su forma es «mejor», introducir un segundo modelo es peor que cualquier modelo único.

Ese momento fue así: Claude introdujo hooks en una base de código React basada en componentes de clase. Funcionaba, pero rompió el patrón de pruebas existente, ya que esas pruebas dependían de componentDidMount. Al final, tomó media jornada eliminarlo y reescribirlo.

El fracaso más costoso de Claude suele ser aquel que parece un éxito. Una función «funciona», pero devuelve datos incorrectos; una migración «se completó», pero omitió 30 registros; una prueba «pasó», pero solo porque la afirmación en sí era errónea.

Ese momento fue así: Claude dijo que la migración de la base de datos se había «completado con éxito». Pero en realidad, omitió silenciosamente 14% de los registros que generaban conflictos con restricciones de activación. El comportamiento de omisión se registró en los logs, pero no se expuso explícitamente. Once días después, cuando los datos del informe comenzaron a mostrar anomalías, descubrimos el problema.

Durante 6 semanas, rastreé el mismo conjunto de 50 tareas representativas, cubriendo 30 repositorios de código, y probé tres configuraciones.

La tasa de error se refiere a: la tarea necesita ser corregida o reescrita para coincidir con la intención original. Los errores incluidos son: suposiciones silenciosas erróneas, sobreingeniería, destrucción irrelevante, fallos silenciosos, violación de convenciones, compromisos conflictivos y puntos de control omitidos.

La tasa de cumplimiento se refiere a la probabilidad con la que Claude aplica explícitamente una regla cuando dicha regla es aplicable.

El resultado verdaderamente interesante no es solo que la tasa de error disminuyera del 41% al 3%. Más importante aún, al expandirse de 4 reglas a 12 reglas, la carga de cumplimiento apenas aumentó, y la tasa de cumplimiento solo pasó del 78% al 76%, mientras que la tasa de error disminuyó otros 8 puntos porcentuales. Las nuevas reglas abordan modos de falla que no estaban cubiertos por las 4 reglas originales, y no compiten por el mismo presupuesto de atención.

¿Dónde fallará silenciosamente la plantilla Karpathy?

Incluso sin agregar nuevas reglas, las 4 reglas originales del plantilla son insuficientes en al menos 4 lugares.

Primero, tareas de Agent de larga duración.
Las reglas de Karpathy se dirigen principalmente al momento en que Claude está escribiendo código. Pero, ¿qué sucede cuando Claude ejecuta una canalización de múltiples pasos? La plantilla original no tiene reglas de presupuesto, ni reglas de puntos de control, ni reglas de "fallar en voz alta". Por lo tanto, la canalización se desvía lentamente.

En segundo lugar, la consistencia entre múltiples repositorios.
«Coherencia con el estilo existente» por defecto solo tiene un estilo. Pero en un monorepo con 12 servicios, Claude debe elegir cuál estilo coincidir. La regla original no le indica cómo elegir. Por lo tanto, o bien elige aleatoriamente o mezcla los estilos de forma equitativa.

Tercero, la calidad de la prueba.
“Ejecutar con orientación a objetivos” considera “aprobar la prueba” como éxito, pero no especifica que la prueba en sí debe ser significativa. Como resultado, Claude escribe pruebas que casi no verifican nada, pero que le hacen creer que tiene mucha confianza.

Cuarta, la diferencia entre el entorno de producción y la fase de prototipo.
Las mismas 4 reglas pueden evitar que el código de producción se sobrecargue innecesariamente, pero también pueden ralentizar el desarrollo de prototipos, ya que en la fase de prototipo a veces se necesitan realmente 100 líneas de andamiaje exploratorio para definir primero la dirección. El enfoque "simplicidad primero" de Karpathy se activa fácilmente en exceso en el código inicial.

Estas 8 nuevas reglas no pretenden reemplazar las 4 reglas originales de Karpathy, sino completar sus vacíos: la plantilla original estaba diseñada para escenarios de escritura de código con completado automático como los de enero de 2026; pero para mayo de 2026, Claude Code ya ha entrado en un entorno impulsado por Agentes, con múltiples pasos y colaboración entre varios repositorios de código, y los problemas que enfrentan son distintos.

¿Qué métodos no funcionaron?

Antes de finalizar estas 12 reglas, también probé algunas otras alternativas.

Incluye las reglas que vi en Reddit / X.
La mayoría de ellos simplemente repetían las cuatro reglas originales de Karpathy con diferentes palabras, o eran reglas específicas del dominio que no se podían generalizar, como «siempre usa clases de Tailwind». Finalmente, se eliminaron todas.

Más de 12 reglas.
Probé hasta 18 líneas. Después de 14, la tasa de cumplimiento bajó del 76% al 52%. El límite de 200 líneas es real; después de esta longitud, Claude comienza a hacer coincidencia de patrones como «aquí hay reglas», en lugar de leer realmente cada regla.

Reglas que dependen de la existencia de ciertas herramientas.
Por ejemplo, «siempre usa eslint»; si en el proyecto no se ha instalado eslint, esta regla dejará de funcionar y lo hará silenciosamente. Más tarde, la cambié por una expresión que no depende de una herramienta específica, como reemplazar «usa eslint» con «sigue el estilo ya impuesto en la base de código».

En CLAUDE.md, muestra ejemplos, no reglas.
Los ejemplos ocupan más contexto que las reglas. Tres ejemplos consumen aproximadamente el mismo contexto que 10 reglas, y Claude tiende a sobreajustarse fácilmente a los ejemplos. Las reglas son abstractas, los ejemplos son concretos. Por lo tanto, se deben utilizar reglas.

Ten cuidado. Piensa con cuidado. Concéntrate.
Esto es todo ruido. La tasa de cumplimiento de este tipo de instrucciones cayó a alrededor del 30% porque no se pueden verificar. Luego las reemplacé con reglas imperativas más específicas, como «especificar claramente las suposiciones».

Dile a Claude que actúe como un ingeniero experimentado.
Esto no funciona. Claude ya se considera un ingeniero experimentado. El problema real no es si lo cree, sino si lo ejecuta. Las reglas imperativas pueden reducir esta brecha; los prompts de identidad no.

Versión completa de 12 reglas de CLAUDE.md

Aquí tienes la versión completa lista para copiar y pegar.

Este contenido no puede mostrarse fuera de los documentos de Feishu temporalmente

Guárdalo como CLAUDE.md en el directorio raíz del repositorio. Debajo de estas 12 reglas, agrega reglas específicas del proyecto, como pila tecnológica, comandos de prueba, patrones de error, etc. En total, no superes las 200 líneas, ya que después de eso, la adherencia a las reglas disminuye notablemente.

¿Cómo instalar?

Solo dos pasos:

1. Añade las 4 reglas básicas de Karpathy a tu archivo CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. Pegue las reglas 5–12 del presente artículo a continuación

Guarde el archivo en la raíz del repositorio. Los >> son importantes, ya que agregan al archivo CLAUDE.md existente en lugar de reemplazar las reglas específicas del proyecto que ya ha escrito.

CLAUDE.md no es una lista de deseos, sino un contrato de comportamiento diseñado para cerrar los patrones de fracaso específicos que ya has observado.

Cada regla debe responder una pregunta: ¿qué error impide?

Las 4 reglas de Karpathy previenen los patrones de fracaso que vio en enero de 2026: suposiciones silenciosas, sobrecarga técnica, destrucción irrelevante y criterios de éxito débiles. Son fundamentales; no las omitas.

Mis 8 nuevas reglas previenen nuevos modos de fallo que surgirán después de mayo de 2026: ciclos de Agentes sin restricciones de presupuesto, tareas multietapa sin puntos de control, pruebas que parecen haberse realizado pero que no cubren la lógica clave, y el problema de presentar fallos silenciosos como éxitos silenciosos. Son parches incrementales.

Claro, los resultados varían según la persona. Si no ejecutas un pipeline de múltiples pasos, la regla 10 no es tan relevante para ti. Si tu base de código tiene un solo estilo uniforme ya impuesto por un linter, la regla 11 es redundante. Tras leer estas 12 reglas, conserva solo aquellas que realmente se corresponden con errores que hayas cometido realmente y elimina el resto.

Una versión de 6 reglas de CLAUDE.md personalizada para patrones de fallo reales, que supera una versión de 12 reglas donde 6 nunca usarás.

Conclusión

El tweet de Karpathy de enero de 2026 fue, en esencia, una queja. Forrest Chang lo convirtió en 4 reglas. Finalmente, 120.000 desarrolladores dieron "Me gusta" a este resultado. Y la mayoría de ellos, hoy en día, aún solo usan esas 4 reglas.

Los modelos han avanzado y el ecosistema ha cambiado. Agentes de múltiples pasos, activación en cadena de hooks, carga de habilidades, colaboración entre múltiples repositorios de código: todo esto no existía cuando Karpathy escribió ese tweet. Las cuatro reglas originales no resuelven estos problemas. No están mal, sino que son incompletas.

Se agregaron 8 nuevas reglas. En 6 semanas, se probaron 30 repositorios de código. La tasa de errores disminuyó del 41% al 3%.

Guarde este artículo esta noche y pegue estas 12 reglas en su CLAUDE.md. Si le ahorra una semana de curva de aprendizaje con Claude, compártalo.