Spec-Driven Development con IA: qué debe contener una spec

Llegué al desarrollo dirigido por especificaciones intentando resolver un problema concreto. Los agentes de IA generan código muy deprisa, pero empiezan a fallar cuando tienen que decidir por su cuenta qué se quiere construir, con qué reglas y cómo sabremos que el resultado es correcto.

Una spec útil deja por escrito el propósito, el alcance, los actores, las reglas, los estados, las integraciones, los casos límite y las pruebas que demuestran el comportamiento. Reduce lo que el agente tiene que suponer y hace visible una omisión antes de que se propague al diseño, al código y a las pruebas. No descubre decisiones que nadie ha tomado ni sustituye la arquitectura.

Si una decisión cambia el comportamiento, debe poder localizarse en la spec y en la prueba que la protege.

Cuando esa definición no existe, el desarrollo degenera en una sucesión de instrucciones sueltas:

«Crea un sistema de certificados». «Ahora añade autenticación». «Que el certificado lo firme un emisor externo». «Añade una página pública de verificación». «No emitas dos veces al mismo alumno».

Cada petición produce un cambio que parece correcto. Después de varias iteraciones, las reglas, las decisiones y las restricciones han quedado repartidas entre la conversación y el código. Reconstruir qué se quería construir, por qué y bajo qué reglas cuesta entonces más que haberlo definido al principio. Los prompts siguen haciendo falta; lo que no pueden ser es la única memoria del proyecto.

Qué cambia cuando la especificación dirige el trabajo

Spec-Driven Development, o desarrollo dirigido por especificaciones, trabaja con un documento persistente como referencia del comportamiento. Primero se define qué debe hacer el sistema, bajo qué condiciones y cómo se comprobará. Después, personas y agentes producen o validan el diseño, las tareas, el código y las pruebas contra esa referencia.

Un artefacto es cualquier documento persistente y revisable que forma parte de ese recorrido. Puede vivir en el repositorio o en un sistema documental. Yo prefiero versionarlo junto al código y revisarlo en el mismo flujo. Cuando la documentación se revisa aparte, la divergencia tarda menos en aparecer y más en descubrirse.

Un criterio de aceptación es la evidencia observable que decide si un comportamiento es correcto. El formato Dado / cuando / entonces ayuda a expresarlo, pero no lo convierte por sí solo en una prueba ejecutable. Todavía hacen falta los datos, el entorno y el código que conecte el escenario con el sistema.

La relación entre los artefactos es la diferencia importante. Una regla de la spec debe poder localizarse en el diseño que la resuelve, en la tarea que la implementa y en la prueba que la protege. Lo que se aprende al implementar vuelve al documento. Si el cálculo de una política de cancelación descubre un cambio de hora, el hallazgo corrige la regla; no se queda escondido en un comentario del código.

Especificar antes de implementar no es nuevo. Lo nuevo es que el documento también sirve como contexto operativo para un agente capaz de producir varios artefactos en minutos. Esa velocidad amplifica tanto una regla clara como una ambigüedad. De ahí la asimetría: un caso ya escrito resulta más difícil de perder, pero el que nadie identificó sigue sin existir.

Quién mantiene la spec es una decisión organizativa. Si la escribe una persona que no participa en la implementación y el equipo la recibe como una orden cerrada, el proceso recupera los problemas que pretendía evitar. Producto, arquitectura y desarrollo tienen que corregirla cuando el trabajo revela algo nuevo.

¿No es esto una historia de usuario con criterios de aceptación?

Es la primera objeción de quien lleva años trabajando con métodos ágiles, y en parte lleva razón. SDD no inventa las historias de usuario, ni los criterios de aceptación, ni la ingeniería de requisitos: usa material que los equipos de producto llevan décadas empleando. Lo que cambia es el nivel al que opera cada pieza y, sobre todo, el papel que desempeña después.

Una historia de usuario expresa una necesidad desde el punto de vista de alguien:

Como alumno, quiero recibir un certificado verificable al terminar el curso para acreditarlo ante un empleador.

Un criterio de aceptación define un escenario observable que permite decidir si esa necesidad está satisfecha. Ninguno de los dos dice qué ocurre cuando dos procesos cierran el mismo expediente a la vez. Ni cómo se calcula la caducidad si por medio hay un cambio de hora. Ni qué pasa cuando el emisor no responde, ni qué se conserva para auditoría.

La spec reúne todo eso y otros elementos, desde el propósito hasta las decisiones tomadas con su justificación; el inventario completo está más abajo. Una sola spec puede contener varias historias y muchos criterios relacionados entre sí.

La historia explica una necesidad. El criterio define cómo comprobar un comportamiento. La spec establece el contrato dentro del cual se construye la funcionalidad, y ese contrato dirige el resto del proceso: el diseño, las tareas, el código y las pruebas se generan o se validan contra él. Cuando cambia una regla no se añade otro comentario al ticket, sino que se actualiza la fuente compartida y se miran sus consecuencias. Una historia suele perder centralidad en cuanto se entrega; una spec anclada al producto conserva su autoridad mientras exista la funcionalidad.

Conviene reconocer el límite de la distinción. Una historia de usuario suficientemente completa, con sus reglas, escenarios, restricciones y decisiones, funciona en la práctica como una spec. Lo que separa a una de otra no es si el fichero se llama story.md o spec.md, sino su cobertura, su persistencia, su autoridad y su trazabilidad. Sospecho que muchos equipos ágiles ya practican una forma parcial de SDD sin llamarlo así. La novedad no consiste en volver a escribir requisitos. Consiste en convertirlos en contexto operativo, persistente y verificable para personas y agentes.

El contenido mínimo de una spec útil

El contenido exacto depende del proyecto, pero hay un núcleo que se repite:

Los dos últimos bloques son los que veo faltar con más frecuencia, y los que más se echan de menos cuando alguien vuelve al documento meses después. Registrar la duda evita que una respuesta inventada llegue al código como si ya se hubiera decidido.

Para decidir cuánto detalle necesita la spec, conviene medir señales que dejen rastro. Contaría las preguntas de clarificación que resuelve sin abrir otro hilo y los cambios de alcance detectados antes de implementar. Añadiría los retrabajos cuya causa apunta a un bloque ausente. Cuando mantenerla al día cuesta más que las omisiones que evita, el documento se recorta.

La spec conserva autoridad cuando guía los artefactos de ejecución y también incorpora lo que el trabajo obliga a decidir después.

Ver a tamaño originalCerrar

Un caso que obliga a recorrer todos los bloques

Supongamos una funcionalidad que emite credenciales verificables cuando un alumno termina un curso. El prompt inicial sería algo así:

«Crea un sistema que emita el certificado cuando el alumno apruebe el curso».

Un agente puede generar de inmediato una tabla, un endpoint y una plantilla de diploma, y para hacerlo tendrá que decidir por su cuenta una docena de cosas que nadie le ha dicho. Esta es la misma funcionalidad recorriendo los bloques de arriba; me salto los requisitos funcionales, que aquí no añaden nada inesperado.

Propósito. Que un alumno reciba una credencial comprobable por terceros en cuanto cumple los requisitos del curso, y que la institución pueda retirarla si después aparece un motivo.

Alcance. Entra la emisión, la revocación y la consulta pública de una credencial. Queda fuera el diseño del itinerario formativo, la pasarela de pago y la firma electrónica cualificada.

Actores.

Reglas de negocio.

• Un alumno recibe como máximo una credencial vigente por curso y convocatoria. Repetir el curso emite otra distinta; no sustituye a la anterior.
• La emisión exige que el alumno haya superado la nota mínima y completado la actividad obligatoria. Las dos condiciones se comprueban en el mismo instante, no en momentos distintos.
• Una credencial revocada deja de validar, conserva su identificador y expone el motivo de la revocación a quien la verifique.
• La caducidad se calcula sobre la fecha de emisión en el huso de la institución, no en el del alumno.
• Quedan auditadas la emisión, la revocación y cada consulta de verificación, con autor, instante y evidencia que la respalda.

Requisitos no funcionales. La consulta pública de verificación responde en menos de un segundo para el 95 % de las peticiones, medida durante una ventana y una carga acordadas; la emisión, que depende de un tercero, queda fuera de ese tiempo. La credencial contiene datos personales del alumno y se publica en una URL: la spec concreta qué campos aparecen, quién puede verlos y cuánto se conservan. La página de verificación aporta evidencia de conformidad con WCAG 2.2 AA.

Restricciones. El emisor de credenciales es un servicio externo que firma y aloja el certificado. La plataforma no guarda la clave de firma. El identificador de la credencial lo genera el emisor y la plataforma no puede inventarlo.

Integraciones. El emisor externo firma la credencial y envía un aviso —un webhook— cuando alguien la revoca desde su panel. La intención de emitir se registra de forma duradera en la misma transacción que cierra el expediente del alumno. Después, un proceso la ejecuta con una clave lógica estable construida a partir del alumno, el curso y la convocatoria. Los avisos entrantes se autentican, deduplican y toleran llegadas fuera de orden. Si una respuesta se pierde, la reconciliación consulta al emisor antes de reintentar.

Estados. El vocabulario distingue las tres acciones para que la interfaz, la API y la telemetría no usen «emitir» con significados distintos:

El invariante es «como máximo una credencial vigente por alumno, curso y convocatoria»; una revocada o caducada deja de contar. La operación externa distingue los estados pendiente, confirmada, fallo definitivo, resultado desconocido o requiere conciliación y revocada. El presupuesto de reintentos, el plazo visible, la alerta y el responsable se deciden antes de implementar. Agotar los reintentos no demuestra por sí solo que el emisor no haya firmado la credencial: si falta una prueba concluyente, el estado pasa a resultado desconocido y se deriva a revisión.

Casos límite. Aquí se comprueba el valor de la spec, porque son los escenarios que una instrucción inicial suele dejar fuera:

• El emisor responde con error al firmar la credencial.
• El emisor agota el tiempo de espera pero la credencial sí queda firmada.
• El responsable revoca directamente desde el panel del emisor.
• Dos procesos cierran el mismo expediente a la vez.
• El alumno pide el borrado de sus datos con una credencial vigente publicada.
• La caducidad cae en un cambio de horario, por lo que «un año después» debe definirse como fecha civil y no como una duración fija de horas.

Criterios de aceptación (uno de varios).

Dado un alumno que cumple los requisitos de un curso y una convocatoria, cuando se cierra su expediente, entonces se registra una única intención de emisión y ningún segundo cierre del mismo expediente produce una credencial adicional.

El criterio funcional describe el resultado observable. Debajo hace falta una garantía técnica que impida dos credenciales vigentes para la misma terna y que separe la persistencia local de los efectos externos. La spec conserva el invariante y el error visible. La elección entre unicidad, bloqueo o aislamiento serializable sigue siendo una decisión de arquitectura.

La integración necesita además una poscondición verificable: el sistema reconcilia el estado antes de reintentar y evita que una respuesta perdida produzca dos credenciales firmadas. El artículo sobre cómo verificar una automatización de IA desarrolla ese contrato.

Un segundo criterio cubre el límite más peligroso: si el proceso cae después de cerrar el expediente y antes de llamar al emisor, la intención duradera queda pendiente y se ejecuta después sin duplicar la credencial. Otro comprueba que dos avisos iguales de revocación producen un único cambio local. La trazabilidad puede ser tan pequeña como REG-04 → ADR-02 → T-07 → P-12: regla, decisión técnica, tarea y prueba quedan conectadas sin copiar el contenido cuatro veces.

Preguntas abiertas. ¿Una credencial revocada por error se restituye o se emite otra nueva? ¿La caducidad se define por curso o es una política común? ¿Qué se hace con las credenciales publicadas de un alumno que ejerce su derecho de supresión?

Una pregunta abierta escrita como tal vale más que una suposición disfrazada de requisito. Las anteriores bloquean las partes afectadas o quedan asignadas con fecha; no se esconden en una sección que nadie vuelve a leer.

Decisiones de dominio. La credencial se identifica por alumno, curso y convocatoria en lugar de por matrícula: sobrevive a un cambio administrativo que renumere las matrículas. El histórico se separa de la vigencia para que revocar no borre el rastro. El mecanismo de integridad que lo garantiza queda vinculado a un ADR y se revisará si aparecen credenciales compartidas entre varios cursos.

Grados de autoridad de la spec

Para decidir cuánta autoridad recibe el documento, propongo distinguir tres grados. No pretenden formar una taxonomía universal, sino ordenar una pregunta práctica: quién manda cuando la spec y el código no coinciden.

Spec-first. Se escribe antes de implementar, aporta claridad inicial y después puede dejar de mantenerse. Cuando spec y código discrepan, manda el código. Funciona en prototipos y funcionalidades aisladas, y es la puerta de entrada natural para un equipo que empieza, con el riesgo de que la spec caduque sin que nadie se entere.

Spec-anchored. Spec y código evolucionan juntos, y un cambio importante actualiza los dos. Cuando discrepan, se corrige la discrepancia, no se elige un ganador. Es el equilibrio realista para productos mantenidos a largo plazo y dominios con reglas complejas.

Spec-as-source. La especificación es la única fuente que editan las personas, y el resto se genera a partir de ella. Cuando discrepan, manda la spec y se regenera. Exige especificaciones rigurosas, generación controlada, validación exhaustiva y detección automática de divergencias. Pocos proyectos lo necesitan y, en sistemas heredados, cuesta saber por dónde empezar.

Dónde deja de ser suficiente

La primera limitación aparece antes de escribir. Una especificación precisa puede describir la funcionalidad equivocada. El documento conserva una decisión; no descubre por sí solo si alguien necesita el resultado.

También puede dar formato a un desacuerdo. He visto specs impecables sobre reglas de negocio que seguían sin estar acordadas. Parecían resueltas porque estaban bien escritas, pero producto y operaciones seguían esperando cosas distintas. Una pregunta abierta visible habría sido más útil que un requisito falso.

Después llega la deriva. Si el código cambia y la spec no, los dos cuentan historias distintas y el equipo termina fiándose de lo que se ejecuta. Las comprobaciones automáticas detectan parte de esa divergencia, pero no saben si la decisión correcta está en el código o en el documento. Atar pruebas a requisitos ayuda; la revisión sigue decidiendo qué versión representa el comportamiento deseado.

Una spec tampoco elige la arquitectura. Puede exigir que dos reservas no ocupen el mismo hueco, pero no decide qué garantía técnica encaja con el modelo, la carga y el motor de datos. El artículo sobre el límite entre la especificación y la arquitectura desarrolla esa distinción con el mismo caso.

Por último está el coste de mantenimiento. Cientos de documentos con reglas transversales pueden contradecirse. Los principios estables caben en una referencia común; el conocimiento de dominio cambiante necesita propietarios y relaciones explícitas. Ninguna estructura evita que el equipo tenga que mantenerlo.

La profundidad de la especificación debe ser proporcional al coste del error, a la incertidumbre y a la dificultad de dar marcha atrás, no al número de páginas. Una migración de datos y un prototipo visual no necesitan el mismo detalle ni la misma supervisión.

La medida correcta es cuánto deja de adivinar el equipo

No mediría la adopción por número de specs ni por páginas escritas. Mediría las decisiones implícitas que dejan de llegar a la implementación. Las señales útiles son preguntas de aclaración resueltas sin abrir otra conversación, cambios de alcance detectados antes de programar y retrabajos cuya causa apunta a un bloque que faltaba.

Empezaría por funcionalidades donde un error cruza varios artefactos o actores: integraciones, estados asíncronos, permisos, migraciones y reglas con muchas excepciones. Una mejora pequeña y reversible puede trabajar con una spec breve. Una operación difícil de deshacer necesita más precisión y una revisión más exigente.

Cuando el documento cuesta más de mantener que las omisiones que evita, se recorta. Si el equipo sigue resolviendo los mismos desacuerdos en tickets, revisiones y pruebas, falta información o autoridad. El objetivo consiste en reducir las decisiones que el agente y quien revisa tienen que reconstruir, no en producir documentación.

Una buena spec reduce fallos evitables porque conserva el problema, las reglas y la evidencia de éxito. Las decisiones de producto y arquitectura siguen correspondiendo al equipo. Esa separación permite aprovechar la velocidad del agente sin entregarle decisiones que la organización todavía no ha tomado.

Empezaría con un piloto pequeño: una funcionalidad con estados o integraciones, una persona propietaria de la spec, trazabilidad exigida desde cada regla hasta su prueba y una revisión al terminar. Ampliaría el piloto si disminuyen las aclaraciones y el retrabajo sin disparar el coste de mantener el documento; lo recortaría o abandonaría si la spec queda desactualizada y el equipo vuelve a reconstruir las decisiones desde el código.