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 solo 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 solían ocurrir ~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: las 12 reglas completas de CLAUDE.md, por qué cada una se ganó su lugar y los 4 puntos donde la plantilla original de Karpathy se rompe 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:

• Lo tratan como un vertedero de todas las preferencias que han tenido, inflado a más de 4,000 tokens, el cumplimiento baja 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 se rompe 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 se entierran en el ruido.

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

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 quejó 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 piso:

**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 funciones especulativas. Sin abstracciones para código de un solo uso. Si un ingeniero senior lo consideraría sobrecomplicado — simplifica.

**Regla 3 — Cambios quirúrgicos.

**Toca solo lo necesario. No "mejores" código, comentarios o formato adyacentes. No refactorices lo que no está roto. Coincide con 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 no supervisadas de Claude Code. El ~60% restante vive en los vacíos a continuación.

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

Cada una 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 no mencionan 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, el código simple responde la pregunta.

El momento: Un 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 el prompt era aleatorio.

Regla 6 — Presupuestos de tokens duros, sin excepciones

Un CLAUDE.md sin presupuestos es un cheque en blanco. Cada bucle tiene la posibilidad 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 continúes a la fuerza.
5Reportar el exceso 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é corrección ya había probado. Al final, sugería correcciones 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 combines.
3Elige uno (el más reciente / el más probado), explica por qué y marca el otro para limpiar.
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 con async/await y 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 "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.
4"Se ve ortogonal" es la frase más peligrosa en esta base de código.

El momento: Claude añadió una función al lado de 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 "Ejecución orientada a objetivos" de Karpathy implica pruebas como criterios de éxito. En la práctica, Claude trata "las 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('Juan')` no vale nada si la función toma un ID hardcodeado.
4Si no puedes escribir una prueba que falle cuando la lógica de negocio cambia, 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 devolvía 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 una sola vez. El trabajo real de Claude Code es de varios pasos: refactorizar en 20 archivos, construir funciones durante 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 vuelve a enunciar.

El momento: Una refactorización de 6 pasos salió mal en el paso 4. Para cuando me di cuenta, Claude también había hecho los pasos 5 y 6 sobre el estado roto. Desenredar 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 — Coincide con 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 de clase. 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 saltó 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 saltaron silenciosamente.
4"Pruebas pasan" es incorrecto si saltaste alguna.
5"Función 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 saltado silenciosamente el 14% de los registros que encontraron una violación de restricción. El salto se registró pero no se reportó. 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 = 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 casi no añadió sobrecarga 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 se rompe 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. No dicen nada 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.

**"Coincide con el estilo existente" asume un solo estilo. En un monorepo 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.

*La "Ejecución orientada a objetivos" trata "las 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 se sienta 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 andamio especulativo para encontrar una dirección. La "Simplicidad primero" de Karpathy dispara en exceso sobre el 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. Más allá, Claude comienza a hacer coincidencia de patrones con "existen reglas" sin leerlas realmente.
• Reglas que dependen de herramientas que podrían no existir. "Usa siempre eslint" se rompe cuando eslint no está instalado. La regla falla silenciosamente. Reemplazado con frases independientes de la capacidad: "coincide con el estilo impuesto por la base de código" en lugar de "usa eslint."
• Ejemplos en CLAUDE.md en lugar de reglas. Los ejemplos son más pesados 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 duro" / "concéntrate realmente." Ruido puro. El cumplimiento con estos bajó a ~30% porque no son comprobables. Reemplazados 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; los prompts 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 funciones 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 necesario. Limpia solo tu propio desorden.
19No "mejores" código, comentarios o formato adyacentes.
20No refactorices lo que no está roto. Coincide con 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.
35Reporta el exceso. 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 limpiar.
40No combines patrones conflictivos.
41
42## Regla 8 — Lee antes de escribir
43Antes de añadir código, lee exportaciones, llamadores inmediatos, utilidades compartidas.
44"Se ve 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.
53Si pierdes el rastro, detente y vuelve a enunciar.
54
55## Regla 11 — Coincide con 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 saltó silenciosamente.
61"Pruebas pasan" es incorrecto si alguna se saltó.
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, más allá, 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 >> importa, 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 debe 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, conserva las que correspondan a 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 enero de 2026 de Karpathy fue una queja. Forrest Chang lo convirtió en 4 reglas. 120,000 desarrolladores marcaron con estrella el resultado. La mayoría todavía ejecuta 4 reglas hoy.

El modelo ha mejorado. El ecosistema ha cambiado. Agentes de varios pasos, cascadas de hooks, carga de habilidades, trabajo en múltiples bases de código — nada de esto existía cuando Karpathy escribió su hilo. Las 4 reglas no los 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. Reenvíalo si te ahorró una semana de errores de Claude.

Telegram para consejos diarios de optimización de Claude:

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