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

Cinco fases, de la intención al código verificado.

Índice

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

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

Si no sabes qué es el SDD conceptualmente, empieza con ¿Qué es el desarrollo basado en especificaciones? para obtener definiciones, comparaciones con TDD y BDD, y el argumento a favor de 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 puedes copiar en tu repositorio hoy mismo.

Flujo de trabajo de desarrollo basado en especificaciones: requisitos, diseño, tareas, implementación, validación

SDD es un flujo de trabajo, no un documento

El modo de fallo más común en el desarrollo basado en especificaciones es tratar la especificación como mera burocracia. Un equipo escribe un largo documento de requisitos, lo almacena en un wiki y luego programa desde la memoria y los hilos de chat. La especificación existe, pero no dirige nada. Ese es teatro de documentación, y es peor que no tener especificación porque crea una falsa confianza.

Un flujo de trabajo de 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 la 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, corriges el artefacto y vuelves a ejecutar desde ese punto, no después de que tres mil líneas de deriva se hayan incorporado a la rama principal.

flowchart LR A[Especificar] --> B[Planificar] B --> C[Tareas] C --> D[Implementar] D --> E[Validar] E -->|deriva detectada| A E -->|publicar| F[Hecho]

El flujo de trabajo es neutral con respecto a las herramientas. Puedes ejecutarlo con archivos markdown en Git, con GitHub Spec Kit, con una CLI más ligera centrada en cambios como OpenSpec, con planes de Cursor, con un paquete de habilidades impuesto como Superpowers, 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 en las herramientas.

Fase 1: Especificar los requisitos

La fase de especificación responde a qué problema estás resolviendo y cómo se ve “terminado”. Deliberadamente evita cómo construirlo. En el momento en que tu especificación de requisitos dice “usa conjuntos ordenados de Redis”, has dejado de especificar y has comenzado a diseñar en el documento equivocado. Mantén la implementación fuera de los requisitos. Pónla en el plan.

Enunciado del problema y usuarios

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

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

Los consumidores de la API en el nivel gratuito pueden enviar solicitudes ilimitadas, lo que causa picos de costos e impacto de vecinos ruidosos en los inquilinos de pago. Los operadores de la plataforma necesitan un límite ejecutable por clave sin intervención manual.

Objetivos, no objetivos y criterios de aceptación

Los objetivos describen resultados que entregarás. Los no objetivos describen trabajos adyacentes tentadores que explícitamente no harás. Juntos limitan la creatividad del agente, lo cual es esencial cuando las herramientas de IA de lo contrario “ayudativamente” expanden el alcance.

Sección	Ejemplo bueno	Ejemplo débil
Objetivo	Rechazar solicitudes que excedan el límite por clave con HTTP 429	Hacer la API más rápida
No objetivo	Paneles de facturación por inquilino	Mejorar todo el rendimiento de la API
Criterio de aceptación	Las solicitudes sin autenticación reciben 401 antes de que se ejecute la comprobación de tasa	El punto de conexión es seguro

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

Preguntas abiertas

Lista 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élvelas antes de escribir el plan de diseño, o pagarás por la ambigüedad en retrabajos de implementación.

Una plantilla mínima de requisitos:

## Problema
[Un párrafo: quién sufre, por qué y qué provoca 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 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

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

Modelo de datos, contratos de API y migraciones

Documenta los cambios de esquema, tablas o campos nuevos, requisitos de índice y reglas de compatibilidad hacia atrás. Para APIs HTTP, escribe el método, la ruta, la forma de solicitud, la forma de respuesta y los códigos de error. Para eventos, escribe los nombres de tema, los esquemas de carga útil y las semánticas de entrega. Incluye pasos de migración y notas de reversión cuando el modelo de datos cambia.

Seguridad, observabilidad y estrategia de pruebas

Las restricciones de seguridad pertenecen en el plan, no como ideas posteriores en la revisión de código. Anota 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 función funciona en producción.

La estrategia de pruebas se conecta con los criterios de aceptación. Identifica qué criterios necesitan pruebas unitarias, cuáles necesitan pruebas de integración y cuáles necesitan verificación manual. Si usas pruebas unitarias en Go o pruebas unitarias en Python, nombra los paquetes y archivos de prueba que esperas agregar. Un plan sin una estrategia de pruebas es un plan que se publicará con huecos que descubrirás en producción.

flowchart TB subgraph plan [Contenido del plan de diseño] R[Espec de requisitos] C[Constitución del proyecto / ADRs] R --> D[Decisiones de arquitectura] C --> D D --> M[Modelo de datos y migraciones] D --> A[Contratos de API] D --> S[Restricciones de seguridad] D --> T[Estrategia de pruebas] end

Fase 3: Descomponer las tareas de implementación

La fase de tareas descompone el plan en rebanadas lo suficientemente pequeñas para implementar, revisar y validar de forma independiente. Esto es lo que hace que el desarrollo asistido por agentes sea revisable. En lugar de un enorme diff, obtienes una secuencia de cambios enfocados que cada uno se mapea de vuelta a un requisito nominado.

Tamaño 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 dependencias explícitamente. Las tareas de migración se ejecutan antes que el código que lee el nuevo esquema. Los cambios en bibliotecas compartidas se ejecutan antes que los consumidores. Los cambios en middleware de autenticación se ejecutan antes que los puntos de conexión que dependen del nuevo comportamiento.

flowchart TD T1[Tarea 1: migración de esquema] --> T2[Tarea 2: capa de repositorio] T2 --> T3[Tarea 3: manejador HTTP] T2 --> T4[Tarea 4: instrumentación de métricas] T3 --> T5[Tarea 5: pruebas de integración] T4 --> T5

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 puede ser un comando de prueba, un ejemplo de curl o una comprobació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 exceder límite), AC-3 (encabezados de límite en 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, antes del manejador

Vigila 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. Elige una tarea, da al agente solo el contexto que necesita para esa tarea y detente cuando la validación pase. Los reinicios de contexto entre tareas son una característica, no un error. Previenen que suposiciones anteriores contaminen el trabajo posterior y mantienen los diffs revisables.

Aplicar restricciones del stack de especificaciones

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

Actualizar el plan cuando la realidad difiera

La implementación hará aflorar sorpresas. Una biblioteca no soporta el comportamiento asumido. Una migración toma más tiempo del esperado. Un caso de borde faltaba en los criterios de aceptación. Cuando eso sucede, actualiza la especificación antes de continuar. Corrige los requisitos o el plan, obtén una rápida revisión y luego reanuda la implementación contra el artefacto corregido. El código que se desvía silenciosamente de la especificación es cómo la deriva se vuelve permanente.

sequenceDiagram participant H como Revisor humano participant A como Agente de IA participant S como Artefactos de especificación H->>S: Aprobar tarea N A->>S: Leer tarea + plan + restricciones A->>A: Implementar tarea N A->>A: Ejecutar validación de tarea A->>H: Enviar diff para revisión H->>H: Revisar diff contra tarea alt deriva o sorpresa H->>S: Actualizar espec/plan H->>A: Re-ejecutar con contexto corregido else aprobado H->>S: Marcar tarea N como completa H->>A: Proceder a tarea N+1 end

Fase 5: Validar contra la especificación

La validación es donde el SDD gana su inversión. Sin ella, la especificación es un ejercicio de planificación. Con ella, la especificación es un contrato que puedes comprobar contra el código publicado.

Comprobaciones automatizadas

Ejecuta el conjunto completo de pruebas, lint y comprobaciones de tipos en CI. Conecta estos en tu pipeline usando patrones de la hoja de referencia de GitHub Actions si necesitas un punto de partida práctico. Las comprobaciones automatizadas detectan regresiones. No detectan funciones incorrectas construidas correctamente, por lo que la revisión de criterios de aceptación sigue importando.

Criterios de aceptación y revisión manual

Recorre cada criterio de aceptación de la especificación de requisitos. Marca cada uno como satisfecho, fallido o pospuesto con justificación. La revisión manual detecta problemas de UX, huecos de seguridad y comportamiento incorrecto que las pruebas perdieron 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 de arquitectura en el código coincidieron con las decisiones registradas? Los archivos inesperados en el diff son una señal: o el plan estaba incompleto o el agente se desvió. Ambos merecen atención antes del merge. 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, de modo que la deriva se detecta en cada PR en lugar de solo cuando alguien recuerda mirarlo.

Capa de validación	Detecta
Pruebas unitarias y de integración	Regresiones y lógica incorrecta dentro del alcance
Lint y comprobaciones de tipos	Problemas de estilo y errores de tipo
Recorrido de criterios de aceptación	Comportamiento incorrecto construido según especificación
Diferencia de especificación a código	Deriva arquitectónica y expansión de alcance

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

Los agentes de IA son aceleradores en cada fase, no sustitutos de la revisión. El patrón productivo es redactar, revisar, refinar y luego proceder. Pide a un agente que redacte la especificación de requisitos a partir de una descripción del problema, luego edita la intención hasta que los objetivos, no objetivos y criterios de aceptación sean correctos. Pide a un agente que redacte el plan de diseño a partir de los requisitos aprobados, luego revisa las decisiones de arquitectura antes de que exista código. Pide a una agente que implemente una rebanada de tarea a la vez, con tú aprobando cada diff antes de que comience la siguiente tarea.

flowchart LR subgraph human [Humano posee] H1[Intención y prioridades] H2[Aprobación de arquitectura] H3[Revisión de diff en puntos de control] H4[Aceptación final] end subgraph agent [Agente acelera] A1[Redactar requisitos] A2[Redactar plan de diseño] A3[Generar lista de tareas] A4[Implementar rebanadas de tarea] A5[Redactar pruebas] end H1 --> A1 --> H1 A1 --> A2 --> H2 H2 --> A3 --> A4 --> H3 H3 --> A4 A4 --> A5 --> H4

Los agentes son especialmente útiles para producir borradores iniciales y pruebas de plantilla. Los humanos son especialmente útiles para detectar objetivos incorrectos, arquitectura insegura y expansión sutil de alcance. El flujo de trabajo falla cuando se omite cualquier lado: cuando los agentes implementan sin especificaciones, o cuando los humanos escriben especificaciones sin nunca validarlas contra el código.

Este artículo de flujo de trabajo permanece 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 de agentes: pertenecen bajo el clúster de Herramientas de Desarrollo de IA. El pilar del proceso vive aquí bajo prácticas de documentación porque los artefactos importan más que el vendedor.

Errores comunes que matan el desarrollo basado en especificaciones

Especificaciones enormes antes de cualquier validación. Un documento de requisitos de treinta páginas escrito antes de un prototipo o una prueba de concepto es burocracia de cascada, no SDD. Escribe la especificación mínima que elimina la ambigüedad para la siguiente fase, luego valida las suposiciones temprano. No cada función necesita el bucle completo de cinco fases: Desarrollo Basado en 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ázalos con comportamiento medible. Si no puedes probarlo, no puedes implementarlo de forma confiable: especialmente con un agente de IA.

Falta de no objetivos. Sin no objetivos, los agentes expanden el alcance por defecto. Agregan capas de caché, refactorizan módulos vecinos e introducen dependencias que no pediste. Los no objetivos son cómo dices 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 fue construido, no lo que fue intentado. El plan debería nombrar qué criterios de aceptación se mapean a qué tipos de pruebas antes de que el primer archivo de producción cambie.

Saltar 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 deriva después de un merge grande es costoso.

Permitir que las tareas generadas exploten. Trata una lista de tareas generada por IA de cincuenta elementos como un borrador inicial, no como un horario. Fusiona elementos redundantes, divide los demasiado grandes y elimina tareas que no se mapean a un requisito.

Eliminar investigaciones rechazadas en lugar de registrar por qué. Cuando la revisión de la fase 2 concluye que una dirección no vale la pena construir, el reflejo es eliminar la especificación y pasar al siguiente. Eso borra el razonamiento, y la misma idea resurge el próximo trimestre, investigada desde cero por quien: humano o agente: la vuelva a encontrar. Registrar la rechazo con el mismo rigor que una decisión aceptada es barato en comparación; Propuestas Rechazadas de OpenSpec: Una Convención de Memoria de Decisiones trabaja una forma concreta de hacerlo, incluida la instrucción que hace que un agente busque decisiones anteriores antes de re-proponer.

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

Plantillas reutilizables

Copia estas en tu repositorio y adáptalas. Almacena las especificaciones junto con la rama de la función, revísalas en solicitudes de extracción y mantenlas en control de versión para que agentes y humanos lean la misma fuente.

Plantilla de requisitos

# Función: [nombre]

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

Plantilla de diseño

# Diseño: [nombre de la función]

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

Plantilla de lista de tareas

# Tareas: [nombre de la función]

## 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 función]

## 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 basado en 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 suposiciones que la fase anterior.

Empieza pequeño. Ejecuta el flujo de trabajo completo en una función de tamaño medio. Mantén los artefactos en markdown en el repositorio. Actualiza la especificación cuando la realidad diverja. Valida antes del merge. Cuando la cadena funciona, obtienes menos deriva, diffs revisables más pequeños y un registro duradero de la intención que sobrevive a los reinicios de sesión y las transferencias de equipo.

Cuando la cadena se convierte en burocracia, corta 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
Guía rápida de OpenSpec: Instalación, flujo de trabajo y errores comunes – una CLI más ligera y centrada en cambios que ejecuta este mismo bucle como explorar-proponer-aplicar-archivar
Propuestas Rechazadas de OpenSpec: Una Convención de Memoria de Decisiones – registrar una decisión rechazada de la fase 2 para que no sea re-investigada desde cero
Guía rápida de Superpowers: 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 Basado en Especificaciones – análisis de Kiro, Spec Kit y Tessl