Flujo de trabajo de desarrollo basado en especificaciones: de los requisitos al código

El Desarrollo Guiado por Especificaciones (SDD) funciona cuando la especificación es un flujo de trabajo, no un documento que se archiva después de la reunión inicial. El objetivo no es producir un gran documento de requisitos de producto.

El objetivo es avanzar a través de una secuencia de artefactos revisables que reducen la ambigüedad antes de que alguien, humano o 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 caso a favor de tratar la especificación como fuente de verdad. Este artículo en el 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.

SDD es un flujo de trabajo, no un documento

El modo de fallo 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 largo documento de requisitos, lo almacena en una wiki y luego codifica de memoria y a partir de hilos de chat. La especificación existe, pero no dirige nada. Eso es teatro documental y es peor que no tener especificación porque crea una confianza falsa.

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, se corrige el artefacto y se vuelve a ejecutar desde ese punto, no después de que tres mil líneas de desviación hayan aterrizado en main.

El flujo de trabajo es neutral con respecto a las herramientas. Puede ejecutarse con archivos markdown en Git, con GitHub Spec Kit, con planes de Cursor, con un paquete de habilidades impuesto como Superpowers, o con un editor de texto plano y un revisor disciplinado. Lo importante es la secuencia y las puertas de revisión, no la marca de las herramientas.

Fase 1: Especificar los requisitos

La fase de especificación responde a qué problema se está resolviendo y qué aspecto tiene el “hecho”. Deliberadamente evita cómo construirlo. En el momento en que su especificación de requisitos dice “use 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.

Declaración del problema y usuarios

Comience con un párrafo que declare el problema en lenguaje claro. Nombrar a los usuarios afectados y la situación que hace que el problema sea doloroso. Una buena declaración del problema permite a un revisor que no estuvo en la reunión de planificación decidir si una solución propuesta aborda realmente el dolor.

Ejemplo para una funcionalidad 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 vecinos ruidosos en 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 resultados que se entregarán. Los no objetivos describen trabajos adyacentes tentadores que se decidirá explícitamente no hacer. Juntos delimitan la creatividad del agente, lo cual es esencial cuando las herramientas de IA, de lo contrario, “útilmente” expanden el alcance.

Los criterios de aceptación deben ser lo suficientemente precisos como para que cada uno se mapee a al menos 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 implementarlo.

Preguntas abiertas

Enumere cada decisión que aún no está resuelta. Las preguntas poco claras no son una señal 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 en la reestructuración de 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 decisión 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 funcionalidad 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 previene 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 tema, los esquemas de carga útil y las semánticas de entrega. Incluya pasos de migración y notas de reversión cuando cambie el modelo de datos.

Seguridad, observabilidad y estrategia de pruebas

Las restricciones de seguridad pertenecen al plan, no como pensamientos posteriores 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, registros o trazas necesarias para confirmar que la funcionalidad funciona en producción.

La estrategia de pruebas se conecta de vuelta 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 usa 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 huecos que descubrirá en producción.

Fase 3: Desglosar tareas de implementación

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

Dimensionado de tareas y dependencias

Una buena tarea toca un conjunto acotado de archivos, se completa en una sesión de agente y termina con un paso de verificación. Las tareas deben declarar sus dependencias explícitamente. Las tareas de migración se ejecutan antes del código que lee el nuevo esquema. Los cambios en 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 enumerar los archivos que probablemente cambiarán, los criterios de aceptación que satisface y cómo validar la finalización. La validación puede ser un comando de prueba, un ejemplo de curl o una comprobación manual descrita en pasos que se pueden copiar y pegar. Cada tarea termina en un punto de control de revisión humana. El revisor confirma que la diferencia coincide con la descripción de la tarea antes de que comience la siguiente.

Una entrada mínima de tarea:

### 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 sobre límite), AC-3 (encabezados de límite en la respuesta)
**Validar:** `go test ./middleware/...` pasa; curl sobre 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, 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 funcionalidad de tamaño medio a menudo tiene 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. Las reinicializaciones de contexto entre tareas son una función, no un error. Evitan que las suposiciones anteriores contaminen el trabajo posterior y mantienen las diferencias revisables.

Aplicar restricciones de la pila de especificaciones

El agente de implementación 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 de mayor retorno de la inversión que la mayoría de los equipos omiten. Le dicen al agente qué no hacer: no refactorizar módulos no relacionados, no cambiar las firmas de la API pública fuera de esta funcionalidad, no introducir nuevas dependencias sin actualizar el plan.

Actualizar el plan cuando la realidad difiere

La implementación revelará sorpresas. Una biblioteca no soporta el comportamiento asumido. Una migración toma más tiempo del esperado. Un caso límite estaba ausente de los criterios de aceptación. Cuando eso sucede, 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 se gana su lugar. Sin ella, la especificación es un ejercicio de planificación. Con ella, la especificación es un contrato contra el que puede comprobarse el código lanzado.

Comprobaciones automatizadas

Ejecute la suite de pruebas completa, 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 funcionalidades incorrectas construidas correctamente, por lo que la revisión de 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 diferido con justificación. La revisión manual captura problemas de UX, huecos de seguridad y comportamiento incorrecto que las pruebas pasaron por alto porque las pruebas se escribieron para coincidir con una especificación defectuosa.

Diferencia de especificación a código

El paso final de validación compara la implementación con 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 la diferencia son una señal: o el plan estaba incompleto o el agente se desvió. Ambos merecen atención antes de la fusión. Mantener especificaciones, pruebas y código sincronizados en el desarrollo con IA convierte esta revisión de diferencia única en una tabla de trazabilidad repetible y un conjunto de comprobaciones de CI, de modo que la desviación se captura en cada PR y no solo cuando alguien se acuerda de mirar.

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

Los agentes de IA son aceleradores en cada fase, no reemplazos de la revisión. El patrón productivo es: redactar, revisar, refinar y luego proceder. Pida a un agente que redacte 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 estén correctos. Pida a un agente que redacte el plan de diseño a partir de los requisitos aprobados, luego revise las decisiones de arquitectura antes de que exista código. Pida a un agente que implemente una porción de tarea a la vez, con usted aprobando cada diferencia antes de que comience la siguiente tarea.

Los agentes son especialmente útiles para producir borradores iniciales y pruebas de calderería. Los humanos son especialmente útiles para capturar objetivos incorrectos, arquitectura insegura y expansión sutil de 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 con respecto a las herramientas a propósito. Las guías de ejecución específicas de herramientas: configuración del editor, comandos de barra diagonal, configuración del agente, pertenecen al clúster de Herramientas para Desarrolladores de IA. El pilar del proceso vive aquí bajo 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 spike es papeleo de cascada, no SDD. Escriba la especificación mínima que elimina la ambigüedad para la siguiente fase, luego valide las suposiciones temprano. No cada funcionalidad necesita el bucle completo de cinco fases: Desarrollo Guiado por Especificaciones vs Vibe Coding explica cuándo una estructura más ligera es suficiente.

Criterios de aceptación vagos. Adjetivos como “rápido”, “limpio” y “fácil de usar” 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.

No objetivos ausentes. Sin no objetivos, los agentes expanden el alcance por defecto. Agregan capas de caché, refactorizan módulos vecinos e introducen dependencias que no solicitó. 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 cambie el primer archivo de producción.

Omitir 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 gran fusión es caro.

Dejar que las tareas generadas exploten. Trate una lista de tareas generada por IA de cincuenta elementos como un borrador inicial, no como un horario. Fusionar elementos redundantes, dividir los demasiado grandes y eliminar tareas que no se mapean a un requisito.

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

Plantillas reutilizables

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

Plantilla de requisitos

# Funcionalidad: [nombre]

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

Plantilla de diseño

# Diseño: [nombre de la funcionalidad]

## 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 funcionalidad]

## 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 funcionalidad]

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

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

## Especificación a código
- [ ] Los archivos cambiados coinciden con el plan
- [ ] No hay 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, tarea, 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 conjeturas que la fase anterior.

Comience pequeño. Ejecute el flujo de trabajo completo en una funcionalidad 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 funcione, obtendrá menos desviación, diferencias revisables más pequeñas y un registro duradero de la intención que sobrevive a las reinicializaciones de sesión y las transferencias de equipo.

Cuando la cadena se convierte en papeleo, recorte el alcance, no la revisión. Una especificación de dos páginas que fue validada gana 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 bucle similar de especificar-planificar-tareas-implementar
• Superpowers Quickstart: Instalación, Flujo de trabajo y Prueba – un paquete de habilidades instalable que automatiza este mismo bucle de cinco fases con puertas de revisión obligatorias
• Martin Fowler sobre herramientas de Desarrollo Guiado por Especificaciones – análisis de Kiro, Spec Kit y Tessl