📋 ¿Qué es Spec-Driven Development?

Spec-Driven Development (SDD), o Desarrollo Dirigido por Especificaciones, es un enfoque de desarrollo de software en el que las especificaciones detalladas de lo que debe hacer el sistema sirven como guía principal para diseñar, implementar y validar el código.

En el desarrollo de software acelerado, es común caer en la tentación de "empezar a codificar de inmediato". El frontend crea sus propios mocks, el backend construye la API según su criterio y el equipo de QA intenta adivinar cómo debería comportarse el sistema. El resultado inevitable son integraciones rotas, trabajo duplicado y refactorizaciones eternas.

Spec-Driven Development (SDD) propone una solución clara: la especificación del sistema (el "contrato") es la fuente única de verdad (Single Source of Truth) y debe escribirse y validarse antes de tirar una sola línea de código de producción.

👉 La idea central es:

Primero se define claramente qué debe hacer el software; después se desarrolla el código para cumplir esa especificación.

📋 ¿Qué es Spec-Driven Development?

SDD es un enfoque de diseño donde las especificaciones técnicas ejecutables y legibles (usando estándares como OpenAPI/Swagger para APIs REST, AsyncAPI para eventos o Protobuf para gRPC) guían todo el ciclo de vida del desarrollo.

A diferencia de la documentación tradicional que se escribe al final (y que nadie actualiza), en SDD la especificación es un artefacto vivo:

┌─────────────────────────┐
│  Diseño de la "Spec"    │ ── (OpenAPI / AsyncAPI / GraphQL Schema)
└────────────┬────────────┘
             │
             ├───────────────────────┬───────────────────────┐
             ▼                       ▼                       ▼
┌─────────────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐
│ Servidores Mock (Front) │ │ Código Stubs    │ │ Tests Automatizados     │
│ (Desarrollo Paralelo)   │ │ (Backend Auto)  │ │ (Contrato / QA)         │
└─────────────────────────┘ └─────────────────┘ └─────────────────────────┘

💡 Idea principal

En un desarrollo tradicional puede ocurrir:

Idea
  ↓
Código
  ↓
Pruebas
  ↓
Correcciones

Con Spec-Driven Development:

Requisitos
    ↓
Especificación
    ↓
Diseño
    ↓
Implementación
    ↓
Pruebas
    ↓
Validación

👉 La especificación funciona como un contrato técnico que permite comprobar si la implementación realmente cumple con lo solicitado.

🧠 ¿Qué es una Specification?

Una specification (especificación) describe de manera precisa el comportamiento esperado del software.

Puede definir:

• funcionalidades
• reglas de negocio
• entradas
• salidas
• restricciones
• casos límite
• criterios de aceptación
• comportamiento esperado ante errores

Por ejemplo:

Funcionalidad: Inicio de sesión

Dado un usuario registrado
Cuando introduce credenciales válidas
Entonces debe acceder al sistema.

👉 Esto permite transformar un requisito general en un comportamiento verificable.

⚙️ ¿Cómo funciona?

1️⃣ Definir el problema

Primero se determina qué necesita resolver el sistema.

Ejemplo:

El usuario necesita autenticarse
mediante correo electrónico y contraseña.

2️⃣ Crear la especificación

Se detalla exactamente cómo debe funcionar.

✓ Correo obligatorio
✓ Contraseña obligatoria
✓ Credenciales válidas → acceso
✓ Credenciales incorrectas → error
✓ Tres intentos fallidos → bloqueo temporal

3️⃣ Diseñar la solución

Se determina cómo se implementará:

Frontend
  ↓
API
  ↓
Authentication Service
  ↓
Base de datos

4️⃣ Implementar

El desarrollador escribe el código siguiendo la especificación.

👉 El código deja de ser el punto de partida y pasa a ser la implementación de un comportamiento previamente definido.

5️⃣ Validar

Se ejecutan pruebas para comprobar que el software cumple la especificación.

Especificación
      ↓
    Tests
      ↓
¿Cumple?
  ↙     ↘
Sí       No
↓        ↓
Deploy   Corregir

🤖 SDD y desarrollo con Inteligencia Artificial

El concepto se ha vuelto especialmente relevante con los agentes de programación basados en IA.

En lugar de decirle a una IA:

"Créame una aplicación de usuarios"

se puede proporcionar una especificación mucho más precisa:

Crear un sistema de usuarios que permita:

- Registrar usuarios
- Iniciar sesión
- Restablecer contraseña
- Validar correo electrónico
- Utilizar autenticación mediante tokens
- Proteger las rutas privadas

La IA puede utilizar esa especificación para:

Spec
  ↓
Plan
  ↓
Código
  ↓
Tests
  ↓
Validación

👉 Esto ayuda a reducir ambigüedades y proporciona un criterio claro para evaluar el resultado.

🔥 SDD vs desarrollo tradicional

🧩 Ejemplo práctico

Supongamos que queremos crear una API para productos.

❌ Requisito ambiguo

Crear una API de productos.

No especifica:

• qué datos necesita
• qué respuestas devuelve
• qué errores existen
• quién puede modificar productos

✅ Especificación

POST /products

Entrada:
{
  "name": "Arduino Uno",
  "price": 25
}

Reglas:
- name es obligatorio
- price debe ser mayor que 0

Respuesta exitosa:
HTTP 201

👉 Ahora el desarrollador puede implementar exactamente ese comportamiento.

🧪 La especificación como criterio de prueba

Una de las grandes ventajas del SDD es que la especificación puede convertirse en casos de prueba.

Por ejemplo:

SPEC
  │
  ├── Usuario válido → 201
  ├── Nombre vacío → 400
  ├── Precio = 0 → 400
  └── Precio negativo → 400

👉 Cada regla puede comprobarse automáticamente.

📦 ¿Qué puede contener una especificación?

Una especificación bien estructurada puede incluir:

🎯 Objetivo

Qué problema resuelve.

👤 Actores

Quién utilizará la funcionalidad.

📥 Entradas

Qué información recibe.

📤 Salidas

Qué información produce.

📐 Reglas

Condiciones que debe cumplir.

⚠️ Errores

Qué ocurre cuando algo falla.

🧪 Criterios de aceptación

Cómo determinar que está correctamente implementado.

🚀 Ventajas

🎯 Mayor claridad

Todos entienden qué debe hacer el sistema.

🤝 Mejor colaboración

Desarrolladores, diseñadores y responsables del negocio pueden trabajar sobre una referencia común.

🧪 Mejor calidad

Las especificaciones pueden utilizarse para definir pruebas.

🤖 Ideal para IA

Los agentes de programación reciben instrucciones estructuradas y verificables.

🔄 Facilita el mantenimiento

Cuando cambia un requisito, se puede actualizar primero la especificación y luego adaptar la implementación.

⚠️ Desventajas

📝 Requiere tiempo inicial

Crear buenas especificaciones puede requerir más trabajo al principio.

🔄 Mantenimiento

La especificación debe mantenerse sincronizada con el software.

🧠 Requiere precisión

Una especificación incompleta puede producir una implementación incorrecta.

⚠️ No elimina la necesidad de criterio humano

Una especificación puede ser técnicamente correcta y aun así resolver mal el problema del negocio.

🧩 Los Beneficios Clave del Enfoque SDD

⚡ Trabajo en Paralelo Real

Una vez acordada y congelada la especificación (por ejemplo, un archivo openapi.yaml), el equipo de Frontend y el de Backend pueden trabajar simultáneamente. El Frontend genera servidores mock automáticos basados en la especificación, mientras el Backend implementa la lógica real. Al final, la integración es transparente.

🤖 Generación Automática de Código y Documentación

A partir del archivo de especificación, herramientas como openapi-generator o Orval pueden generar automáticamente:

• Los clientes HTTP en TypeScript, Dart o Swift para el Frontend/Mobile.
• Las interfaces y modelos de datos de entrada/salida en Go, Java, Python o Node.js para el Backend.
• La documentación interactiva (Swagger UI / Redoc) sin esfuerzo manual.

🛡️ Pruebas de Contrato (Contract Testing)

Las especificaciones se convierten en suites de prueba automáticas. Si un desarrollador del backend modifica un campo o cambia el tipo de dato de una respuesta, las pruebas del pipeline de CI/CD fallarán inmediatamente al detectar que se ha violado el contrato establecido.

🔗 Relación con otras metodologías

SDD puede combinarse con diferentes prácticas:

Spec-Driven Development
        │
        ├── Agile
        ├── CI/CD
        ├── Testing
        ├── Git
        ├── API Design
        └── AI Coding Agents

También puede relacionarse con enfoques como:

• Test-Driven Development (TDD)
• Behavior-Driven Development (BDD)
• Contract-Driven Development

🆚 SDD vs TDD

Son conceptos relacionados, pero no iguales.

👉 Pueden utilizarse juntos:

Specification
    ↓
Tests
    ↓
Código
    ↓
Validación

🌐 ¿Dónde resulta especialmente útil?

SDD puede ser muy útil en:

• APIs
• sistemas empresariales
• microservicios
• aplicaciones complejas
• proyectos con equipos grandes
• desarrollo asistido por IA
• sistemas donde los requisitos deben ser verificables

🛠️ Herramientas y tecnologías relacionadas

Puede utilizarse junto con:

• GitHub
• OpenCode
• OpenAPI
• JSON Schema
• Markdown
• pruebas automatizadas
• CI/CD

Por ejemplo:

GitHub
  ↓
Specification
  ↓
AI Coding Agent
  ↓
Código
  ↓
Tests
  ↓
Pipeline CI/CD
  ↓
Producción

🧠 SDD en la Era de la Inteligencia Artificial

Con la llegada de agentes de código como OpenCode o asistentes avanzados, SDD cobra aún más relevancia:

• La IA es tan buena como el contexto que recibe. Proporcionar a un agente de IA una especificación OpenAPI precisa y sin ambigüedades le permite generar la implementación del backend, los tests unitarios y la capa de integración con una precisión cercana al $100\%$.
• La especificación actúa como el marco de contención (guardrail) que evita que la IA alucine endpoints o estructuras de datos inexistentes.

📝 Comparativa: TDD vs. BDD vs. SDD

🏁 Resumen

Spec-Driven Development no se trata de añadir burocracia, sino de eliminar la ambigüedad. Al tratar a las especificaciones como ciudadanos de primera clase dentro del repositorio, los equipos reducen drásticamente los errores de integración, aceleran el desarrollo paralelo y preparan su arquitectura para ser escalable e interoperable en el tiempo.

Spec-Driven Development =

enfoque de desarrollo en el que las especificaciones definen de manera explícita el comportamiento esperado del software y sirven como referencia para su implementación y validación.