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 reservas». «Ahora añade autenticación». «Intégralo con Zoom». «Que funcione también con Moodle». «No permitas cancelar en las últimas veinticuatro horas».

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 reservar una tutoría con mi profesor para resolver dudas de una asignatura.

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 alumnos solicitan el mismo hueco a la vez. Ni cómo se calculan las veinticuatro horas si por medio hay un cambio de hora. Ni qué pasa cuando Zoom no responde, ni qué se conserva para auditoría.

La spec reúne todo eso y bastante más, 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.

El límite de la distinción hay que reconocerlo. 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.

Un caso que obliga a recorrer todos los bloques

Es un caso construido a partir de problemas que he visto repetirse en integraciones con sistemas de gestión del aprendizaje (LMS), no un proyecto real. Supongamos una plataforma para reservar tutorías en línea. El prompt inicial sería algo así:

«Crea una aplicación para que los alumnos reserven tutorías con sus profesores».

Un agente puede generar de inmediato una interfaz, una API y varias tablas, 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 aportan sorpresa.

Propósito. Permitir que los alumnos reserven tutorías disponibles con sus profesores, y que ambas partes gestionen los cambios.

Alcance. Entra la reserva, la cancelación y la reprogramación de tutorías individuales. Queda fuera la facturación, las tutorías grupales y la videollamada propia: se usa Zoom.

Actores.

Reglas de negocio.

• La disponibilidad se define en huecos de treinta minutos sobre una rejilla fija. Dos reservas no pueden ocupar el mismo hueco del mismo profesor.
• El alumno no puede cancelar con menos de veinticuatro horas respecto al inicio de la tutoría, calculadas sobre el instante real y no sobre la hora de reloj local.
• El profesor sí puede cancelar en cualquier momento, y esa cancelación libera el hueco y notifica al alumno.
• Un profesor marcado como ausente deja de recibir reservas nuevas. Sus tutorías ya confirmadas se mantienen hasta que él las cancele.
• Quedan auditadas la creación, la cancelación y la reprogramación de cualquier reserva, con autor, instante y motivo.

Requisitos no funcionales. Las operaciones locales de solicitar y confirmar responden en menos de dos segundos para el 95 % de las peticiones, medido durante una ventana y una carga acordadas; la creación externa de la reunión queda fuera de ese tiempo. Los datos de alumnos son personales: la spec debe concretar minimización, acceso, retención y borrado, no limitarse a citar el RGPD. La interfaz debe aportar evidencia verificable de conformidad con WCAG 2.2 AA, el nivel de accesibilidad acordado.

Restricciones. El sistema se integra con un Moodle existente. Toma de allí matrículas y permisos, pero revalida la autorización en cada transición y define qué ocurre cuando una matrícula se revoca con una reserva activa. La videollamada es Zoom, impuesta por el cliente.

Integraciones. Zoom crea la reunión y envía un aviso automático —un webhook— cuando alguien la borra desde su interfaz. La intención de crearla se registra de forma duradera en la misma transacción que confirma la tutoría. Después, un proceso la ejecuta con una clave lógica estable. Los avisos entrantes se autentican, deduplican y toleran llegadas fuera de orden. Si una respuesta se pierde, la reconciliación consulta Zoom antes de reintentar. Moodle muestra el estado local de la actividad y el correo envía las notificaciones después de confirmar la transacción.

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

El invariante es «como máximo una ocupación activa por profesor y hueco»; una reserva rechazada o cancelada deja de ocuparlo. La operación externa distingue los estados pendiente, confirmada, fallo definitivo, resultado desconocido o requiere conciliación y cancelada. 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 Zoom no haya creado la reunión: si falta una prueba concluyente, el estado pasa a resultado desconocido y se escala.

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

• Zoom responde con error al crear la reunión.
• Zoom responde con un tiempo de espera agotado pero la reunión sí se ha creado.
• El profesor borra la reunión directamente desde Zoom.
• Dos alumnos solicitan el mismo hueco en el mismo instante.
• El alumno pierde el acceso al curso teniendo una tutoría reservada.
• La tutoría cae en el día del cambio de horario de verano en la zona del alumno, de modo que «veinticuatro horas antes» son veintitrés o veinticinco horas de reloj de pared.

Criterios de aceptación (uno de varios).

Dado un alumno autorizado y un hueco disponible, cuando solicita la reserva, entonces se crea una única solicitud activa, el hueco queda retenido y ningún otro alumno puede ocuparlo mientras esa solicitud siga vigente.

El criterio funcional describe el resultado observable. Debajo hace falta una garantía técnica que impida dos ocupaciones activas para el mismo hueco y que separe la persistencia local de los efectos externos. La spec debe conservar 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 postcondición verificable. Un tiempo de espera agotado no demuestra que la reunión no exista. El sistema debe poder reconciliar el estado antes de reintentar y evitar que una confirmación perdida produzca dos reuniones. 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 confirmar la tutoría y antes de llamar a Zoom, la intención duradera queda pendiente y se ejecuta después sin duplicar la reunión. Otro comprueba que dos avisos iguales de Zoom 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. ¿Cuántas cancelaciones seguidas puede acumular un alumno antes de que el sistema haga algo? ¿La disponibilidad del profesor es recurrente por semana o se define por fechas concretas? ¿Se conservan las reservas de un alumno dado de baja, o se anonimizan?

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. Rejilla fija de treinta minutos en lugar de intervalos libres: permite identificar el hueco de forma estable y cubre el caso habitual. La ocupación activa se separa del histórico para que rechazar o cancelar libere el hueco. El mecanismo de integridad que lo garantiza queda vinculado a un ADR y se revisará si aparecen tutorías de duración variable.

Tres 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 ver por dónde se empezaría.

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 satélite sobre la frontera entre spec y arquitectura desarrolla ese límite 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.

Última revisión: 27 de julio de 2026.

Alberto Lara Hernández trabaja en dirección técnica, arquitectura de software, inteligencia artificial aplicada y plataformas de aprendizaje.