Un agente de código termina una tarea. Los tests pasan, el build está en verde, el diff se ve limpio. Haces merge. ¿Cuántas veces hace ese código lo que pediste de verdad?
Dejé de suponerlo y lo medí. La respuesta es peor de lo que parece, y el arreglo es aburrido en el buen sentido.
El montaje
Cogí una app real de Next.js y TypeScript, la congelé en un commit y escribí cinco features pequeñas. Cada una es una petición de una línea más cinco criterios de aceptación. Le pasé la petición a cuatro agentes de código (Claude Sonnet, Claude Haiku, Codex y Kimi), corrí cada combinación tres veces, y puntué el resultado ejecutando el código, no leyendo el diff.
La puntuación la hace un gate aparte. Reaplica cada diff sobre una copia limpia del repo, ejecuta el código y comprueba cada criterio de aceptación. El agente nunca se corrige a sí mismo. Que el build esté en verde no cuenta para nada.
El build en verde nunca fue la vara
En algún momento dimos por bueno que “compila y los tests pasan” significa terminado. No es así. El agente escribió el código y, de la misma tirada, escribió los tests a su alrededor. Verde significa que el código está de acuerdo consigo mismo. No dice nada de si coincide con lo que querías.
Así que separé las dos cosas. El agente produce un diff. Un gate independiente decide si ese diff es correcto ejecutándolo contra los criterios. Trabajos distintos, dueños distintos.
Con solo la petición de una línea, el 40% de las ejecuciones colaron un fallo de corrección real. Build en verde, tests pasando, y aun así mal.
Qué cambia de verdad el desarrollo guiado por especificaciones
La idea es pequeña: escribe los criterios de aceptación antes de que el agente empiece, y verifícalos ejecutando cuando termina. Ya está.
Corrí cada tarea de dos formas. Mismo modelo, mismo repo, mismo esfuerzo. Una diferencia:
- Raw: la petición de una línea. Lo que escribe casi todo el mundo.
- Spec: esa misma petición más los cinco criterios de aceptación como checklist.
Agregando los cuatro modelos, en crudo coló un fallo real en el 40% de las ejecuciones. Con los criterios por delante, bajó a 0%. Los intervalos de confianza al 95% ni se solapan. Todos los modelos llegaron a cero fallos reales en cuanto supieron qué significaba “hecho”.
Dile al agente qué es correcto. Compruébalo ejecutando el código. Eso cierra el hueco.
El resultado que no esperaba
Daba por hecho que el modelo caro siempre ganaría. No fue así.
Haiku es un modelo barato. En crudo, sacó una feature totalmente correcta el 40% de las veces, más o menos lo mismo que Claude Sonnet. Dale a Haiku los criterios de aceptación y llega al 100%, a la altura del modelo puntero. El modelo barato con spec le ganó al puntero sin él.
Si estás pagando el modelo grande para tapar una petición vaga, igual estás comprando el upgrade equivocado. En este benchmark, la spec movió más la aguja que el modelo. Es la misma lección que hay detrás de la peligrosa ilusión de la productividad con IA: la velocidad es real, la palanca está en la estructura que la rodea.
Por qué no es una victoria amañada
La objeción justa: a la rama spec le di los mismos criterios que el gate comprueba después, así que claro que pasa.
Dos cosas lo mantienen honesto. El gate corre las mismas comprobaciones en las dos ramas, así que a la rama raw no se le exige una vara más baja. Y cada criterio está etiquetado antes de cualquier ejecución como genuine (cualquier versión competente debería cumplirlo) o contract (una elección de interfaz arbitraria que el agente no podía adivinar, como el nombre de un parámetro). El 40% cuenta solo fallos genuine. A la rama raw nunca se la castiga por no leerme la mente.
Son cinco features, un repo, un stack. Direccional, no una ley. Por eso justamente es público y no una captura.
Intenta romperlo
El repo tiene el protocolo (escrito antes de las ejecuciones, para que el análisis no se pueda ajustar al resultado), las features, los prompts, el gate de ejecución y los 120 diffs con sus veredictos. Puedes volver a puntuar cada ejecución sin pagar ni una llamada a un agente. Si encuentras por dónde se rompe el método, el hilo del foro está abierto y te respondo.
Dónde te deja esto
Escribir criterios de aceptación exactos para cada tarea, y poner un gate de ejecución en cada merge, es trabajo de verdad. La mayoría lo salta porque hacerlo a mano en cada tarea es tedioso. Esa parte tediosa es la que PaellaDoc automatiza: convierte tu intención en criterios y mete el gate de ejecución, para que lo guiado por especificaciones deje de ser una disciplina que tienes que recordar y pase a ser lo normal. El principio aguanta sin la herramienta, y por eso no hay ningún producto dentro del benchmark.