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

El desarrollo basado en especificaciones 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 mediante 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 sabes qué es el SDD conceptualmente, comienza con ¿Qué es el desarrollo basado en especificaciones? para definiciones, comparaciones con TDD y BDD, y el caso para tratar la especificación como fuente de verdad. Este artículo del cluster 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.

El 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 papeleo. Un equipo escribe un largo documento de requisitos, lo almacena en un wiki y luego codifica de memoria y a través de hilos de chat. La especificación existe, pero no impulsa nada. Ese es teatro de 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, corriges el artefacto y reinicias 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. Puedes 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 los puntos de control de revisión, no la marca de las herramientas.

Fase 1: Especificar los requisitos

La fase de especificación responde a qué problema estás resolviendo y qué significa “terminado”. Evita deliberadamente cómo construirlo. El momento en que tu especificación de requisitos dice “usar 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. Ponla en el plan.

Enunciado del problema y usuarios

Comienza con un párrafo que enuncie el problema en lenguaje sencillo. 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 problema.

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 “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 entregarás. Los no objetivos describen el trabajo adyacente tentador que explícitamente no harás. Juntos limitan la creatividad del agente, lo cual es esencial cuando las herramientas de IA de otro modo “ayudadoramente” expanden el alcance.

Los criterios de aceptación deben ser lo suficientemente precisos para que cada uno se corresponda con 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 puedes escribir un criterio concreto, el requisito es demasiado vago para implementarse.

Preguntas abiertas

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

Una plantilla de requisitos mínima:

## 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 de tu 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 finales inventados y formas de respuesta incorrectas.

Modelo de datos, contratos de API y migraciones

Documenta los cambios de esquema, nuevas tablas o campos, requisitos de índice y reglas de compatibilidad hacia atrás. Para APIs HTTP, escribe el método, la ruta, la forma de la solicitud, la forma de la respuesta y los códigos de error. Para eventos, escribe los nombres de los temas, los esquemas de carga útil y la semántica de entrega. Incluye 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. 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, los registros o las trazas necesarias para confirmar que la función funciona en producción.

La estrategia de pruebas conecta de vuelta con los criterios de aceptación. Identifica qué criterios necesitan pruebas unitarias, qué necesitan pruebas de integración y qué 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 enviará con lagunas que descubrirás 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 revisable el desarrollo asistido por agentes. En lugar de un diff enorme, obtienes una secuencia de cambios enfocados que cada uno se remonta a un requisito nombrado.

Dimensionamiento de tareas y dependencias

Una buena tarea toca 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 dependencias explícitamente. Las tareas de migración se ejecutan antes del código que lee el nuevo esquema. Los cambios en la biblioteca compartida 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 límite 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, 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 a menudo tiene cinco a quince elementos, no cincuenta.

Fase 4: Implementar una tarea a la vez

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

Aplicar restricciones desde 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 con el mayor retorno de 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 API públicas fuera de esta función, 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 extremo 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 revisión rápida 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 desviación se vuelve permanente.

Fase 5: Validar contra la especificación

La validación es donde el SDD demuestra su valor. Sin ello, la especificación es un ejercicio de planificación. Con ello, la especificación es un contrato contra el cual puedes comprobar el código enviado.

Comprobaciones automatizadas

Ejecuta el conjunto completo de pruebas, lint y comprobaciones de tipos en CI. Conéctalos a tu canalización usando patrones de la hoja de trucos de GitHub Actions si necesitas 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

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 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 el plan estaba incompleto o el agente se desvió. Ambos merecen atención antes de fusionar.

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. Pide a un agente que bosqueje 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 bosqueje 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 un agente que implemente un fragmento de tarea a la vez, con tu aprobación de cada diff antes de que comience la siguiente tarea.

Los agentes son especialmente útiles para producir primeros borradores y pruebas de código repetitivo. Los humanos son especialmente útiles para detectar objetivos incorrectos, arquitecturas inseguras y expansiones de alcance sutiles. 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 permanece neutral respecto a las herramientas a propósito. Las guías de ejecución específicas de herramientas: configuración de editor, comandos de barra oblicua, configuración de agentes, pertenecen al cluster 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 basado en especificaciones

Especificaciones enormes antes de cualquier validación. Un documento de requisitos de treinta páginas escrito antes de un prototipo o pico es papeleo cascada, no SDD. Escribe la especificación mínima que elimine la ambigüedad para la siguiente fase, luego valida las suposiciones temprano. No cada función necesita el ciclo completo de cinco fases: Desarrollo basado en especificaciones vs Coding de ambiente 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ázalos con comportamiento medible. Si no puedes probarlo, no puedes implementarlo de manera 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 solicitaste. Los no objetivos son cómo dices no con anticipación.

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.

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 desviación después de una fusión grande es costoso.

Dejar que las tareas generadas exploten. Trata una lista de tareas generada por IA de cincuenta elementos como un primer borrador, no como un horario. Fusiona elementos redundantes, divide los de tamaño excesivo y elimina las tareas que no se mapean a un requisito.

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

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 versiones para que los agentes y los 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 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 función]

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

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

Lista de comprobació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 --

## De 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 mediante 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 trabajo de suposición que la fase anterior.

Comienza 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 de fusionar. Cuando la cadena funciona, obtienes 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 papeleo, corta 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 basado en especificaciones – análisis de Kiro, Spec Kit y Tessl