Escribí el Libro de Contratos de Prompts. El Capítulo 4 Rompió Mi Propio Framework.

El contrato decía return a JSON array of contacts. No había puesto límite ni paginación. El código generado por IA pasó todas las pruebas. Luego un usuario generó un reporte de un segmento grande y el navegador murió bajo 5,000 contactos volcados de una vez.

El código estaba correcto. El contrato era el bug.

Publiqué un artículo sobre contratos de prompt. Se compartió tanto que convertirlo en libro tenía sentido. Y al escribirlo, surgieron tres cosas que un solo artículo no podía cubrir. El contrato que se rompe mientras el código es perfecto. La frontera entre código confiable y hechos confiables. Y el instinto que se atrofia cuando delegas demasiado tiempo.

5,000 Contactos, Cero Errores, Un Navegador Estrellado

Construí la cosa en un fin de semana. Herramienta pequeña para sincronizar contactos de distribuidores para una tienda WooCommerce, backend completo generado por IA desde un contrato de prompt. Modelo de datos, endpoints de API, validación, todo especificado por adelantado. Incluyendo esta línea: "return a JSON array of contacts matching the filter criteria."

Todos los criterios de aceptación pasaron. Desplegué un viernes por la tarde antes de llevar a los niños a hacer snorkel (porque aparentemente odio los fines de semana tranquilos).

Lunes. Un usuario con 5,000 contactos en su segmento de distribuidores presiona "Exportar." El navegador se pone blanco. La pestaña se cuelga. Sin error, sin degradación elegante. Solo una pestaña muerta y un blob JSON del tamaño de una novela corta sentado en memoria.

La IA no se desvió del contrato. Ni por una sola línea. Hizo exactamente lo que pedí, que es exactamente por qué se rompió.

El Capítulo 4 del libro se queda con esa pregunta: ¿rompió la IA el contrato, o escribí un contrato que especificaba el comportamiento equivocado?

Tres patrones de falla de contrato salieron de ese capítulo. Casos extremos faltantes: el contrato decía "return contacts" pero nunca dijo qué pasa cuando hay 5,000 (sin paginación, sin límite, la ausencia de una restricción es en sí misma una mala especificación). Suposiciones de dominio incorrectas: asumí que los contactos serían decenas, tal vez cientos, pero esa suposición vivía en mi cabeza, no en el documento. Y sobre-especificación de lo cosmético mientras los límites estructurales no estaban por ningún lado: había detallado el anidamiento JSON exacto, los nombres de campos, los tipos. ¿Pero payload máximo? ¿Fallback cuando es demasiado grande? Nada.

La solución no fue mejor prompting. Tres preguntas. Agregué tres preguntas al workflow:

Here is my contract for [feature].
Before generating any code:
- What edge cases am I not covering?
- What assumptions am I making that aren't written down?
- Where does this break at scale?

Tres preguntas. Eso es todo. La IA destroza tu spec antes de escribir una línea. Parcheas los huecos, luego generas.

Ese es el loop que documenta el libro. No prompt, generar, arreglar el código, re-prompt (el ciclo ingenuo que mantiene el spec congelado mientras parcheas síntomas). El ciclo real: especificar, generar, verificar, revisar EL SPEC. El spec es el documento vivo. El código es el output. Cuando el output se rompe, arreglas el input.

La primera versión de cualquier contrato es un borrador. Siempre. La prueba del presentimiento ayuda a decidir si necesitas un contrato (más sobre eso después). Pero una vez que decides que necesitas uno, asume que tiene huecos. El loop es el producto, no el documento.

El artículo decía: escribe un contrato. El libro tuvo que responder: ¿y cuando el contrato mismo es el bug?

Un contrato roto, lo puedes arreglar (parchear el spec, regenerar). El siguiente problema es más traicionero, porque el contrato no puede arreglarlo para nada.

El Framework Tiene una Frontera que el Artículo Nunca Dibujó

Los contratos de prompt producen código confiable. No producen hechos confiables.

Esa oración no está en ningún lado del artículo original. No podía estar. En un solo artículo muestras el framework funcionando, no vas mapeando dónde se detiene. Un libro no te deja salirte con la tuya.

Un webhook de Stripe o valida la firma o no. Un schema de base de datos o respeta el índice o no. Para lógica de código, el contrato elimina la alucinación. La IA genera lo que especificaste, las pruebas lo confirman, listo.

Pero mi herramienta de WooCommerce también genera reportes con datos reales de distribuidores. URLs de contactos, números de audiencia, nombres de socios. Cosas que existen en el mundo, no en el contrato. Y aquí el contrato bajó la alucinación de 30% a cerca de 15%. Bajó, no desapareció.

15% suena pequeño hasta que conoces a Karen de Contabilidad. Cada pipeline tiene una. Es la persona del otro lado a quien no le importa tu arquitectura limpia. A Karen le importa que la fila 47 del reporte trimestral liste un distribuidor que no existe. Puedes explicar que el código es técnicamente correcto. Karen te explicará que el cliente llamó, y que tu reporte técnicamente correcto hizo que la empresa se viera como amateur. Karen siempre gana estos argumentos. 🤷

El estudio METR encontró una brecha de 39-44% entre qué tan productivos piensan que son los desarrolladores con IA y qué tan productivos realmente son. Ox Security fue más lejos: 10 anti-patrones recurrentes en 80-100% del código generado por IA, lo que llamaron "un ejército de juniors talentosos sin supervisión." El contrato es la supervisión para código. Para hechos que la IA saca de sus datos de entrenamiento o inventa de la nada, el contrato no tiene jurisdicción.

Para productos donde el valor está en el código (la mayoría de SaaS), el framework es suficiente. Para productos donde el valor depende de hechos generados por la IA, necesitas una capa de verificación encima. El libro documenta ambos lados. El artículo solo tenía espacio para uno.

Y esta semana hace la frontera más visible. 1,234 skills de comunidad para Claude Code. Nueve categorías, desde deployment hasta testing hasta documentación. Cada una automatiza generación. ¿Cuántas automatizan verificación de outputs factuales? Scrolleé por las top 10. Cero.

1,234 skills para generar código. El que verifica hechos no existe todavía.

Lo que sigue no es ni técnico ni factual. Es personal, y fue el capítulo más difícil de escribir.

La Habilidad que me Enseñó el Libro que Ningún Slash Command Puede Reemplazar

Escribí este contrato hace tres meses para un import CSV de socios:

feature: partner-csv-import
acceptance_criteria:
  - Parse CSV with headers: name, url, category, audience_size
  - Validate each row: name non-empty, url valid format,
    audience_size integer > 0
  - Skip malformed rows, log them to stderr
  - Output clean JSON array to stdout
edge_cases:
  - Empty CSV → exit 0, empty array
  - CSV > 50,000 rows → stream processing, never load full file
  - Duplicate URLs → keep first occurrence, log duplicates

Y aquí está lo que generé la semana pasada para un script desechable para renombrar archivos de imagen:

rename all .png files in /uploads to kebab-case, lowercase

Sin contrato. Sin criterios de aceptación. Sin casos extremos. Una línea.

La diferencia es la prueba del presentimiento. El import CSV toca datos de socios que alimentan reportes de producción. Si el parser silenciosamente descarta filas o corrompe una URL, gente real toma decisiones reales con datos incorrectos. Se me encoge el estómago. Contrato. ¿El renombrado de imágenes? Si arruina un filename simplemente lo vuelvo a correr. Me encojo de hombros. Vibe code.

El artículo original tenía un pitch simple: escribe un contrato, deja que la IA codee. El libro tuvo que agregar la segunda parte incómoda: pero mantén tu instinto vivo.

Trabajé en un banco francés temprano en mi carrera. Tenían jobs batch de COBOL corriendo en producción por 25 años. Nadie los tocaba. Nadie necesitaba hacerlo. Todo el mise en place funcionaba tan bien que entender el sistema se volvió opcional. Hasta que un cambio regulatorio forzó una modificación, y los desarrolladores que entendían el sistema estaban jubilados. Idos. No porque alguien cometiera un error. Porque el sistema fue demasiado confiable por demasiado tiempo.

Luciano Nooijen le dijo a MIT Technology Review que sus instintos de programación se degradaron después de meses de uso intensivo de IA. Mismo mecanismo, solo comprimido de décadas a meses. Craig Weiss lo puso diferente esta semana (y la comunidad dev estuvo de acuerdo lo suficientemente fuerte como para notarlo): el verdadero moat es diseño de sistemas y pensamiento de producto, no sintaxis. La sintaxis se delega. El criterio no puede.

La parte graciosa (o aterradora, depende de qué día me preguntes).

Pasamos de leer cada línea de código a no leerlo para nada. Y el reemplazo para "verifiqué esto línea por línea" no es algún sistema de verificación automatizada superior. Ningún test suite atrapa todo. Corremos en un presentimiento ahora. Esa cosa va a explotar. Esa está bien. Esta, cuidado. Cambiamos code review por gut check. El workflow de desarrollo más avanzado de la historia corre en tu estómago. 🫠

La prueba del presentimiento lo convierte en un método en lugar de una adivinanza. Imagina el peor output posible para la tarea que estás a punto de delegar. Base de datos corrompida. Pago cobrado dos veces. Datos de usuario expuestos en los logs. Se encoge el estómago: contrato. Te encoges de hombros: vibe code libremente.

Construí el framework original de contratos de prompt después de suficientes desastres como el crash de 5,000 contactos. El artículo capturó la dirección. El libro mapea el terreno, callejones sin salida incluidos.

El artículo enseñó un framework. El libro me enseñó cuándo no usarlo.

Lo que el Artículo No Pudo Cubrir

Una lectura de 10 minutos prueba una dirección. "La especificación le gana a la improvisación." Esa parte está resuelta.

Pero una lectura de 10 minutos no te deja sentarte con los modos de falla. El contrato que es el bug. La frontera donde empiezan los hechos y se detiene el framework. La erosión lenta de tu propio criterio. Escribí el libro para profundizar en todo eso, para los devs que chocan con las mismas paredes y quieren más que una orientación de brújula.

El libro se llama Prompt Contracts: How I Stopped Vibe Coding and Started Shipping Real Software With AI. Está en Amazon ahora.

---

La industria va a apilar skills, capas, abstracciones. Esta semana son 1,234. El mes que viene serán 50,000. Cada nueva capa hace más cómodo nunca mirar qué está pasando debajo.

El libro no dice "para de apilar." Dice: conoce dónde están las grietas en los cimientos. El hombre sabio no construye su casa sobre arena. El contrato puede ser el bug. El contrato tiene una frontera. Y tu instinto tiene fecha de vencimiento si no lo usas.

Presentimiento + método. Shipealo.

---

Fuentes

Estudio METR sobre productividad de desarrollo asistido por IA (brecha de percepción 39-44%). Ox Security, "Top 10 AI Code Generation Risks" (anti-patrones en 80-100% del código de IA). MIT Technology Review, Luciano Nooijen sobre atrofia del instinto de programación.

Si construyes con IA y quieres la versión honesta (brechas incluidas, no solo el highlight reel), sígueme. El próximo llega a tu inbox.

(*) La portada es generada por IA. Las tres brechas en el artículo están certificadas orgánicas, errores humanos de granja a mesa.