De reglas a resultados: lo que 22.000 estrellas en un solo CLAUDE.md revelan sobre el desarrollo asistido por IA

El cuello de botella en la programación asistida por IA no es la capacidad del modelo. Es la calidad del contrato de comportamiento entre el humano y el LLM. Los equipos que codifican estos contratos en su cadena de herramientas obtienen rendimientos compuestos. Los que no lo hacen siguen reportando los mismos errores: "la IA alucinó otra vez".

La evidencia: forrestchang/andrej-karpathy-skills en GitHub. Un único archivo CLAUDE.md que destila las observaciones de Andrej Karpathy sobre los fallos comunes de los LLMs en la programación, convirtiéndolas en reglas accionables para Claude Code. 22.700 estrellas. 1.800 forks. Por un solo archivo.

Ese número de estrellas no refleja entusiasmo por la marca personal de Karpathy. Son 22.000 desarrolladores confirmando que comparten el mismo problema: los asistentes de programación con IA son potentes pero impredecibles, y un contrato de comportamiento bien escrito soluciona eso.

Los cuatro principios detrás de 22.000 estrellas

El repositorio codifica cuatro principios, cada uno dirigido a un modo de fallo específico en la programación asistida por LLMs:

• Pensar antes de programar. Exponer supuestos, presentar alternativas, preguntar antes de asumir. Apunta al modo de fallo en que los LLMs se lanzan a implementar sin entender el problema.

• La simplicidad primero. Código mínimo viable, sin funcionalidades especulativas ni abstracciones innecesarias. Apunta al modo de fallo en que los LLMs sobreingenierizan soluciones con complejidad innecesaria.

• Ejecución orientada a objetivos. Especificar criterios de éxito, no instrucciones paso a paso. Dejar que el LLM itere hasta cumplir los criterios. Apunta al modo de fallo en que las instrucciones imperativas producen código frágil y excesivamente literal.

• Comunicación explícita. Sin supuestos silenciosos. Cada decisión documentada. Apunta al modo de fallo en que los LLMs toman decisiones que parecen razonables pero violan restricciones no declaradas.

Ninguno de estos principios resulta sorprendente por sí solo. Lo que sí sorprende es que codificarlos en un único archivo marque la diferencia entre "la IA me hizo perder la tarde" y "la IA entregó la funcionalidad mientras yo revisaba".

CLAUDE.md no es una guía de estilo

La mayoría de los equipos tratan su CLAUDE.md (o el archivo de system prompt equivalente) como una guía de estilo de código: preferencias de formato, convenciones de nombres, quizás algunas notas específicas del proyecto. Eso pasa completamente por alto el punto.

Un CLAUDE.md es un contrato de comportamiento. Define cómo el agente de IA razona sobre los problemas, cuándo pide aclaraciones en lugar de hacer suposiciones, cómo delimita el trabajo y qué verifica antes de declararse listo. Las guías de estilo le dicen a la IA cómo debe verse el código. Los contratos de comportamiento le dicen a la IA cómo pensar.

El propio flujo de trabajo de programación asistida por IA de Karpathy refuerza esto. Su ciclo (cargar contexto, describir el cambio, elegir un enfoque, revisar, testear, hacer commit, repetir) trata a la IA como lo que él llama un "interno sabelotodo y entusiasta en exceso": conocimiento enciclopédico, criterio nulo. El contrato de comportamiento aporta el criterio que el modelo no tiene.

Este cambio de perspectiva tiene una consecuencia concreta. Cuando el agente de IA produce un resultado deficiente, la pregunta deja de ser "¿es el modelo suficientemente bueno?" y pasa a ser "¿es el contrato suficientemente específico?". Una pregunta lleva a esperar GPT-5. La otra lleva a un pull request que se puede entregar hoy.

Escalar los contratos de comportamiento a sistemas multiagente

Los principios de Karpathy fueron diseñados para un desarrollador que trabaja solo con un único asistente de IA. Pero el mismo patrón escala a la orquestación multiagente, donde agentes especializados coordinan tareas complejas.

Utilizamos oh-my-claudecode (OMC), una capa de orquestación multiagente de código abierto para Claude Code, para coordinar 19 subagentes especializados: arquitecto, ejecutor, revisor, auditor de seguridad, ingeniero de pruebas y más. Cada agente tiene su propio contrato de comportamiento que define sus patrones de razonamiento, los límites de su alcance y los requisitos de verificación.

La prueba de concepto: una integración de producto completa (~25.000 líneas de código en 252 archivos) generada íntegramente a partir de una especificación de producto a través del pipeline de agentes de OMC. Sin escritura manual de código. Los contratos de comportamiento definidos en el system prompt de cada agente fueron el único input redactado por humanos, más allá de la especificación en sí.

Ese resultado no se debe a que el modelo sea suficientemente inteligente. Claude ya era suficientemente inteligente. Se debe a que los contratos son suficientemente precisos como para que 19 agentes puedan coordinarse sin interferir entre sí.

Dónde reside realmente la ventaja competitiva

Si la infraestructura de IA se está convirtiendo en un commodity (y así es, con runtimes de agentes gestionados disponibles a 0,08 USD por hora de sesión), la pregunta se convierte en: ¿dónde reside la ventaja competitiva duradera?

Lo pensamos como una pila de cinco capas:

Los contratos de comportamiento se sitúan en la capa de orquestación. No es la capa con mayor ventaja competitiva, pero sí es la capa donde la mayoría de los equipos fracasa actualmente. Hacer bien la orquestación es lo que separa "experimentamos con programación por IA" de "la programación por IA es como entregamos".

Las reglas de ingeniería de producto orientada a agentes de PostHog confirman esto desde el lado del producto. Su quinta regla ("trata a los agentes como usuarios reales") es esencialmente el mismo hallazgo: la IA necesita restricciones explícitas, testadas y verificadas, no intuiciones.

Tres patrones que vale la pena adoptar

Si usted se lleva una sola cosa del repositorio karpathy-skills, que sean estos tres patrones para su propio equipo:

• Escriba criterios de éxito, no instrucciones. El principio de ejecución orientada a objetivos de Karpathy funciona porque los LLMs son mejores iterando hacia un objetivo medible que siguiendo pasos procedimentales. Defina cómo se ve "terminado". Deje que el agente encuentre el camino.

• Separe la autoría de la revisión. En sistemas multiagente, el agente que escribe el código nunca debe ser el que lo aprueba. En flujos de trabajo de agente único, lo mismo aplica para usted: revise el output de la IA con el mismo rigor que aplicaría al pull request de un desarrollador junior.

• Versione sus contratos como código. Su CLAUDE.md, los system prompts y las definiciones de agentes son artefactos de producción. Pertenecen al control de versiones, merecen revisión de código y deben evolucionar en función de los fallos observados. El propio repositorio karpathy-skills es la prueba: es un contrato de comportamiento versionado y revisado por la comunidad.

Las 22.000 estrellas no van dirigidas al consejo de programación de Karpathy. Van dirigidas a la idea de que la diferencia entre "una IA que le hace perder el tiempo" y "una IA que entrega sus funcionalidades" es un archivo bien escrito. En webvise, construimos sobre esa idea cada día. Si desea explorar lo que los contratos de comportamiento y la orquestación multiagente pueden hacer por su flujo de trabajo de desarrollo, contáctenos.