Flujo de trabajo de desarrollo orientado a especificaciones: de los requisitos al código

El desarrollo guiado por especificaciones (Spec-Driven Development) funciona cuando la especificación es un flujo de trabajo, no un documento que se archiva después del inicio. El objetivo no es producir un extenso documento de requisitos del producto.

El objetivo es avanzar a través de una secuencia de artefactos revisables que reduzcan la ambigüedad antes de que nadie, ya sea un humano o un agente de IA, modifique el código de producción.

Si no sabe qué es el SDD conceptualmente, comience con ¿Qué es el desarrollo guiado por especificaciones? para obtener definiciones, comparaciones con TDD y BDD, y el argumento para tratar la especificación como fuente de verdad. Este artículo del clúster de documentación de Arquitectura de Aplicaciones es la guía operativa. Recorre las cinco fases, muestra qué debe contener cada artefacto, explica dónde encajan los agentes de IA y proporciona plantillas reutilizables que puede copiar en su repositorio hoy mismo.

El SDD es un flujo de trabajo, no un documento

El modo de falla más común en el desarrollo guiado por especificaciones es tratar la especificación como un trámite burocrático. Un equipo escribe un extenso documento de requisitos, lo almacena en un wiki y luego codifica basándose en la memoria y en hilos de chat. La especificación existe, pero no impulsa nada. Eso es teatro de la documentación y es peor que no tener especificación porque crea una falsa confianza.

Un flujo de trabajo SDD funcional produce una cadena de artefactos, cada uno revisado antes de que comience la siguiente fase. Los requisitos reducen la ambigüedad del producto. El diseño reduce la ambigüedad técnica. Las tareas reducen la ambigüedad de ejecución. La implementación produce código contra un objetivo conocido. La validación demuestra que la cadena se mantuvo. Cuando cualquier fase revela un error, corrige el artefacto y vuelve a ejecutar desde ese punto, no después de que tres mil líneas de desviación hayan llegado a la rama principal.

El flujo de trabajo es neutral respecto a las herramientas. Puede ejecutarlo con archivos markdown en Git, con GitHub Spec Kit, con planes de Cursor o con un editor de texto plano y un revisor disciplinado. Lo que importa es la secuencia y las puertas de revisión, no la marca de la herramienta.

Fase 1: Especificar los requisitos

La fase de especificación responde qué problema se está resolviendo y cómo se ve el estado “terminado”. Evita deliberadamente cómo construirlo. En el momento en que su especificación de requisitos dice “usar conjuntos ordenados de Redis”, ha dejado de especificar y ha comenzado a diseñar en el documento equivocado. Mantenga la implementación fuera de los requisitos. Póngala en el plan.

Enunciado del problema y usuarios

Comience con un párrafo que declare el problema en lenguaje claro. Nombre a los usuarios afectados y la situación que hace que el problema sea doloroso. Un buen enunciado del problema permite que un revisor que no estuvo en la reunión de planificación decida si una solución propuesta realmente aborda el problema.

Ejemplo para una función de limitación de tasa de API:

Los consumidores de API en el nivel gratuito pueden enviar solicitudes ilimitadas, lo que provoca picos de costos e impacto de “vecino ruidoso” en los inquilinos de pago. Los operadores de la plataforma necesitan un límite aplicable por clave sin intervención manual.

Objetivos, no objetivos y criterios de aceptación

Los objetivos describen los resultados que se entregarán. Los no objetivos describen el trabajo adyacente tentador que explícitamente no se realizará. Juntos delimitan la creatividad del agente, lo cual es esencial cuando las herramientas de IA de lo contrario “ayudan” ampliando el alcance.

Los criterios de aceptación deben ser lo suficientemente precisos para que cada uno se mapee al menos a una prueba. “El punto final es seguro” no es un criterio de aceptación. “Las solicitudes no autenticadas reciben HTTP 401” sí lo es. Si no puede escribir un criterio concreto, el requisito sigue siendo demasiado vago para implementarse.

Preguntas abiertas

Enumere cada decisión que aún no está resuelta. Las preguntas poco claras no son un signo de fracaso. Son la fase de especificación haciendo su trabajo. Resuélvalas antes de escribir el plan de diseño, o pagará por la ambigüedad con retrabajos en la implementación.

Una plantilla mínima de requisitos:

## Problema
[Un párrafo: quién sufre, por qué y qué desencadena el dolor.]

## Usuarios
- [Rol de usuario principal]
- [Rol de usuario secundario]

## Objetivos
1. [Resultado medible]
2. [Resultado medible]

## No objetivos
- [Explícitamente fuera de alcance]
- [Explícitamente fuera de alcance]

## Criterios de aceptación
- [ ] [Comportamiento verificable]
- [ ] [Comportamiento verificable]

## Preguntas abiertas
- [ ] [Pregunta que bloquea la planificación]

Fase 2: Planificar el diseño

La fase de planificación traduce la intención en decisiones técnicas. Aquí es donde pertenecen los conjuntos ordenados de Redis, junto con los límites de los módulos, los cambios de esquema, los contratos de API, los pasos de migración, las restricciones de seguridad y la estrategia de pruebas. El plan se deriva de la especificación de requisitos más las restricciones existentes del proyecto: elecciones de stack, registros de decisiones y convenciones almacenadas en archivos como AGENTS.md o una constitución del proyecto.

Arquitectura y módulos afectados

Nombre los módulos, servicios o paquetes que cambiarán y resuma el patrón de integración. Si la función cruza un límite de servicio, documente el contrato en ambos lados. Los agentes alucinan APIs cuando los contratos son implícitos. Hacerlos explícitos en el plan evita puntos finales inventados y formas de respuesta incorrectas.

Modelo de datos, contratos de API y migraciones

Documente los cambios de esquema, nuevas tablas o campos, requisitos de índice y reglas de compatibilidad hacia atrás. Para APIs HTTP, escriba el método, la ruta, la forma de la solicitud, la forma de la respuesta y los códigos de error. Para eventos, escriba los nombres de los temas, los esquemas de carga útil y la semántica de entrega. Incluya pasos de migración y notas de rollback cuando el modelo de datos cambie.

Seguridad, observabilidad y estrategia de pruebas

Las restricciones de seguridad pertenecen al plan, no como reflexiones tardías en la revisión de código. Anote los requisitos de autenticación, las reglas de autorización, los límites de validación de entrada y los datos que no deben aparecer en los registros. La observabilidad debe cubrir las métricas, los registros o las trazas necesarias para confirmar que la función funciona en producción.

La estrategia de pruebas conecta con los criterios de aceptación. Identifique qué criterios necesitan pruebas unitarias, cuáles necesitan pruebas de integración y cuáles necesitan verificación manual. Si utiliza pruebas unitarias en Go o pruebas unitarias en Python, nombre los paquetes y archivos de prueba que espera agregar. Un plan sin una estrategia de pruebas es un plan que se lanzará con lagunas que descubrirá en producción.

Fase 3: Desglosar las tareas de implementación

La fase de tareas descompone el plan en fragmentos lo suficientemente pequeños para implementarse, revisarse y validarse de forma independiente. Esto es lo que hace que el desarrollo asistido por agentes sea revisable. En lugar de un solo diff enorme, obtiene una secuencia de cambios enfocados que cada uno se remonta a un requisito nombrado.

Dimensionamiento de tareas y dependencias

Una buena tarea afecta a un conjunto limitado de archivos, se completa en una sesión de agente y termina con un paso de validación. Las tareas deben declarar explícitamente las dependencias. Las tareas de migración se ejecutan antes del código que lee el nuevo esquema. Los cambios en las bibliotecas compartidas se ejecutan antes que los consumidores. Los cambios en el middleware de autenticación se ejecutan antes que los puntos finales que dependen del nuevo comportamiento.

Archivos, validación y puntos de control de revisión

Cada tarea debe listar los archivos que probablemente cambiarán, los criterios de aceptación que satisface y cómo validar la finalización. La validación podría ser un comando de prueba, un ejemplo de curl o una verificación manual descrita en pasos copiables. Cada tarea termina en un punto de control de revisión humana. El revisor confirma que el diff coincide con la descripción de la tarea antes de que comience la siguiente tarea.

Una entrada de tarea mínima:

### Tarea 3 -- Agregar middleware de limitación de tasa

**Depende de:** Tarea 1 (esquema), Tarea 2 (repositorio)
**Archivos:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Satisface:** AC-2 (429 por encima del límite), AC-3 (encabezados de límite en la respuesta)
**Validar:** `go test ./middleware/...` pasa; curl por encima del límite devuelve 429 con Retry-After
**Punto de control de revisión:** Confirmar que el middleware se ejecuta después de la autenticación y antes del controlador

Vigile las explosiones de tareas generadas. Los agentes de IA pueden producir planes de cincuenta tareas en segundos. La mayoría de esas tareas serán redundantes o demasiado granulares para revisarse eficientemente. Una lista de tareas útil para una función de tamaño medio suele tener de cinco a quince elementos, no cincuenta.

Fase 4: Implementar una tarea a la vez

La implementación es deliberadamente estrecha. Elija una tarea, dé al agente solo el contexto que necesita para esa tarea y deténgase cuando la validación pase. Los reinicios de contexto entre tareas son una característica, no un error. Evitan que los supuestos anteriores contaminen el trabajo posterior y mantienen los diffs revisables.

Aplicar restricciones desde la pila de especificaciones

El agente implementador debe leer la especificación de requisitos, el plan de diseño, la descripción de la tarea actual y las restricciones a nivel de proyecto. Las restricciones son la sección con mayor retorno de inversión que la mayoría de los equipos omiten. Le dicen al agente qué no hacer: no refactorice módulos no relacionados, no cambie las firmas de API públicas fuera de esta función, no introduzca nuevas dependencias sin actualizar el plan.

Actualizar el plan cuando la realidad difiera

La implementación hará surgir sorpresas. Una biblioteca no admite el comportamiento asumido. Una migración tarda más de lo esperado. Un caso límite faltaba en los criterios de aceptación. Cuando eso ocurra, actualice la especificación antes de continuar. Corrija los requisitos o el plan, obtenga una revisión rápida y luego reanude la implementación contra el artefacto corregido. El código que se desvía silenciosamente de la especificación es cómo la desviación se vuelve permanente.

Fase 5: Validar contra la especificación

La validación es donde el SDD justifica su existencia. Sin ella, la especificación es un ejercicio de planificación. Con ella, la especificación es un contrato que puede verificar contra el código lanzado.

Comprobaciones automatizadas

Ejecute la suite completa de pruebas, lint y comprobaciones de tipos en CI. Conecte estos a su pipeline usando patrones de la hoja de trucos de GitHub Actions si necesita un punto de partida práctico. Las comprobaciones automatizadas capturan regresiones. No capturan características incorrectas construidas correctamente, por lo que la revisión de los criterios de aceptación sigue siendo importante.

Criterios de aceptación y revisión manual

Recorra cada criterio de aceptación de la especificación de requisitos. Marque cada uno como satisfecho, fallido o pospuesto con justificación. La revisión manual captura problemas de UX, lagunas de seguridad y comportamientos incorrectos que las pruebas pasaron por alto porque las pruebas se escribieron para coincidir con una especificación defectuosa.

Diff de especificación a código

El paso final de validación compara la implementación contra el plan de diseño. ¿Los archivos que cambiaron coincidieron con los archivos que el plan predijo? ¿Las decisiones arquitectónicas en el código coincidieron con las decisiones registradas? Los archivos inesperados en el diff son una señal: o bien el plan estaba incompleto o el agente se desvió. Ambos merecen atención antes de fusionar. Mantener especificaciones, pruebas y código sincronizados en el desarrollo de IA convierte esta revisión de diff única en una tabla de trazabilidad repetible y un conjunto de comprobaciones de CI, por lo que la desviación se captura en cada PR en lugar de solo cuando alguien recuerda mirar.

Dónde encajan los agentes de IA en el flujo de trabajo

Los agentes de IA son aceleradores en cada fase, no reemplazos para la revisión. El patrón productivo es: bosquejar, revisar, refinar y luego proceder. Pida a un agente que bosqueje la especificación de requisitos a partir de una descripción del problema, luego edite la intención hasta que los objetivos, no objetivos y criterios de aceptación sean correctos. Pida a un agente que bosqueje el plan de diseño a partir de los requisitos aprobados, luego revise las decisiones de arquitectura antes de que exista cualquier código. Pida a un agente que implemente una porción de tarea a la vez, con usted aprobando cada diff antes de que comience la siguiente tarea.

Los agentes son especialmente útiles para producir borradores iniciales y pruebas de plantilla. Los humanos son especialmente útiles para detectar objetivos incorrectos, arquitecturas inseguras y una ampliación sutil del alcance. El flujo de trabajo falla cuando se omite cualquiera de los dos lados: cuando los agentes implementan sin especificaciones, o cuando los humanos escriben especificaciones sin validarlas nunca contra el código.

Este artículo de flujo de trabajo se mantiene neutral respecto a las herramientas a propósito. Las guías de ejecución específicas de herramientas: configuración del editor, comandos de barra inclinada, configuración del agente, pertenecen al clúster de Herramientas de desarrollo de IA. El pilar del proceso vive aquí bajo las prácticas de documentación porque los artefactos importan más que el proveedor.

Errores comunes que matan el desarrollo guiado por especificaciones

Especificaciones enormes antes de cualquier validación. Un documento de requisitos de treinta páginas escrito antes de un prototipo o picado es burocracia en cascada, no SDD. Escriba la especificación mínima que elimine la ambigüedad para la siguiente fase, luego valide los supuestos temprano. No cada función necesita el ciclo completo de cinco fases: Desarrollo guiado por especificaciones vs Codificación por vibes explica cuándo es suficiente una estructura más ligera.

Criterios de aceptación vagos. Adjetivos como “rápido”, “limpio” y “amigable para el usuario” no son criterios de aceptación. Reemplácelos con comportamiento medible. Si no puede probarlo, no puede implementarlo de manera confiable, especialmente con un agente de IA.

Falta de no objetivos. Sin no objetivos, los agentes amplían el alcance por defecto. Agregan capas de caché, refactorizan módulos vecinos e introducen dependencias que no pidió. Los no objetivos son cómo dice no de antemano.

Sin plan de pruebas en la fase de diseño. Las pruebas escritas solo después de la implementación tienden a confirmar lo que se construyó, no lo que se pretendía. El plan debe nombrar qué criterios de aceptación se mapean a qué tipos de pruebas antes de que cambien los primeros archivos de producción.

Saltarse la revisión en los límites de fase. La especificación revisada antes del plan. El plan revisado antes de las tareas. Las tareas revisadas antes de la implementación. Cada puerta es barata. Corregir la desviación después de una fusión grande es costoso.

Dejar que las tareas generadas exploten. Trate una lista de tareas generada por IA de cincuenta elementos como un borrador, no como un horario. Fusione elementos redundantes, divida los de tamaño excesivo y elimine las tareas que no se mapean a un requisito.

El SDD funciona cuando cada fase reduce la ambigüedad. Falla cuando crea burocracia.

Plantillas reutilizables

Copie estas en su repositorio y adáptelas. Almacene las especificaciones junto con la rama de características, revíselas en solicitudes de extracción y manténgalas bajo control de versiones para que los agentes y los humanos lean la misma fuente.

Plantilla de requisitos

# Característica -- [nombre]

## Problema
## Usuarios
## Objetivos
## No objetivos
## Criterios de aceptación
## Preguntas abiertas

Plantilla de diseño

# Diseño -- [nombre de la característica]

## Resumen
## Módulos afectados
## Cambios en el modelo de datos
## Contratos de API
## Migraciones
## Seguridad
## Observabilidad
## Estrategia de pruebas
## Riesgos y mitigaciones

Plantilla de lista de tareas

# Tareas -- [nombre de la característica]

## Tarea 1 -- [título]
Depende de:
Archivos:
Satisface:
Validar:
Punto de control de revisión:

## Tarea 2 -- [título]
...

Lista de verificación de validación

# Validación -- [nombre de la característica]

## Automatizado
- [ ] Todas las pruebas pasan
- [ ] Lint limpio
- [ ] Comprobación de tipos limpia

## Criterios de aceptación
- [ ] AC-1 --
- [ ] AC-2 --

## De especificación a código
- [ ] Los archivos cambiados coinciden con el plan
- [ ] Sin cambios arquitectónicos no documentados
- [ ] Especificación actualizada si la implementación difirió

Conclusión

El desarrollo guiado por especificaciones no se trata de escribir más documentos. Se trata de avanzar a través de especificar, planificar, tareas, implementar y validar con una puerta de revisión en cada paso. Cada fase debería dejar al siguiente actor, humano o agente, con menos trabajo de adivinanza que la fase anterior.

Comience pequeño. Ejecute el flujo de trabajo completo en una característica de tamaño medio. Mantenga los artefactos en markdown en el repositorio. Actualice la especificación cuando la realidad diverja. Valide antes de fusionar. Cuando la cadena funciona, obtiene menos desviación, diffs revisables más pequeños y un registro duradero de intención que sobrevive a los reinicios de sesión y las transferencias de equipo.

Cuando la cadena se convierte en burocracia, reduzca el alcance, no la revisión. Una especificación de dos páginas que fue validada supera a una especificación de treinta páginas que nadie leyó.

Enlaces útiles

• Documentación de GitHub Spec Kit – kit de herramientas de código abierto que implementa un ciclo similar de especificar-planificar-tareas-implementar
• Martin Fowler sobre herramientas de desarrollo guiado por especificaciones – análisis de Kiro, Spec Kit y Tessl