Reglas CLAUDE.md de Karpathy + 8 más: La plantilla de 12 reglas probada en 30 codebases

Finales de enero de 2026: Andrej Karpathy publica un hilo en X quejándose de cómo Claude escribe código. Tres modos de fallo — suposiciones erróneas silenciosas, sobrecomplicación y daño ortogonal al código que no debería haber tocado. Forrest Chang lee el hilo, empaqueta las quejas en 4 reglas de comportamiento en un solo archivo CLAUDE.md y lo sube a GitHub. 5,828 estrellas el primer día. 60,000 marcadores en dos semanas. 120,000 estrellas para mediados de 2026. El repositorio de un solo archivo con el crecimiento más rápido del año. El 9 de mayo de 2026, un desarrollador verificado con el usuario @mnilax (Mnimiy) publicó un artículo extenso en X con una de las afirmaciones de ingeniería más agudas del año: probaron la plantilla en 30 bases de código durante 6 semanas y luego añadieron 8 reglas más para cerrar las brechas. 2.7 millones de visualizaciones, 18,800 marcadores. Este es el desglose completo — y lo que significa si estás ejecutando Claude dentro de Antigravity (o cualquier otro IDE de agentes) con un GEMINI.md o AGENTS.md archivo.

La publicación original de @mnilax en X que este artículo analiza — 2,7M visualizaciones, 18,8K marcadores, 9 de mayo de 2026.

1. El momento viral

El hilo original de Karpathy no era prescriptivo. Era una queja — del tipo que los ingenieros senior publican después de una mala tarde. Tres modos de fallo específicos:

1. Suposiciones erróneas silenciosas. Claude infiere lo que quisiste decir, construye sobre la inferencia incorrecta y nunca te lo dice.
2. Sobrecomplicación. Claude recurre a abstracciones, capas y helpers genéricos. El arreglo de 4 líneas se convierte en 40 líneas.
3. Daño ortogonal. Claude "mejora" código que no debería haber tocado — espacios en blanco, nombres, formato y funciones adyacentes por las que no se preguntó.

Forrest Chang leyó el hilo e hizo el trabajo que nadie más hizo: escribió lo que Karpathy pedía implícitamente. Cuatro reglas cortas e imperativas. Un archivo. 65 líneas. Repositorio público. El ritmo importa — Forrest no añadió comentarios, no lo convirtió en un framework, no lo monetizó. Solo las reglas.

Tocó una fibra sensible. Los desarrolladores que habían estado luchando con Claude todos los días de repente tuvieron una instalación de una sola línea: pega este archivo en la raíz de tu repositorio. Las métricas cuentan la historia — 120,000 estrellas en un archivo que no contiene código. La mayoría de esos desarrolladores todavía ejecutan solo esas cuatro reglas hoy en día.

2. Las 4 reglas originales (Karpathy vía Forrest Chang)

Aquí tienes la base — las reglas en su forma original. Si aún no tienes un CLAUDE.md, empieza con estas:

Datos de Mnimiy: estas cuatro cierran ~40% de los modos de fallo en sesiones no supervisadas de Claude Code. El ~60% restante reside en las brechas que la plantilla original no aborda.

3. Por qué era necesario ampliarlo

La plantilla se escribió en enero de 2026. El ecosistema de Claude Code en mayo de 2026 es un mundo distinto. El artículo señala cuatro realidades posteriores a enero que las 4 reglas originales no cubren:

• Conflictos entre agentes. Configuraciones multi-agente donde dos agentes editan los mismos archivos y se pisan entre sí. Las reglas de Karpathy asumen un único bucle de autocompletado. La orquestación multi-agente necesita reglas de propiedad.
• Cascadas de hooks. Los hooks de Claude Code se activan con cada llamada a una herramienta. Sin presupuestos, un hook ruidoso convierte una solicitud de 200 tokens en una de 8,000 tokens.
• Conflictos de carga de habilidades. Múltiples Habilidades con descripciones que se solapan confunden al despachador de coincidencia de descripciones. La plantilla original no incluye nada sobre cómo desambiguar.
• Flujos de trabajo de varios pasos. Un refactor de 6 pasos que falla en el paso 4 significa que los pasos 5 y 6 se construyen sobre un estado defectuoso. La plantilla original trata cada turno de Claude como un one-shot.

La tesis de Mnimiy: las 4 originales son fundamentales, no erróneas. Están incompletas.

4. Las 8 nuevas reglas (cada una con el momento en que se ganó su lugar)

Cada una de estas surgió de un incidente específico a lo largo del estudio de 30 codebases. El artículo muestra el momento y luego la regla. A continuación: la misma estructura, condensada.

Regla 5 — No obligues al modelo a realizar tareas que no sean de lenguaje

Las decisiones deterministas pertenecen al código determinista. Políticas de reintento, enrutamiento, umbrales de escalada — no a llamadas de LLM. El modelo decide de forma distinta cada semana.

El momento: Una llamada de LLM para "decidir si reintentar tras un 503" funcionó 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 reintento se volvió aleatoria porque el prompt era, en la práctica, aleatorio.

Regla 6 — Presupuestos de tokens estrictos, sin excepciones

Cada bucle tiene el riesgo de derivar en un volcado de contexto de 50,000 tokens. El modelo no se detendrá por sí solo. Los presupuestos te dan un límite mínimo estricto.

El momento: Una sesión de depuración de 90 minutos iterando sobre el mismo mensaje de error de 8KB. Al final, Claude sugería correcciones que el usuario ya había rechazado 40 mensajes atrás. Un presupuesto de tokens habría cortado el bucle en el minuto 12.

Regla 7 — Haz que los conflictos salgan a la superficie, no los promedies

Cuando dos partes de la codebase no coinciden, Claude intenta complacer a ambas. El resultado es un código incoherente que combina ambos patrones y no funciona correctamente con ninguno de los dos.

El momento: Una base de código tenía dos patrones de manejo de errores — async/await con try/catch y un global error boundary. Claude escribió código que hacía ambos. Los errores se silenciaron dos veces. 30 minutos para descubrirlo.

Regla 8 — Lee antes de escribir

Los "Surgical Changes" de Karpathy le dicen a Claude que no toque el código adyacente. No le dicen a Claude que entienda el código adyacente. Sin esta adición, Claude escribe código nuevo que entra en conflicto con el código existente 30 líneas más abajo.

El momento: Claude added a function next to an existing identical function it hadn't read. The new one won by import order. The original had been the source of truth for 6 months.

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

Goal-Driven Execution trata el hecho de que "las pruebas pasen" como un éxito. En la práctica, Claude escribe código que pasa pruebas superficiales mientras rompe el comportamiento en producción.

El momento: 12 pruebas para una función de auth, todas pasando, auth rota en producción. Las pruebas verificaban que la función devolvía algo, no si devolvía lo correcto. La función pasó porque estaba devolviendo una constante.

Regla 10 — Las operaciones de larga duración necesitan checkpoints

La plantilla original asume interacciones one-shot. El trabajo real con Claude Code es de varios pasos — refactorizaciones en 20 archivos, funcionalidades a lo largo de una sesión, depuración entre commits. Sin checkpoints, un paso en falso hace que se pierda todo el progreso.

El momento: Una refactorización de 6 pasos salió mal en el paso 4. Claude procedió a realizar los pasos 5 y 6 sobre el estado dañado. Desenredarlo tomó más tiempo que rehacer toda la refactorización.

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", introducir un segundo patrón es peor que cualquiera de los dos patrones por separado.

El momento: Claude introdujo React hooks en una base de código de class-components. Los hooks funcionaron. También rompieron los patrones de prueba de la base de código, que asumían componentDidMount. Medio día para eliminar y rehacer.

Regla 12 — Falla de forma visible, no silenciosa

Los fallos más costosos de Claude parecen éxitos. Una función "funciona" pero devuelve datos erróneos. Una migración se "completa" pero omitió 30 registros. Un test "pasa" pero la aserción era incorrecta.

El momento: Claude informó que una migración de base de datos se "completó con éxito." Había omitido silenciosamente el 14% de los registros que sufrieron una violación de restricción. La omisión fue registrada pero no notificada. Se descubrió 11 días después cuando los reportes empezaron a verse mal.

5. Los números

Mnimiy monitoreó las mismas 50 tareas representativas en 30 codebases durante 6 semanas, bajo tres configuraciones: sin CLAUDE.md, con las 4 reglas originales y con las 12 reglas completas. La tasa de error es el porcentaje de tareas que requirieron corrección o reescritura para cumplir con la intención — contabilizada en siete tipos de fallos distintos (suposición errónea silenciosa, sobreingeniería, daño ortogonal, fallo silencioso, violación de convenciones, promedio de conflicto, punto de control omitido).

La caída más destacada (41% → 3%) es el resultado obvio. El interesante resultado es que pasar de 4 reglas a 12 no añadió casi ninguna sobrecarga de cumplimiento (78% → 76%) a la vez que redujo la tasa de error otros 8 puntos. Las nuevas reglas cubren modos de fallo que las 4 originales no contemplaban — no compiten por el mismo presupuesto de atención.

Este es el argumento empírico para ir más allá de las 4 reglas. Si añadir reglas afectara el cumplimiento de forma proporcional, te detendrías en 4. Pero no es así.

6. Dónde la plantilla original se rompe silenciosamente

Cuatro escenarios donde las 4 de Karpathy no son suficientes — incluso antes de añadir reglas. El artículo es explícito en que el original no está equivocado, sino que aborda el espacio de problemas de enero de 2026:

1. Tareas de agentes de larga duración. Las reglas se centran en el momento en que Claude escribe código. No dicen nada sobre pipelines de múltiples pasos. Sin regla de budget. Sin regla de checkpoint. Sin regla de fail-loud. Los pipelines se desvían.
2. Consistencia entre múltiples bases de código. "Match existing style" asume un solo estilo. En un monorepo con 12 servicios, Claude tiene que elegir qué estilo seguir. Las reglas originales no le dicen cómo. Elige al azar o hace un promedio.
3. Calidad de las pruebas. Goal-Driven Execution trata "tests pass" como un éxito. No dice que las pruebas deban ser significativas. El resultado son pruebas que no evalúan nada útil pero que le dan confianza a Claude.
4. Producción vs prototype. 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 scaffolding especulativo para definir un rumbo. "Simplicity First" se aplica en exceso en el código en etapas tempranas.

7. Lo que no funcionó (Los experimentos fallidos)

Posiblemente la sección más útil del artículo — no las reglas que pasaron el corte, sino los patrones que explícitamente no lo hicieron:

• Reglas recopiladas de redes sociales. La mayoría eran reformulaciones de las 4 de Karpathy con otras palabras, o reglas específicas de dominio ("always use Tailwind classes") que no se generalizan. Descartadas.
• Más de 14 reglas. Mnimiy probó hasta 18. El cumplimiento cayó del 76% al 52% después de las 14. El techo de 200 líneas que Anthropic documenta es real — al superarlo, Claude hace pattern-matching con "rules exist" sin leerlas realmente.
• Reglas que dependen de herramientas. "Always use eslint" falla silenciosamente cuando eslint no está instalado. Reemplazado con frases agnósticas a la capacidad: "match the codebase's enforced style."
• Ejemplos en lugar de reglas. Tres ejemplos consumen tanto contexto como ~10 reglas y Claude se sobreajusta a ellos. Las reglas son abstractas, los ejemplos son específicos. Usa reglas.
• Intensificadores vagos "Ten cuidado," "piensa bien," "enfócate de verdad." Cumplimiento ~30% porque nada de eso es comprobable. Reemplazado por imperativos concretos como "declara las suposiciones explícitamente."
• Prompts de identidad. Decirle a Claude que sea "senior" no funciona. Claude ya cree que es senior. La brecha de cumplimiento está entre pensar y hacer. Los imperativos la cierran; los prompts de identidad no.

8. El modelo mental

Si reduces el artículo a su frase fundamental, obtienes esto:

Esto lo replantea todo. La mayoría de los desarrolladores tratan CLAUDE.md como un archivo de preferencias personales — una lista de gustos y disgustos estilísticos que crece con el tiempo. El argumento del artículo es que un archivo de preferencias no es la forma correcta. La forma correcta es una lista de modos de fallo con los que realmente te has topado, con una regla por cada modo.

También explica por qué el artículo termina con una recomendación contraintuitiva:

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

No pegues las 12 solo porque alguien en X lo dijo. Léelas, quédate con las que coincidan con errores que hayas cometido y descarta el resto.

9. Mapeándolo a Antigravity (GEMINI.md / AGENTS.md)

El artículo se centra en Claude, pero la abstracción es portable. Antigravity lee reglas procedimentales de dos archivos con el mismo formato:

• GEMINI.md — el archivo de system prompt específico de Gemini. Consulta nuestra guía de GEMINI.md.
• AGENTS.md — el formato multi-herramienta (funciona con Claude Code, Cursor, Antigravity). Consulta nuestra Guía AGENTS.md.

Ambas son recomendaciones, no imposiciones; ambas tienen un tope de unas 200 líneas antes de que el cumplimiento decaiga, y ambas siguen la misma disciplina de "enunciar la regla, sin ejemplos, sin intensificadores vagos". Las 12 reglas se transfieren prácticamente sin cambios. Consideraciones específicas de Antigravity:

1. La Regla 6 (presupuestos de tokens) se vuelve crítica, no opcional. La cuota de Antigravity se consume más rápido que la de Claude Code. Combina la regla con nuestro playbook de reducción de tokens.
2. La Regla 10 (puntos de control) se asocia con el Agent Manager de Antigravity. Si una ejecución multi-agente falla en el paso 4, querrás poder detener al agente y reanudar desde un artefacto anterior, no desde cero.
3. La Regla 7 (exponer conflictos) ayuda con los cambios de modelo. Si cambias entre Gemini y Claude Opus a mitad de la sesión (como se explica en nuestro análisis de cambio de modelo), el nuevo modelo a menudo hereda contexto obsoleto del anterior e intenta reconciliar patrones incompatibles.
4. La Regla 12 (fallar visiblemente) es la más subestimada para Autopilot. Si ejecutas auto-accept, los fallos silenciosos se acumulan a través de múltiples ciclos de Cmd-Enter antes de que los notes. Obliga al agente a exponer cada paso omitido.

Misma plantilla, diferente runtime, misma lógica.

10. La plantilla completa de 12 reglas (lista para copiar y pegar)

Guarda esto como CLAUDE.md (o GEMINI.md o AGENTS.md) en la raíz de tu repositorio. El artículo original señala: mantén el tamaño total del archivo por debajo de las 200 líneas combinadas, incluyendo cualquier adición específica del proyecto a continuación; más allá de eso, la efectividad disminuye.

Ese es el archivo. Dos cosas que hacer con él:

1. Lee las 12 con honestidad. ¿Cuáles coinciden con errores que realmente has cometido este mes? Quédate con esos. Descarta el resto. Un archivo de 6 reglas ajustado a tus patrones de error es mejor que uno de 12 con reglas que nunca llegarás a activar.
2. Añade reglas específicas del proyecto a continuación. Stack-specific ("always use the Repository pattern"), test-runner ("run pnpm test:unit before reporting done"), error patterns. Keep the total under 200 lines.

11. FAQ