La programación asistida por IA falla cuando el contrato de comportamiento entre el humano y el LLM es vago. Los equipos que codifican estos contratos en su cadena de herramientas obtienen retornos acumulativos. Los que omiten este trabajo acaban registrando informes de errores repetidos sobre salidas alucinadas.
La evidencia: forrestchang/andrej-karpathy-skills en GitHub. Un único archivo CLAUDE.md que destila las observaciones de Andrej Karpathy sobre los fallos habituales de los LLMs en la programación en reglas accionables para Claude Code. 22.700 estrellas. 1.800 forks. Por un solo archivo.
Ese recuento de estrellas muestra que 22.000 desarrolladores comparten el mismo problema: los asistentes de programación con IA son potentes pero impredecibles, y un contrato de comportamiento bien redactado resuelve eso (los recuentos de estrellas miden visibilidad, no resultados verificados).
Los cuatro principios detrás de 22.000 estrellas
El repositorio codifica cuatro principios, cada uno orientado a un modo de fallo específico en la programación asistida por LLMs:
- Pensar antes de programar. Exponer supuestos, presentar alternativas y preguntar antes de asumir. Apunta al modo de fallo en que los LLMs comienzan la implementación sin entender el problema.
- Simplicidad ante todo. 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 cumplirlos. Apunta al modo de fallo en que las instrucciones imperativas producen código frágil y demasiado 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 sorprende 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 trata 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 por alto el punto central.
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 indican a la IA cómo debe verse el código. Los contratos de comportamiento le indican 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 genio hiperentusiasta": conocimiento enciclopédico, criterio nulo. El contrato de comportamiento aporta el criterio que le falta al modelo.
Este cambio de perspectiva tiene una consecuencia concreta. Cuando el agente de IA produce un resultado deficiente, la pregunta pasa de "¿es el modelo suficientemente bueno?" a "¿es el contrato suficientemente específico?". La primera lleva a esperar a GPT-5. La segunda 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. El mismo patrón escala, sin embargo, a la orquestación multiagente, donde agentes especializados coordinan tareas complejas.
Se utiliza 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.
| Dimensión | Contrato de agente único | Contrato multiagente |
|---|---|---|
| Alcance | Un desarrollador, un asistente | 19 agentes especializados con roles distintos |
| Verificación | El humano revisa el output de la IA | El agente revisor comprueba al ejecutor; el humano revisa el resultado final |
| Contexto | Todo el código en una sola ventana | Cada agente recibe únicamente el contexto relevante para su tarea |
| Modo de fallo | La IA sobrecomplejiza un archivo | Los agentes duplican trabajo o se contradicen entre sí |
| Foco del contrato | Cómo razonar sobre este código | Quién es responsable de cada decisión y cómo funcionan los traspasos |
La prueba de concepto: una integración de producto completa generada a partir de una especificación de producto a través del pipeline de agentes de OMC. La lección más importante fue el control de calidad, no el número de líneas. Los contratos de comportamiento definidos en el system prompt de cada agente fueron el principal input redactado por humanos, más allá de la especificación en sí.
Claude ya era suficientemente inteligente. Los contratos eran lo bastante precisos para que los 19 agentes coordinaran sin sobrescribir el trabajo de los demás.
Dónde reside realmente la ventaja competitiva
Si la infraestructura de IA se está convirtiendo en un bien de consumo (y así es, con runtimes de agentes gestionados disponibles a $0.08 por hora de sesión), la pregunta es: ¿dónde reside la ventaja competitiva duradera?
Cabe pensarlo como una pila de cinco capas:
| Capa | Función | Defensibilidad |
|---|---|---|
| Infraestructura | Hosting de modelos, aislamiento, persistencia | Baja. Commoditizada. Múltiples proveedores. |
| Orquestación | Coordinación multiagente, contratos de comportamiento | Media. Requiere conocimiento acumulado. |
| Reglas de diseño | Ingeniería de producto orientada a agentes | Media-alta. Requiere experiencia en el dominio. |
| Tesis de producto | Qué construir y para quién | Alta. Requiere visión de mercado. |
| Modelo de negocio | Cómo el trabajo genera ingresos | La más alta. Requiere relaciones con clientes. |
Los contratos de comportamiento se sitúan en la capa de orquestación: donde la mayoría de los equipos fracasa actualmente. Dominar la orquestación es lo que separa "experimentamos con la programación con IA" de "la programación con IA es cómo entregamos".
Las reglas de ingeniería de producto orientada a agentes de PostHog lo confirman desde el lado del producto. Su quinta regla ("trata a los agentes como usuarios reales") recoge esencialmente el mismo hallazgo: la IA necesita restricciones explícitas, testeadas y verificadas, no intuiciones.
Tres patrones que merece la pena adoptar
Si solo se extrae una idea del repositorio karpathy-skills, que sean estos tres patrones para el propio equipo:
- Escribir 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. Definir cómo se ve "terminado" y dejar que el agente encuentre el camino.
- Separar 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 al desarrollador: revisar el output de la IA con el mismo rigor que se aplicaría al pull request de un desarrollador júnior.
- Versionar los contratos como código. El 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 apuntan a la idea de que la diferencia entre herramientas de IA que generan ruido y herramientas de IA que entregan funcionalidades listas para producción suele reducirse a un archivo de contratos bien redactado. webvise trabaja cada día sobre esa base. Si desea explorar lo que los contratos de comportamiento y la orquestación multiagente pueden hacer por su flujo de trabajo de desarrollo, contacte con nosotros.
Las prácticas de webvise están alineadas con las normas ISO 27001 e ISO 42001.