Spec-driven development con IA: del prompt al endpoint verificable

Un prompt como "implementa el endpoint de checkout" produce código que compila. Puede que hasta funcione en el happy path. Pero sin una spec que defina qué inputs acepta, qué errores devuelve, qué estado previo requiere y qué side effects dispara, el modelo completa los huecos con suposiciones. Algunas son correctas; otras no.

El resultado es un endpoint que parece funcionar pero que falla en casos de borde que el desarrollador no anticipó porque no los especificó. El modelo no falla; hace lo que puede con la información que recibió. La responsabilidad de la spec es del desarrollador, no del modelo.

Una spec útil para IA tiene cuatro partes: el contrato de la API (método, ruta, body, respuestas posibles), las precondiciones (qué estado debe existir antes de que el endpoint funcione), los efectos esperados (qué cambia en la base de datos, qué eventos se disparan, qué emails se envían) y los casos de error explícitos (qué pasa si el recurso no existe, si el usuario no tiene permiso, si el payload está mal formado).

No hace falta que sea larga. Dos páginas de spec bien escritas producen mejor output que diez páginas de descripción narrativa. La precisión importa más que el volumen. Un ejemplo concreto del input y el output esperado vale más que tres párrafos describiendo el comportamiento en abstracto.

Una vez que el modelo genera el endpoint a partir de la spec, la verificación es directa: cada campo de la spec es un caso de test. Las precondiciones son setup del test. Los responses son assertions. Los side effects son verificaciones adicionales (que el evento se disparó, que el email se encoló, que el inventario se reservó).

Ese ciclo (spec → generación → test derivado de la spec) es más rápido que el ciclo tradicional porque el test no lo escribe el desarrollador desde cero; lo deriva de la misma spec que guió la implementación. El esfuerzo de la spec se amortiza en velocidad de verificación.

La spec-driven con IA no funciona bien cuando el espacio del problema no está claro. Si no se sabe qué debe hacer el endpoint, escribir una spec prematura cierra opciones antes de explorarlas. En ese caso, primero hay que explorar con el modelo (prototipo rápido, discusión de alternativas, validación de hipótesis) y luego escribir la spec cuando el enfoque está claro.

También falla cuando la spec describe la solución en lugar del comportamiento. "El endpoint debe llamar al servicio de Stripe y luego actualizar la base de datos" es una spec de implementación. "El endpoint debe marcar el pago como confirmado y notificar al cliente" es una spec de comportamiento. La segunda permite que el modelo elija la implementación; la primera la impone sin justificación.