Título original: Las 4 reglas de CLAUDE de Karpathy reducen los errores de Claude del 41% al 11%. Después de 30 bases de código, añadí 8 más
Autor original: @Mnilax
Compilado: Peggy, BlockBeats

Prólogo: En enero de 2026, Andrej Karpathy criticó la forma en que Claude escribe código, lo que llevó a la creación de un archivo aparentemente pequeño pero extremadamente clave en el flujo de trabajo de programación con IA: CLAUDE.md. Forrest Chang luego organizó estos problemas en 4 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 unos meses después, el escenario de uso de Claude Code ya no era solo «hacer que el modelo escriba un fragmento de código». Con agentes de múltiples pasos, disparos en cadena con hooks, carga de habilidades y colaboración en múltiples repositorios, comenzaron a aparecer nuevos patrones de fallo: el modelo se descontrola en tareas largas, pasa las pruebas sin verificar la lógica real, omite silenciosamente errores tras migrar, y se mezclan estilos de código incorrectamente.

El autor de este artículo probó en 6 semanas con 30 repositorios, y añadió 8 reglas adicionales a las 4 originales de Karpathy, intentando cubrir los nuevos problemas que surgen en la colaboración de agentes tras la transición de la programación con IA de una sola completación a un entorno colaborativo.

A continuación, el texto original:

A finales de enero de 2026, Andrej Karpathy publicó una serie de tuits criticando la forma en que Claude escribe código. Señaló tres tipos de problemas típicos: hacer suposiciones incorrectas sin explicarlas, sobrecomplicar las cosas y causar daños irrelevantes en código que no debería modificarse.

Forrest Chang vio estos tuits y organizó las quejas en 4 reglas de comportamiento, las escribió en un archivo separado llamado CLAUDE.md, y lo subió a GitHub. Este proyecto alcanzó 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 un solo archivo de código de crecimiento más rápido en 2026.

Luego, en 6 semanas, probé esto con 30 repositorios.

Estas 4 reglas son efectivas. Los errores que ocurrían aproximadamente en un 40% de los casos, en tareas donde estas reglas son aplicables, bajaron a menos del 3%. Pero el problema es que este modelo fue inicialmente diseñado para resolver errores que ocurrían en enero, cuando Claude escribía código.

Para mayo de 2026, el ecosistema de Claude Code enfrentaba problemas diferentes: conflictos entre agentes, disparos en cadena con hooks, conflictos en carga de habilidades y interrupciones en flujos de trabajo multisesión.

Por eso, añadí otras 8 reglas. A continuación, la versión completa de 12 reglas en CLAUDE.md: por qué cada una vale la pena, y en qué cuatro lugares el modelo original de Karpathy puede fallar silenciosamente.

Si quieres saltarte las explicaciones y copiar directamente, el archivo completo está al final del documento.

Por qué esto es importante

CLAUDE.md en Claude Code es el archivo más subestimado en toda la pila tecnológica de programación con IA. La mayoría de los desarrolladores comete tres errores principales:

Primero, tratarlo como un buzón de preferencias, llenándolo con todos sus hábitos, lo que hace que se expanda a más de 4000 tokens y la tasa de cumplimiento de reglas caiga al 30%.

Segundo, simplemente no usarlo y pedir siempre desde cero. Esto genera un desperdicio de tokens cinco veces mayor y falta de coherencia entre sesiones.

Tercero, copiar un modelo y no modificarlo más. Puede funcionar dos semanas, pero a medida que cambian los repositorios, puede volverse obsoleto sin que te des cuenta.

La documentación oficial de Anthropic dice claramente: CLAUDE.md es solo una recomendación. Claude sigue aproximadamente el 80% de ella. Cuando supera las 200 líneas, la tasa de cumplimiento disminuye notablemente, porque las reglas importantes se pierden en el ruido.

El modelo de Karpathy resolvió esto: un archivo, 65 líneas, 4 reglas. Es el mínimo estándar.

Pero el límite puede ser aún mayor. Añadiendo estas 8 reglas, se cubren no solo los problemas de escritura de código que Karpathy criticó en enero de 2026, sino también los problemas de orquestación de agentes que surgieron en mayo de 2026 — problemas que no existían cuando se escribió el modelo original.

Las 4 reglas originales

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

Regla 1: Piensa antes de codificar.

No hagas suposiciones silenciosas. Explica tus hipótesis, revela los trade-offs. Pregunta antes de suponer. Cuando haya soluciones más simples, propón oposición activamente.

Regla 2: Prioriza la simplicidad.
Usa la menor cantidad de código que resuelva el problema. No añadas funciones imaginarias. No diseñes abstracciones para código de una sola vez. Si un ingeniero senior piensa que es demasiado complejo, simplifica.

Regla 3: Modificación quirúrgica.
Solo cambia lo imprescindible. No optimices código, comentarios o formato adyacente sin necesidad. No refactorices lo que no está roto. Mantén el estilo existente.

Regla 4: Enfócate en el objetivo.
Define el criterio de éxito primero, luego itera hasta verificarlo. No digas a Claude cómo hacerlo paso a paso, sino qué resultado debe lograr, y deja que itere por sí mismo.

Estas 4 reglas resuelven aproximadamente el 40% de los fallos en sesiones no supervisadas de Claude Code. El resto, un 60%, está en los espacios en blanco que siguen.

Las 8 reglas adicionales y por qué

Cada regla surge de una situación real: las 4 reglas originales de Karpathy ya no son suficientes. Primero describo esa situación, luego la regla correspondiente.

Regla 5: No hacer trabajo no verbal

Claude puede manejar: clasificación, redacción, resumen, extracción de información de texto no estructurado.
No debe manejar: enrutamiento, reintentos, manejo de códigos de estado, transformaciones deterministas.
Si un código de estado ya responde, deja que el código normal responda.

Las reglas de Karpathy no cubrían esto. Entonces, el modelo empezó a decidir sobre cosas que deberían ser decisiones determinísticas: si reintentar una API, cómo enrutear un mensaje, cuándo actualizar el proceso. El resultado: decisiones inconsistentes, con costos de 0.003 USD por token, en un if-else inestable.

Por ejemplo: un fragmento de código que llama a Claude para «decidir si reintentar ante un 503». Funcionó bien durante dos semanas, pero luego se volvió inestable porque el modelo empezó a incluir el cuerpo de la solicitud en el contexto de decisión. La estrategia de reintento se volvió aleatoria, porque el prompt también era aleatorio.

Regla 6: Establece un presupuesto rígido de tokens, sin excepciones

Presupuesto por tarea: 4,000 tokens.
Presupuesto por sesión: 30,000 tokens.
Si una tarea se acerca al límite, resume el estado actual y reinicia. No insistas. Expón claramente el límite superado, mejor que sobrepasarlo silenciosamente.

Un CLAUDE.md sin límites de tokens es como un cheque en blanco. Cada ciclo puede salirse de control, generando un contexto de 50,000 tokens. El modelo no se detiene solo.

Por ejemplo: una sesión de depuración de 90 minutos, en la que Claude repite iteraciones sobre un error de 8 KB, olvidando qué soluciones ya intentó. Al final, propone 40 soluciones que ya había rechazado. Con un límite de tokens, esa sesión se habría terminado en 12 minutos.

Regla 7: Revela conflictos, no hagas medias tintas

Si dos patrones en el código son contradictorios, no los mezcles.
Elige uno, preferiblemente el más reciente o probado, explica por qué, y marca el otro para limpiar después.
La «mezcla» de reglas en un código es la peor forma de código.

Cuando hay conflictos en el código, Claude intenta complacer a ambos lados, generando código incoherente.

Por ejemplo: en un repositorio con dos patrones de manejo de errores — async/await con try/catch y un manejador global — Claude genera código que combina ambos, haciendo que los errores se dupliquen y se oculten. Toma 30 minutos entender por qué los errores se estaban silenciando doblemente.

Regla 8: Lee antes de escribir

Antes de añadir código en un archivo, revisa qué exporta, quién lo llama, y qué funciones compartidas hay.
Si no entiendes por qué el código está organizado así, pregunta primero.
«No me parece relevante» es la frase más peligrosa en ese contexto.

El «modificar quirúrgicamente» de Karpathy no dice que no cambies código adyacente, sino que primero entiendas ese código. Sin esa comprensión, Claude puede generar funciones que entran en conflicto con las existentes.

Por ejemplo: Claude añade una función idéntica a una existente, sin leerla. Como resultado, sobrescribe la función antigua, que llevaba 6 meses como estándar, sin que nadie se diera cuenta.

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

Cada prueba debe explicar «por qué este comportamiento importa», no solo «qué hace».
Una prueba como expect(getUserName()).toBe(‘John’) no tiene valor si la función recibe un ID codificado.
Si no puedes crear una prueba que falle con cambios en la lógica, la función está mal.

«Enfócate en el objetivo» de Karpathy sugiere que las pruebas definen el éxito. Pero en la práctica, Claude a veces solo pasa las pruebas superficiales, sin verificar lógica clave.

Por ejemplo: Claude escribe 12 pruebas para una función de autenticación, todas pasan, pero la lógica en producción está rota. Las pruebas solo verifican que «devuelve algo», no que devuelve lo correcto. La función pasa porque devuelve un valor constante.

Regla 10: Operaciones de larga duración necesitan puntos de control

En tareas multisesión, después de cada paso, resume qué se hizo, qué se verificó y qué falta.
No sigas sin entender el estado actual.
Si te pierdes, detente y vuelve a describir el estado.

El modelo original de Karpathy asume interacción única. Pero en realidad, Claude realiza refactorizaciones en 20 archivos, construye funciones en una misma sesión, y depura en múltiples commits. Sin puntos de control, un error en un paso puede invalidar todo el progreso.

Por ejemplo: en una tarea de 6 pasos, en el cuarto paso Claude comete un error. Cuando me doy cuenta, ya ha avanzado en los pasos 5 y 6 en base a ese error. Revertir lleva más tiempo que rehacer. Con puntos de control, el error en el paso 4 sería detectado a tiempo.

Regla 11: La convención prima sobre la innovación

Si el repositorio usa snake_case, usa snake_case.
Si usa componentes basados en clases, usa componentes basados en clases.
La coherencia interna es más importante que las preferencias personales.
Si crees que una convención es dañina, proponla claramente. No crees bifurcaciones silenciosas.

En un repositorio con patrones establecidos, Claude tiende a introducir su propio estilo. Aunque funcione, puede romper la coherencia y requerir reescrituras.

Por ejemplo: en un código React basado en clases, Claude introduce hooks. Aunque funciona, rompe los tests existentes que dependen de componentDidMount. Tarda medio día en revertirlo y reescribirlo.

Regla 12: La falla explícita, no silenciosa

Si no estás seguro de que algo funcionó, dilo claramente.
Si omites 30 registros silenciosamente, no digas «migración completa».
Si omites alguna validación, no digas «funcionalidad lista».
Expón claramente la incertidumbre, no la ocultes.

Las fallas más caras de Claude son las que parecen éxitos. Una función que «funciona» pero devuelve datos incorrectos; una migración que «terminó» pero omitió el 14% de los registros con errores; una prueba que «pasa» pero solo porque la aserción es incorrecta.

Por ejemplo: Claude dice que una migración de base de datos «finalizó con éxito», pero en realidad omitió silenciosamente el 14% de los registros que violaban restricciones. La omisión aparece en logs, pero no se reporta explícitamente. Cuando los datos de los informes empiezan a fallar, descubrimos el problema 11 días después.

Resultados

En 6 semanas, rastreé 50 tareas representativas en 30 repositorios, probando 3 configuraciones diferentes.

El porcentaje de errores se refiere a cuántas tareas necesitan corrección o reescritura para alinearse con la intención original. Incluye errores silenciosos, sobreingeniería, daños irrelevantes, fallos silenciosos, violaciones de convenciones, conflictos de reglas y omisiones en puntos de control.

La tasa de cumplimiento indica la probabilidad de que Claude aplique explícitamente cada regla cuando corresponde.

Lo más interesante no es solo que el porcentaje de errores bajó del 41% al 3%. Lo más importante es que, al ampliar las reglas de 4 a 12, la carga de cumplimiento apenas cambió del 78% al 76%, pero el error disminuyó en 8 puntos porcentuales. Las reglas adicionales cubren fallos que las 4 reglas originales no abordaban, sin competir por el mismo presupuesto de atención.

Dónde puede fallar silenciosamente el modelo de Karpathy

Incluso sin añadir nuevas reglas, el modelo de las 4 reglas originales de Karpathy puede fallar en al menos 4 áreas.

Primero, tareas de agentes de larga duración.
Las reglas de Karpathy se enfocan en el momento en que Claude escribe código. Pero, ¿qué pasa cuando Claude ejecuta un pipeline de múltiples pasos? El modelo original no tiene reglas de presupuesto, puntos de control ni reglas para fallar claramente. La tubería puede desviarse lentamente.

Segundo, coherencia en múltiples repositorios.
«Coincidir con el estilo existente» asume un solo estilo. Pero en un monorepo con 12 servicios, Claude debe decidir qué estilo seguir. Las reglas originales no indican cómo elegir. Entonces, puede escoger aleatoriamente o mezclar estilos, generando incoherencias.

Tercero, calidad de las pruebas.
«Enfócate en el objetivo» considera que pasar pruebas es éxito, pero no especifica que las pruebas deben ser significativas. Como resultado, Claude puede generar pruebas superficiales que parecen correctas, pero no verifican lógica clave.

Cuarto, diferencias entre producción y prototipo.
Las 4 reglas pueden ralentizar el desarrollo de prototipos, que a veces requiere 100 líneas de código exploratorio. La regla de «priorizar la simplicidad» puede ser demasiado estricta en fases iniciales.

Estas 8 reglas adicionales no pretenden reemplazar las originales, sino complementarlas. La plantilla original se diseñó para escenarios de autocompletado en enero de 2026; en mayo, Claude Code funciona en entornos de múltiples pasos, agentes y colaboración en varios repositorios, enfrentando problemas diferentes.

Qué métodos no funcionaron

Antes de definir estas 12 reglas, probé otras soluciones.

Incluir reglas que vi en Reddit/X.
La mayoría solo repetían las 4 reglas originales con diferentes palabras, o eran reglas específicas de dominio, como «siempre usar Tailwind». Al final, las eliminé.

Más de 12 reglas.
Probé hasta 18. Más de 14, la tasa de cumplimiento cayó del 76% al 52%. El límite real es 200 líneas. Más allá, Claude empieza a hacer coincidencias de patrones en lugar de leer reglas.

Dependencia de herramientas específicas.
Por ejemplo, «siempre usar eslint». Si no está instalado, la regla falla silenciosamente. La convertí en «seguir el estilo ya impuesto en el código», sin depender de herramientas.

Mostrar ejemplos en CLAUDE.md en lugar de reglas.
Los ejemplos consumen mucho contexto, casi lo mismo que 10 reglas, y Claude puede sobreajustarse. Las reglas deben ser abstractas, los ejemplos específicos.

Frases como «Ten cuidado», «Piensa bien», «Concéntrate».
Son ruido. La tasa de cumplimiento cae al 30% porque no se pueden verificar. Mejor usar comandos concretos, como «explica claramente tus hipótesis».

Decirle a Claude que actúe como un «ingeniero senior».
No funciona. Claude ya se ve a sí mismo así. La diferencia está en cómo actúa, no en cómo se percibe. Las reglas imperativas ayudan, las indicaciones de identidad no.

Versión completa de las 12 reglas en CLAUDE.md

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

Por ahora, no puedo mostrar esto fuera de la documentación de Feishu.

Guárdalo en la raíz del repositorio como CLAUDE.md. Añade reglas específicas del proyecto debajo, como stack tecnológico, comandos de prueba, patrones de error. No excedas las 200 líneas, o la tasa de cumplimiento caerá.

Cómo instalar

Dos pasos:

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

2. Pega las reglas 5–12 de este artículo abajo

Guarda el archivo en la raíz del repositorio. El símbolo >> es importante: añade a lo que ya tienes, no lo sobreescribe.

Modelo mental

CLAUDE.md no es una lista de deseos, sino un contrato de comportamiento para bloquear fallos específicos observados.

Cada regla debe responder: ¿qué error previene?

Las 4 reglas de Karpathy previenen fallos vistos en enero de 2026: suposiciones silenciosas, sobreingeniería, daño irrelevante y criterios débiles de éxito. Son la base, no las ignores.

Las 8 reglas adicionales previenen nuevos fallos que surgieron después de mayo de 2026: ciclos de agentes sin límite, tareas multisesión sin puntos de control, pruebas superficiales que no verifican lógica clave, y errores silenciosos que parecen éxitos. Son parches incrementales.

Por supuesto, los efectos varían según el usuario. Si no haces pipelines de múltiples pasos, la regla 10 no es tan relevante. Si tu repositorio tiene un solo estilo y ya está enlintado, la regla 11 puede ser redundante. Después de leer las 12 reglas, conserva las que realmente previenen tus errores, y elimina las demás.

Una versión de 6 reglas, adaptada a fallos reales, vale más que una lista de 12 con la mitad inútil.

Conclusión

El tuit de enero de 2026 de Karpathy fue en realidad una queja. Forrest Chang lo convirtió en 4 reglas. Al final, 120,000 desarrolladores le dieron estrellas. La mayoría aún usa solo esas 4 reglas.

El modelo y el ecosistema han avanzado. Agentes de múltiples pasos, disparos en cadena, carga de habilidades, colaboración en varios repositorios — todo eso no existía cuando Karpathy escribió ese tuit. Las reglas originales no resolvieron estos problemas. No estaban mal, solo incompletas.

Las 8 reglas adicionales, en 6 semanas y con 30 repositorios, redujeron el error del 41% al 3%.

Guarda este artículo hoy, copia estas 12 reglas en tu CLAUDE.md. Si te ahorran una semana de errores, comparte.

[Enlace al original]

Haz clic para conocer las oportunidades en BlockBeats en reclutamiento

Únete a la comunidad oficial de BlockBeats en Telegram:
https://t.me/theblockbeats

Grupo de Telegram: https://t.me/BlockBeats_App

Cuenta oficial en Twitter: https://twitter.com/BlockBeatsAsia