Principios core de SDD

Especificaciones como lingua franca

En cualquier proyecto de software intervienen roles con perspectivas diferentes: product managers que definen requisitos de negocio, diseñadores que piensan en experiencias de usuario, desarrolladores que toman decisiones técnicas y stakeholders que evalúan resultados. Cada uno de estos roles utiliza su propio vocabulario y sus propias herramientas. Los requisitos se expresan en documentos de producto, los diseños en mockups, las decisiones técnicas en código y las evaluaciones en métricas. Esta fragmentación genera islas de contexto donde la información relevante queda atrapada en formatos que no todos los participantes pueden consumir.

SDD propone que la especificación actúe como lingua franca del proyecto: un formato compartido que todos los roles pueden leer, entender y contribuir. La especificación no está escrita en código (que excluye a los no técnicos) ni en prosa ambigua (que los agentes IA no pueden ejecutar). Está escrita en un formato estructurado pero legible que sirve tanto a humanos como a máquinas.

La especificación SDD es el punto de encuentro entre la intención humana y la ejecución automatizada: lo bastante precisa para que un agente IA genere código y lo bastante clara para que un product manager la revise.

Este principio tiene consecuencias prácticas inmediatas. Cuando un product manager revisa una especificación y detecta que falta un caso de uso, puede señalarlo directamente en el documento. Cuando un desarrollador identifica una restricción técnica que invalida un requisito, lo anota en la misma especificación. Cuando un agente IA implementa la funcionalidad, parte exactamente del mismo documento que todos han revisado. No hay traducciones intermedias, no hay interpretaciones divergentes.

Estructura sobre ambigüedad

Para que la especificación funcione como lingua franca, necesita una estructura predecible. Los documentos de texto libre tienden a la ambigüedad porque cada lector interpreta el contenido según su experiencia. Una especificación SDD resuelve esto mediante secciones estandarizadas:

• User stories: describen quién necesita qué funcionalidad y por qué, en un formato que conecta la funcionalidad con su valor de negocio.
• Criterios de aceptación: definen condiciones concretas y verificables que determinan si la funcionalidad está completa.
• Requisitos no funcionales (NFRs): capturan restricciones de rendimiento, seguridad, accesibilidad u otras cualidades que el sistema debe cumplir.
• Marcadores de ambigüedad: cuando un requisito no está suficientemente definido, se marca explícitamente (por ejemplo, con etiquetas como [NEEDS CLARIFICATION]) en lugar de dejarlo a la interpretación del implementador.

Este formato estructurado no impone rigidez. Las secciones pueden adaptarse al contexto del proyecto, pero la existencia de una estructura compartida garantiza que ningún requisito se pierda y que las ambigüedades se identifiquen antes de la implementación, no durante ella.

Refinamiento continuo

El segundo principio de SDD es que las especificaciones no se escriben una vez y se abandonan. Son artefactos vivos que se refinan a lo largo del ciclo de desarrollo. Este refinamiento sigue una progresión natural: de lo abstracto a lo concreto, de lo ambiguo a lo preciso.

flowchart TB
    V1["Especificación v1<br>Ideas iniciales"] --> R1["Revisión<br>Detectar ambigüedades"]
    R1 --> V2["Especificación v2<br>Clarificaciones"]
    V2 --> R2["Planificación<br>Decisiones técnicas"]
    R2 --> V3["Especificación v3<br>Refinada y validada"]
    V3 --> IM["Implementación"]
    IM -->|Descubrimientos| V4["Especificación v4<br>Actualizada"]

El refinamiento no es un proceso lineal forzado. Ocurre de forma orgánica a medida que el equipo profundiza en el problema. La primera versión de una especificación puede contener requisitos vagos como "el usuario debe poder personalizar sus notificaciones". Tras una ronda de clarificación, esta descripción se transforma en user stories concretas con criterios de aceptación medibles: canales disponibles, frecuencia de envío, condiciones de silencio, comportamiento por defecto.

Multi-step refinement

Los agentes IA actuales rinden mejor con refinamiento en múltiples pasos que con generación de un solo intento (one-shot). Este principio aplica tanto a la creación de especificaciones como a la implementación.

En lugar de pedir al agente que genere toda la especificación de una vez, SDD divide el proceso en pasos donde cada uno construye sobre el anterior:

• 1. Prompt inicial: el usuario describe la funcionalidad a alto nivel.
• 2. Generación de spec: el agente produce una primera versión estructurada con user stories y criterios de aceptación.
• 3. Clarificación: el usuario (o el propio agente) identifica ambigüedades y las resuelve de forma explícita.
• 4. Planificación técnica: a partir de la spec refinada, se generan decisiones de arquitectura y stack.
• 5. Desglose en tareas: el plan se descompone en unidades de trabajo concretas y verificables.

Cada paso produce un artefacto revisable antes de avanzar al siguiente. Si en el paso 4 se descubre que una decisión técnica invalida un requisito del paso 2, se retrocede, se actualiza la especificación y se regenera el plan. Esta mecánica de checkpoints intermedios evita el problema habitual del vibe coding, donde los errores de contexto se detectan demasiado tarde.

El refinamiento continuo transforma las especificaciones de documentos estáticos en artefactos que evolucionan con cada iteración del proyecto, acumulando las decisiones y clarificaciones de forma trazable.

Feedback bidireccional

El tercer principio establece que la información fluye en ambas direcciones entre la especificación y la implementación. No es un proceso lineal donde la spec se escribe, se entrega y se olvida. La implementación genera descubrimientos que retroalimentan la especificación.

Este feedback bidireccional se manifiesta en varias situaciones:

• Restricciones técnicas emergentes: durante la planificación técnica, el equipo descubre que un requisito no es viable con la arquitectura elegida. Esta restricción se refleja en la especificación como un NFR actualizado o como una modificación de la user story original.

• Edge cases no contemplados: al descomponer una funcionalidad en tareas, aparecen escenarios que la especificación original no cubría. Estos casos se añaden a la spec como criterios de aceptación adicionales.

• Validación contra la realidad: tras la implementación, las pruebas de usuario pueden revelar que un flujo que parecía lógico en la especificación no funciona en la práctica. La spec se actualiza para reflejar el aprendizaje.

flowchart TB
    SPEC["Especificación"] -->|Genera| PLAN["Plan técnico"]
    PLAN -->|Genera| TASKS["Tareas"]
    TASKS -->|Genera| CODE["Implementación"]
    CODE -->|Descubrimientos| SPEC
    PLAN -->|Restricciones| SPEC
    TASKS -->|Edge cases| SPEC

La diferencia con el desarrollo tradicional es que en SDD estos descubrimientos se registran formalmente en la especificación, no se pierden en conversaciones o se codifican implícitamente en el código. Cuando un requisito cambia, la especificación refleja tanto el requisito original como la razón del cambio. Este historial de decisiones es uno de los activos más valiosos del enfoque SDD, especialmente en equipos grandes o en proyectos de larga duración.

El coste de la unidireccionalidad

Cuando el feedback solo fluye en una dirección (de la especificación al código, sin retorno), se produce una divergencia silenciosa. El código evoluciona con parches, hotfixes y adaptaciones que nunca se reflejan en los documentos originales. Al cabo de unos meses, la especificación describe un sistema que ya no existe y se convierte en un documento inútil que nadie consulta.

SDD evita esta trampa al establecer que la especificación es el artefacto maestro del proyecto. Cualquier cambio significativo en la implementación debe reflejarse en la especificación. El coste de mantener esta sincronización es bajo porque los agentes IA pueden ayudar a actualizar la spec a partir de los cambios detectados en el código.

Exploración creativa

El cuarto principio de SDD desafía una limitación habitual del desarrollo de software: la necesidad de comprometerse con una implementación concreta antes de poder evaluarla.

En el desarrollo tradicional, explorar alternativas es caro. Probar si una funcionalidad rinde mejor implementada con una arquitectura de microservicios o con un monolito requiere construir ambas versiones, lo cual duplica el esfuerzo de especificación, diseño e implementación. En la práctica, la mayoría de equipos eligen una opción basándose en la experiencia previa y la intuición, sin datos empíricos.

SDD desacopla la especificación de la implementación, lo que habilita la exploración de múltiples implementaciones a partir de la misma especificación. La especificación define el "qué", el agente IA puede generar varias versiones del "cómo".

La exploración creativa permite generar múltiples implementaciones a partir de una misma especificación, comparar sus características y elegir con datos reales en lugar de suposiciones.

Implementaciones paralelas

La exploración creativa adopta formas prácticas en el trabajo diario:

• Comparación de stacks: una misma spec puede generar una implementación en FastAPI y otra en Express para comparar rendimiento, facilidad de mantenimiento o compatibilidad con la infraestructura existente.

• Variantes de UX: partiendo de la misma especificación funcional, se pueden generar interfaces con distintos frameworks de diseño o patrones de interacción, conectando con herramientas como Figma a través de MCP.

• Experimentación arquitectónica: se puede explorar si una funcionalidad se implementa mejor como módulo dentro del monolito existente o como un servicio independiente, con la misma spec como punto de partida.

Esta capacidad de generar alternativas sin multiplicar el esfuerzo de definición de requisitos es exclusiva de SDD. El equipo invierte una vez en definir qué construir y puede evaluar múltiples formas de construirlo, eligiendo con evidencia en lugar de con suposiciones.

El ciclo explorar-decidir-comprometer

La exploración creativa sigue un patrón estructurado:

• Explorar: generar dos o más implementaciones alternativas desde la misma especificación, variando el stack, la arquitectura o el diseño.
• Decidir: comparar las alternativas según criterios objetivos (rendimiento, complejidad, coste de mantenimiento, compatibilidad con el ecosistema existente).
• Comprometer: seleccionar la alternativa que mejor cumple los criterios, descartando las demás sin coste significativo.

Este ciclo reduce el riesgo de las decisiones técnicas irreversibles. Si una elección de arquitectura resulta equivocada tres meses después, el equipo puede volver a la especificación original, generar una nueva implementación con una arquitectura diferente y migrar de forma controlada. La especificación actúa como un punto de restauración que preserva la intención original del proyecto.