Las 4 reglas CLAUDE.md de Karpathy redujeron los errores de Claude del 41% al 11%. Tras probar 30 bases de código, añadí 8 más

A finales de enero de 2026, Andrej Karpathy publicó un hilo quejándose de cómo Claude escribe código. Tres modos de fallo: suposiciones incorrectas silenciosas, sobrecomplicación, daño ortogonal a código que no debería haber tocado.

Forrest Chang leyó el hilo, empaquetó las quejas en 4 reglas de comportamiento en un único archivo CLAUDE.md y lo subió a GitHub. Consiguió 5.828 estrellas el primer día. 60.000 marcadores en dos semanas. 120.000 estrellas hoy. El repositorio de un solo archivo de más rápido crecimiento de 2026.

Luego lo probé en 30 bases de código durante 6 semanas.

Las 4 reglas funcionan. Los errores que antes ocurrían ~40% de las veces bajaron a menos del 3% en tareas que aprovechaban sus puntos fuertes. Pero la plantilla se creó para corregir errores de escritura de código de enero.

El ecosistema de Claude Code en mayo de 2026 tiene problemas diferentes: peleas entre agentes, cascadas de hooks, conflictos de carga de habilidades, flujos de trabajo de varios pasos que se rompen entre sesiones.

Así que añadí 8 reglas más. A continuación: la plantilla completa de 12 reglas de CLAUDE.md, por qué cada una se ganó su lugar y los 4 puntos donde la plantilla original de Karpathy falla silenciosamente.

Si quieres saltarte las explicaciones y solo pegar, el archivo completo está al final.

Por qué esto importa

El CLAUDE.md de Claude Code es el archivo más infrautilizado de todo el stack de codificación con IA. La mayoría de los desarrolladores o bien:

• Lo tratan como un vertedero para todas las preferencias que han tenido, inflado a más de 4.000 tokens, el cumplimiento cae al 30%
• Lo omiten por completo y dan instrucciones cada vez — 5x de desperdicio de tokens, sin consistencia entre sesiones
• Copian una plantilla una vez y se olvidan. Funciona dos semanas, luego falla silenciosamente 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. Pasadas las 200 líneas, el cumplimiento cae drásticamente porque las reglas importantes quedan enterradas en el ruido.

La plantilla de Karpathy resolvió esto en un archivo, 65 líneas, 4 reglas. Ese es el mínimo.

El techo es más alto. Con 8 reglas más, las que repasaré a continuación, cubres no solo los problemas de escritura de código de enero de 2026 de los que se quejaba Karpathy, sino los problemas de orquestación de agentes de mayo de 2026 que aún no existían cuando se escribió la plantilla.

Las 4 reglas originales

Si no has leído el repositorio de Forrest Chang, el mínimo:

**Regla 1 — Piensa antes de codificar.

**Sin suposiciones silenciosas. Indica lo que estás asumiendo. Expón las compensaciones. Pregunta antes de adivinar. Rechaza cuando exista un enfoque más simple.

**Regla 2 — Simplicidad primero.

**Mínimo código que resuelva el problema. Sin funcionalidades especulativas. Sin abstracciones para código de un solo uso. Si un ingeniero senior lo llamaría sobrecomplicado — simplifica.

**Regla 3 — Cambios quirúrgicos.

**Toca solo lo que debas. No "mejores" el código adyacente, comentarios o formato. No refactorices lo que no está roto. Respeta el estilo existente.

**Regla 4 — Ejecución orientada a objetivos.

**Define criterios de éxito. Itera hasta verificar. No le digas a Claude qué pasos seguir, dile cómo se ve el éxito y déjalo iterar.

Estas cuatro cierran ~40% de los modos de fallo que veo en sesiones de Claude Code no supervisadas. El ~60% restante vive en los vacíos que siguen.

Las 8 reglas que añadí (y por qué)

Cada una de estas surgió de un momento real donde las 4 de Karpathy no eran suficientes. Mostraré el momento, luego la regla.

Regla 5 — No hagas que el modelo haga trabajo no lingüístico

Las reglas de Karpathy guardan silencio sobre esto. El modelo decide cosas que deberían ser código determinista: si reintentar una llamada API, cómo enrutar un mensaje, cuándo escalar. Decisiones diferentes cada semana. If-else inestable a $0.003 por token.

1## Regla 5 — Usa el modelo solo para juicios
2Usa Claude para: clasificación, redacción, resumen, extracción de texto no estructurado.
3NO uses Claude para: enrutamiento, reintentos, manejo de códigos de estado, transformaciones deterministas.
4Si un código de estado ya responde la pregunta, código simple responde la pregunta.

El momento: Código que llamaba a Claude para "decidir si reintentar en un 503" funcionó perfectamente durante dos semanas, luego empezó a fallar porque el modelo comenzó a leer el cuerpo de la solicitud como contexto para la decisión. La política de reintentos era aleatoria porque la instrucción era aleatoria.

Regla 6 — Presupuestos de tokens estrictos, sin excepciones

CLAUDE.md sin presupuestos es un cheque en blanco. Cada bucle tiene la oportunidad de convertirse en un volcado de contexto de 50.000 tokens. El modelo no se detendrá por sí solo.

1## Regla 6 — Los presupuestos de tokens no son consultivos
2Presupuesto por tarea: 4.000 tokens.
3Presupuesto por sesión: 30.000 tokens.
4Si una tarea se acerca al presupuesto, resume y empieza de nuevo. No sigas adelante.
5Informar la infracción es mejor que excederse silenciosamente.

El momento: Una sesión de depuración duró 90 minutos. El modelo estaba perfectamente contento iterando sobre el mismo mensaje de error de 8KB, perdiendo gradualmente el rastro de qué solución ya había probado. Al final, sugería soluciones que había rechazado 40 mensajes antes. Un presupuesto de tokens lo habría detenido en el minuto 12.

Regla 7 — Expón los conflictos, no los promedies

Cuando dos partes de la base de código discrepan, Claude intenta complacer a ambas. El resultado es incoherente.

1## Regla 7 — Expón los conflictos, no los promedies
2Si dos patrones existentes en la base de código se contradicen, no los mezcles.
3Elige uno (el más reciente / el más probado), explica por qué y marca el otro para limpieza.
4El código "promedio" que satisface ambas reglas es el peor código.

El momento: Una base de código tenía dos patrones de manejo de errores: uno async/await con try/catch explícito, otro con un límite de error global. Claude escribió código nuevo que hacía ambos. Manejadores de error duplicados. Me tomó 30 minutos descubrir por qué los errores se tragaban dos veces.

Regla 8 — Lee antes de escribir

La "Regla 3 — Cambios quirúrgicos" de Karpathy le dice a Claude que no toque código adyacente. No le dice que entienda el código adyacente primero. Sin esto, Claude escribe código nuevo que entra en conflicto con código existente a 30 líneas de distancia.

1## Regla 8 — Lee antes de escribir
2Antes de añadir código en un archivo, lee las exportaciones del archivo, el llamador inmediato y cualquier utilidad compartida obvia.
3Si no entiendes por qué el código existente está estructurado como está, pregunta antes de añadirle algo.
4"Me parece ortogonal" es la frase más peligrosa en esta base de código.

El momento: Claude añadió una función junto a una función idéntica existente que no había leído. Ambas funciones hacían lo mismo. La nueva tomó prioridad por el orden de importación. La antigua había sido la fuente de verdad durante 6 meses.

Regla 9 — Las pruebas no son opcionales, pero no son el objetivo

La "Regla 4 — Ejecución orientada a objetivos" de Karpathy implica pruebas como criterio de éxito. En la práctica, Claude trata "pruebas pasan" como el único objetivo y escribe código que pasa pruebas superficiales mientras rompe todo lo demás.

1## Regla 9 — Las pruebas verifican la intención, no solo el comportamiento
2Cada prueba debe codificar POR QUÉ el comportamiento importa, no solo QUÉ hace.
3Una prueba como `expect(getUserName()).toBe('John')` no vale nada si la función toma un ID fijo.
4Si no puedes escribir una prueba que falle cuando la lógica de negocio cambie, la función está mal.

El momento: Claude escribió 12 pruebas para una función de autenticación. Todas pasaron. La autenticación estaba rota en producción. Las pruebas verificaban que la función devolviera algo, no si devolvía lo correcto. La función pasaba porque devolvía una constante.

Regla 10 — Las operaciones de larga duración necesitan puntos de control

La plantilla de Karpathy asume interacciones de un solo paso. El trabajo real de Claude Code es de varios pasos: refactorizar en 20 archivos, construir funcionalidades a lo largo de una sesión, depurar a través de múltiples commits. Sin puntos de control, un giro equivocado pierde todo el progreso.

1## Regla 10 — Punto de control después de cada paso significativo
2Después de completar cada paso en una tarea de varios pasos: resume lo que se hizo, lo que está verificado, lo que queda.
3No continúes desde un estado que no puedas describirme.
4Si pierdes el rastro, detente y reformula.

El momento: Una refactorización de 6 pasos salió mal en el paso 4. Cuando me di cuenta, Claude ya había hecho los pasos 5 y 6 sobre el estado roto. Desenredarlo tomó más tiempo que rehacer todo. Los puntos de control lo habrían detectado en el paso 4.

Regla 11 — La convención vence a la novedad

En una base de código con patrones establecidos, a Claude le gusta introducir los suyos propios. Incluso cuando su forma es "mejor", la introducción de dos patrones es peor que cualquiera de los patrones por separado.

1## Regla 11 — Respeta las convenciones de la base de código, incluso si no estás de acuerdo
2Si la base de código usa snake_case y prefieres camelCase: snake_case.
3Si la base de código usa componentes basados en clases y prefieres hooks: basados en clases.
4El desacuerdo es una conversación aparte. Dentro de la base de código, conformidad > gusto.
5Si realmente crees que la convención es dañina, expónlo. No la bifurques silenciosamente.

El momento: Claude introdujo hooks de React en una base de código de componentes basados en clases. Funcionaron. También rompieron los patrones de prueba de la base de código, que asumían componentDidMount. Medio día para eliminar y reescribir.

Regla 12 — Falla visiblemente, no silenciosamente

Los fallos más costosos de Claude son los que parecen éxito. Una función "funciona" pero devuelve datos incorrectos. Una migración "se completa" pero omitió 30 registros. Una prueba "pasa" pero solo porque la aserción era incorrecta.

1## Regla 12 — Falla fuerte
2Si no puedes estar seguro de que algo funcionó, dilo explícitamente.
3"Migración completada" es incorrecto si 30 registros se omitieron silenciosamente.
4"Pruebas pasan" es incorrecto si omitiste alguna.
5"Funcionalidad funciona" es incorrecto si no verificaste el caso límite que te pregunté.
6Por defecto, expón la incertidumbre, no la ocultes.

El momento: Claude dijo que una migración de base de datos "se completó exitosamente". Había omitido silenciosamente el 14% de los registros que encontraron una violación de restricción. La omisión se registró pero no se informó. Descubrí el problema 11 días después, cuando los informes empezaron a verse incorrectos.

Los números

Seguí el mismo conjunto de 50 tareas representativas en 30 bases de código durante 6 semanas. Tres configuraciones:

Tasa de error = la tarea requirió corrección o reescritura para coincidir con la intención. Cuenta: suposición incorrecta silenciosa, sobreingeniería, daño ortogonal, fallo silencioso, violación de convención, promediado de conflictos, punto de control omitido.

Cumplimiento = con qué frecuencia Claude aplicó visiblemente la regla relevante cuando era aplicable.

El resultado interesante no es la caída principal del 41% al 3%. Es que pasar de 4 reglas a 12 añadió casi ningún overhead de cumplimiento (78% -> 76%) pero redujo la tasa de error en otros 8 puntos. Las nuevas reglas cubren modos de fallo que las 4 originales no abordaban — no compiten por el mismo presupuesto de atención.

Donde la plantilla de Karpathy falla silenciosamente

Cuatro lugares donde la plantilla original de 4 reglas no es suficiente, incluso antes de añadir nuevas reglas:

**1. Tareas de agente de larga duración.

*Las reglas de Karpathy apuntan al momento en que Claude está escribiendo código. Guardan silencio sobre lo que sucede cuando Claude está ejecutando* un pipeline de varios pasos. Sin regla de presupuesto. Sin regla de punto de control. Sin regla de "falla fuerte". Los pipelines se desvían.

**2. Consistencia entre múltiples bases de código.

**"Respeta el estilo existente" asume un solo estilo. En un monorepositorio con 12 servicios, Claude tiene que elegir qué estilo. Las reglas originales no le dicen cómo. Elige al azar o promedia.

**3. Calidad de las pruebas.

*"Ejecución orientada a objetivos" trata "pruebas pasan" como éxito. No dice que las pruebas tengan que ser significativas*. El resultado son pruebas que no prueban nada útil pero hacen que Claude esté seguro.

**4. Producción vs. prototipo.

**Las mismas 4 reglas que protegen el código de producción de la sobreingeniería también ralentizan los prototipos que legítimamente necesitan 100 líneas de andamiaje especulativo para encontrar una dirección. La "Regla 2 — Simplicidad primero" de Karpathy dispara en exceso en código en etapas tempranas.

Las 8 reglas añadidas no reemplazan las 4 de Karpathy. Parchean los vacíos donde su modelo, enero de 2026, codificación estilo autocompletado, no coincide con el trabajo de mayo de 2026, impulsado por agentes, de varios pasos y múltiples bases de código.

Lo que no funcionó

Cosas que probé antes de decidirme por las 12 reglas:

• Añadir reglas que había visto en Reddit / X. La mayoría eran reformulaciones de las 4 de Karpathy con diferentes palabras, o reglas específicas de dominio ("usa siempre clases de Tailwind") que no generalizan. Las eliminé.
• Más de 12 reglas. Probé hasta 18. El cumplimiento bajó del 76% al 52% después de 14 reglas. El límite de 200 líneas es real. Pasado ese punto, Claude empieza a hacer coincidencia de patrones con "existen reglas" sin leerlas realmente.
• Reglas que dependen de herramientas que podrían no existir. "Usa siempre eslint" falla cuando eslint no está instalado. La regla falla silenciosamente. Las reemplacé con frases independientes de la capacidad: "respeta el estilo impuesto por la base de código" en lugar de "usa eslint".
• Ejemplos en CLAUDE.md en lugar de reglas. Los ejemplos pesan más que las reglas. Tres ejemplos cuestan tanto contexto como ~10 reglas y Claude se sobreajusta a ellos. Las reglas son abstractas, los ejemplos son específicos. Usa reglas.
• "Ten cuidado" / "piensa mucho" / "concéntrate de verdad". Puro ruido. El cumplimiento de estas cayó a ~30% porque no son comprobables. Las reemplacé con imperativos concretos ("indica las suposiciones explícitamente").
• Decirle a Claude que sea "senior". No funciona. Claude ya cree que es senior. La brecha de cumplimiento está entre pensar y hacer. Las reglas imperativas cierran la brecha; las instrucciones de identidad no.

El CLAUDE.md completo de 12 reglas (listo para copiar y pegar)

1# CLAUDE.md — Plantilla de 12 reglas
2
3Estas reglas aplican a cada tarea en este proyecto a menos que se anulen explícitamente.
4Sesgo: precaución sobre velocidad en trabajo no trivial. Usa el juicio en tareas triviales.
5
6## Regla 1 — Piensa antes de codificar
7Indica las suposiciones explícitamente. Si hay incertidumbre, pregunta en lugar de adivinar.
8Presenta múltiples interpretaciones cuando exista ambigüedad.
9Rechaza cuando exista un enfoque más simple.
10Detente cuando estés confundido. Nombra lo que no está claro.
11
12## Regla 2 — Simplicidad primero
13Mínimo código que resuelva el problema. Nada especulativo.
14Sin funcionalidades más allá de lo solicitado. Sin abstracciones para código de un solo uso.
15Prueba: ¿un ingeniero senior diría que esto está sobrecomplicado? Si es así, simplifica.
16
17## Regla 3 — Cambios quirúrgicos
18Toca solo lo que debas. Limpia solo tu propio desorden.
19No "mejores" el código adyacente, comentarios o formato.
20No refactorices lo que no está roto. Respeta el estilo existente.
21
22## Regla 4 — Ejecución orientada a objetivos
23Define criterios de éxito. Itera hasta verificar.
24No sigas pasos. Define el éxito e itera.
25Criterios de éxito sólidos te permiten iterar de forma independiente.
26
27## Regla 5 — Usa el modelo solo para juicios
28Úsame para: clasificación, redacción, resumen, extracción.
29NO me uses para: enrutamiento, reintentos, transformaciones deterministas.
30Si el código puede responder, el código responde.
31
32## Regla 6 — Los presupuestos de tokens no son consultivos
33Por tarea: 4.000 tokens. Por sesión: 30.000 tokens.
34Si te acercas al presupuesto, resume y empieza de nuevo.
35Informa la infracción. No te excedas silenciosamente.
36
37## Regla 7 — Expón los conflictos, no los promedies
38Si dos patrones se contradicen, elige uno (el más reciente / el más probado).
39Explica por qué. Marca el otro para limpieza.
40No mezcles patrones contradictorios.
41
42## Regla 8 — Lee antes de escribir
43Antes de añadir código, lee las exportaciones, los llamadores inmediatos, las utilidades compartidas.
44"Parece ortogonal" es peligroso. Si no estás seguro de por qué el código está estructurado de cierta manera, pregunta.
45
46## Regla 9 — Las pruebas verifican la intención, no solo el comportamiento
47Las pruebas deben codificar POR QUÉ el comportamiento importa, no solo QUÉ hace.
48Una prueba que no puede fallar cuando la lógica de negocio cambia está mal.
49
50## Regla 10 — Punto de control después de cada paso significativo
51Resume lo que se hizo, lo que está verificado, lo que queda.
52No continúes desde un estado que no puedas describir de vuelta.
53Si pierdes el rastro, detente y reformula.
54
55## Regla 11 — Respeta las convenciones de la base de código, incluso si no estás de acuerdo
56Conformidad > gusto dentro de la base de código.
57Si realmente crees que una convención es dañina, expónlo. No la bifurques silenciosamente.
58
59## Regla 12 — Falla fuerte
60"Completado" es incorrecto si algo se omitió silenciosamente.
61"Pruebas pasan" es incorrecto si alguna se omitió.
62Por defecto, expón la incertidumbre, no la ocultes.

Guárdalo como CLAUDE.md en la raíz de tu repositorio. Añade reglas específicas del proyecto debajo de las 12 (stack, comandos de prueba, patrones de error). No superes las 200 líneas combinadas, pasado ese punto, el cumplimiento cae.

Cómo instalarlo

Dos pasos:

1# 1. Añade la línea base de 4 reglas de Karpathy a tu CLAUDE.md
2curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
3
4# 2. Pega las reglas 5-12 de este artículo debajo

Guárdalo en la raíz de tu repositorio. El >> es importante, añade a tu CLAUDE.md existente en lugar de sobrescribir cualquier regla específica del proyecto que ya tengas.

El modelo mental

CLAUDE.md no es una lista de deseos. Es un contrato de comportamiento que cierra modos de fallo específicos que has observado.

Cada regla debería responder: ¿qué error previene esto?

Las 4 de Karpathy previenen los modos de fallo que vio en enero de 2026: suposiciones silenciosas, sobreingeniería, daño ortogonal, criterios de éxito débiles. Son fundamentales. No las omitas.

Las 8 que añadí previenen modos de fallo que surgieron en mayo de 2026: bucles de agente sin presupuestos, tareas de varios pasos sin puntos de control, pruebas que no prueban, éxitos silenciosos que ocultan fallos silenciosos. Son aditivas.

Tu experiencia puede variar. Si no ejecutas pipelines de varios pasos, la Regla 10 no importa. Si tu base de código tiene un estilo consistente impuesto por linting, la Regla 11 es redundante. Lee las 12, quédate con las que se correspondan con errores que realmente hayas cometido, descarta el resto.

Un CLAUDE.md de 6 reglas ajustado a tus modos de fallo reales supera a uno de 12 reglas con 6 reglas que nunca necesitarás.

F I N

El hilo de Karpathy de enero de 2026 fue una queja. Forrest Chang la convirtió en 4 reglas. 120.000 desarrolladores marcaron el resultado con estrella. La mayoría de ellos todavía usan 4 reglas hoy.

El modelo ha mejorado. El ecosistema ha cambiado. Agentes de varios pasos, cascadas de hooks, carga de habilidades, trabajo con múltiples bases de código — nada de esto existía cuando Karpathy escribió su hilo. Las 4 reglas no lo abordan. No están equivocadas; están incompletas.

8 reglas más. 6 semanas de pruebas en 30 bases de código. Tasa de error del 41% al 3%.

Guarda esto y pega las 12 reglas en tu CLAUDE.md esta noche. Compártelo de nuevo si te ahorró una semana de giros equivocados de Claude.

Telegram para consejos diarios de optimización de Claude:

*https://t.me/+_ZWrQN7GuDA3ZDEy*