Spec-Driven Development: guía de BDD, DDD, MDE y API-First

Tabla de Contenidos

• Primero se escribe qué debe hacer el software, después el código
• Por qué SDD volvió a estar de moda: la IA programa, tú especificas
• 1. Behavior-Driven Development (BDD): la especificación que se ejecuta
• 2. Domain-Driven Design (DDD): el modelo del negocio como especificación
• 3. Model-Driven Engineering (MDE) y Model-Driven Architecture (MDA): del modelo al código generado
• 4. API-First y Contract-Driven Development (CDD): el contrato manda
• Comparativa: ¿cuál enfoque te sirve?
• SDD con IA: un flujo que puedes usar mañana

  • Cómo hacerlo con OpenSpec
• Errores comunes al empezar con SDD
• Conclusión
• Preguntas frecuentes
• Fuentes

Primero se escribe qué debe hacer el software, después el código

Seguro te ha pasado: el cliente pide "un bot que agende citas", el equipo arranca a programar y, tres semanas después, nadie está de acuerdo en qué significaba "agendar". ¿Se podía cancelar? ¿Qué pasaba si el horario ya estaba ocupado? El código existe, pero la idea nunca quedó escrita.

El Spec-Driven Development (SDD), o desarrollo guiado por especificaciones, ataca justo ese problema. La regla es simple: la especificación es el artefacto principal del proyecto, y el código, las pruebas y la documentación se derivan de ella. Si cambia el negocio, primero cambia la especificación; el código viene después.

No es una sola metodología. Es una familia de enfoques que ponen una especificación, un modelo o un contrato en el centro de todo el ciclo de vida del software (SDLC). En este artículo vas a ver los cuatro más usados —BDD, DDD, MDE/MDA y API-First—, cómo se comparan y cómo aplicarlos hoy, cuando buena parte del código ya lo escribe una IA.

Por qué SDD volvió a estar de moda: la IA programa, tú especificas

La idea de especificar antes de programar tiene décadas. Lo nuevo es quién escribe el código. Con agentes de IA como Copilot, Claude Code o Cursor, generar código es barato; lo caro es saber qué generar.

Si le pides a un agente "hazme un login" sin más contexto, vas a obtener un login, no tu login. Esa forma de trabajar por intuición se ganó un nombre: vibe coding. Funciona para prototipos y se rompe en proyectos reales.

Por eso aparecieron herramientas que ponen la especificación en el centro del trabajo con IA:

• OpenSpec: mi recomendación. Es ligero, funciona con más de 30 asistentes de IA (Claude Code, Cursor, Copilot y otros) y está pensado para proyectos que ya existen, no solo para empezar de cero.
• Kiro: IDE de AWS que convierte cada funcionalidad en tres archivos: requirements.md, design.md y tasks.md.
• GitHub Spec Kit: kit open source con un proceso más rígido por fases; útil sobre todo si trabajas con GitHub Copilot.

La especificación pasó de ser un documento que nadie leía a ser el prompt más importante del proyecto.

1. Behavior-Driven Development (BDD): la especificación que se ejecuta

BDD lleva las ideas de TDD al lenguaje del negocio. La especificación son escenarios de comportamiento escritos en lenguaje natural estructurado, casi siempre en formato Gherkin (Given / When / Then, o en español Dado / Cuando / Entonces).

Feature: Agendar cita por WhatsApp

  Scenario: El horario solicitado ya está ocupado
    Given un cliente que escribe al bot de la clínica
    And el martes a las 10:00 ya tiene una cita asignada
    When el cliente pide una cita el martes a las 10:00
    Then el bot responde que el horario no está disponible
    And le ofrece los tres horarios libres más cercanos

Cómo recorre el ciclo de vida:

• Análisis y diseño: negocio, desarrollo y QA escriben juntos los escenarios en la reunión de los "Tres Amigos".
• Desarrollo y pruebas: cada escenario se conecta a una prueba automatizada (Cucumber, Behave, SpecFlow/Reqnroll) que falla antes de programar la funcionalidad.
• Mantenimiento: los archivos .feature son documentación viva (living documentation): si dejan de ser ciertos, las pruebas fallan.

Úsalo cuando el mayor riesgo del proyecto es malinterpretar lo que pide el cliente.

2. Domain-Driven Design (DDD): el modelo del negocio como especificación

En DDD la especificación es un modelo de dominio rico y un lenguaje ubicuo: las mismas palabras, con el mismo significado, en la reunión con el cliente, en el tablero y en el código. Si el negocio dice "reserva", la clase se llama Reserva, no BookingItemDTO.

Cómo recorre el ciclo de vida:

• Análisis y estrategia: con talleres como Event Storming se descubren los eventos del negocio y se dividen en Bounded Contexts (por ejemplo, Agenda, Facturación y Notificaciones), conectados por un mapa de contexto.
• Arquitectura e implementación: el diseño táctico (Entidades, Objetos de Valor, Agregados, Eventos de Dominio) traduce el modelo directamente a código.
• Evolución: cuando cambia una regla de negocio, primero se actualiza el modelo y luego la arquitectura y el código.

Un ejemplo del lenguaje ubicuo convertido en código:

// Bounded Context: Agenda
class Cita {
  reprogramar(nuevoHorario: Horario) {
    if (this.estado === "cancelada") throw new Error("Una cita cancelada no se reprograma");
    this.horario = nuevoHorario;
    this.registrar(new CitaReprogramada(this.id, nuevoHorario));
  }
}

Úsalo cuando la complejidad está en las reglas del negocio, no en la tecnología.

3. Model-Driven Engineering (MDE) y Model-Driven Architecture (MDA): del modelo al código generado

Aquí la especificación es un modelo formal: diagramas UML, un lenguaje específico de dominio (DSL) o cualquier lenguaje de modelado. MDA es la variante estandarizada por el OMG, que separa un modelo independiente de la plataforma (PIM) de uno específico de la plataforma (PSM).

Cómo recorre el ciclo de vida:

• Diseño: se construyen modelos abstractos, sin atarse a un lenguaje ni a un framework.
• Construcción y despliegue: motores de transformación convierten los modelos en código fuente, esquemas de base de datos, scripts de infraestructura y pruebas.
• Mantenimiento: el sistema se actualiza cambiando el modelo de alto nivel y regenerando; el código generado no se toca a mano.

Lo usas más de lo que crees: un schema.prisma que genera la base de datos y el cliente, o un archivo de Terraform que define tu infraestructura, son pequeños ejemplos de esta filosofía. Las plataformas low-code llevan la idea al extremo.

Úsalo cuando tienes muchos sistemas parecidos o dominios muy regulados donde conviene generar, no escribir. Cuidado con la rigidez: si las herramientas de transformación no acompañan, el equipo termina editando el código generado y el modelo deja de ser la verdad.

4. API-First y Contract-Driven Development (CDD): el contrato manda

Es la aplicación más práctica de SDD en arquitecturas de servicios, microservicios e integraciones. La especificación es el contrato de la API, escrito en un estándar abierto antes de programar: OpenAPI (Swagger) para REST, AsyncAPI para eventos o Protobuf para gRPC.

openapi: 3.1.0
info:
  title: API de Citas
  version: 1.0.0
paths:
  /citas:
    post:
      summary: Crear una cita
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [clienteId, horario]
              properties:
                clienteId: { type: string }
                horario: { type: string, format: date-time }
      responses:
        "201": { description: Cita creada }
        "409": { description: El horario ya está ocupado }

Cómo recorre el ciclo de vida:

• Diseño: se acuerda el contrato entre quien expone la API y quien la consume.
• Desarrollo en paralelo: del contrato se generan servidores mock, SDKs cliente y esqueletos de código, así frontend y backend avanzan al mismo tiempo sin esperarse.
• Integración y despliegue: las pruebas de contrato (Consumer-Driven Contracts con herramientas como Pact) corren en el pipeline de CI/CD y bloquean cualquier cambio que rompa a un consumidor.

Úsalo cuando varios equipos o sistemas dependen de la misma API, como en integraciones con WhatsApp, CRMs o pasarelas de pago.

Comparativa: ¿cuál enfoque te sirve?

No compiten entre sí: atacan riesgos distintos y se combinan bien.

Metodología	Artefacto central	Foco principal en el SDLC	Resuelve sobre todo
BDD	Escenarios de comportamiento (.feature)	Alineación negocio-desarrollo-QA y validación	"Construimos algo que el cliente no pidió"
DDD	Modelo de dominio y lenguaje ubicuo	Arquitectura, complejidad y negocio	"Las reglas del negocio están regadas por todo el código"
MDE / MDA	Modelos de abstracción (UML, DSL)	Generación automática y abstracción	"Escribimos a mano lo mismo una y otra vez"
API-First / CDD	Contratos de API (OpenAPI, AsyncAPI, Protobuf)	Integración, microservicios y paralelismo	"Cada despliegue rompe una integración"

Una combinación frecuente en proyectos reales: DDD para dividir el sistema en contextos, API-First para definir cómo se hablan esos contextos y BDD para validar cada funcionalidad desde el punto de vista del usuario.

SDD con IA: un flujo que puedes usar mañana

No necesitas adoptar las cuatro metodologías para empezar. Este flujo funciona con cualquier agente de IA y unos pocos archivos Markdown en tu repositorio; más abajo te muestro cómo automatizarlo con OpenSpec.

1. Especificar: escribe en spec.md qué debe hacer la funcionalidad y por qué, con criterios de aceptación. Aquí encajan los escenarios BDD y el lenguaje ubicuo de DDD.
2. Planear: pide al agente un plan.md con la arquitectura, el stack y los contratos (tu OpenAPI vive aquí). Revísalo tú antes de seguir.
3. Tareas: divide el plan en un tasks.md con pasos pequeños y verificables, uno por commit.
4. Implementar: el agente ejecuta una tarea a la vez, leyendo siempre la especificación y el plan como contexto.
5. Verificar: las pruebas derivadas de la especificación dicen si la tarea está terminada, no la intuición.

La regla de oro: cuando cambia un requisito, editas la especificación y dejas que el cambio fluya hacia abajo. Si corriges directo en el código, la especificación deja de ser la verdad y vuelves al vibe coding.

Cómo hacerlo con OpenSpec

OpenSpec es la herramienta que te recomiendo para aplicar este flujo. Frente a Spec Kit tiene tres ventajas prácticas:

• Menos ceremonia: no te obliga a pasar por fases rígidas; iteras sobre la propuesta hasta que esté clara.
• Pensado para proyectos existentes: cada cambio vive en su propia carpeta como un delta sobre las specs actuales, así no tienes que documentar todo el sistema antes de empezar.
• No te casa con un agente: funciona con Claude Code, Cursor, Copilot, Amazon Q y decenas más.

Para instalarlo necesitas Node.js 20.19 o superior:

npm install -g @fission-ai/openspec@latest
cd tu-proyecto
openspec init

Después, desde tu agente de IA, el ciclo tiene tres comandos:

1. /opsx:propose: crea una carpeta en openspec/changes/ con la propuesta, las specs afectadas, el diseño y las tareas. Revisas y ajustas antes de seguir.
2. /opsx:apply: el agente implementa las tareas siguiendo la especificación.
3. /opsx:archive: el cambio terminado se archiva y sus specs pasan a formar parte de openspec/specs/, la fuente de verdad del proyecto.

Si aún no tienes clara la idea, /opsx:explore te deja pensar los requisitos con el agente antes de crear la propuesta. La sintaxis exacta del comando puede variar según el asistente que uses.

Errores comunes al empezar con SDD

• Especificar de más: una spec de 40 páginas nadie la mantiene. Empieza con una página por funcionalidad.
• Especificar cómo en vez de qué: "usar Redis" va en el plan, no en la especificación.
• Spec que no se verifica: si ningún test ni contrato la valida, se desactualiza en semanas.
• Cambiar el código y olvidar la spec: es el error que convierte SDD en documentación muerta.

Conclusión

Spec-Driven Development no es burocracia: es escribir primero lo que vas a tener que explicar de todas formas. BDD, DDD, MDE y API-First son cuatro formas de hacerlo, cada una con su artefacto y su riesgo favorito. Con agentes de IA escribiendo cada vez más código, la especificación se convirtió en tu mejor herramienta para que el resultado sea el que necesitas.

Tu siguiente paso: toma la próxima funcionalidad de tu proyecto, escribe su spec.md con tres escenarios Given/When/Then y pásasela a tu agente de IA antes de pedirle una sola línea de código. Cuéntame en los comentarios cómo te fue.

Preguntas frecuentes

¿SDD es lo mismo que TDD? No. TDD parte de pruebas unitarias escritas por el desarrollador; SDD parte de una especificación de más alto nivel, de la que pueden salir pruebas, código y documentación. BDD es el puente entre ambos.

¿Sirve para equipos pequeños o proyectos personales? Sí. Un spec.md y un tasks.md bastan para que un agente de IA trabaje con mucho más foco, aunque seas un equipo de una persona.

¿Tengo que usar las cuatro metodologías? No. Elige según tu mayor riesgo: malentendidos con el cliente (BDD), reglas de negocio complejas (DDD), código repetitivo (MDE) o integraciones frágiles (API-First).

¿Qué herramientas necesito para empezar? Un editor, Markdown y tu agente de IA favorito. Si quieres estructura lista, empieza con OpenSpec: se instala con un comando y funciona con el agente que ya usas.

Fuentes

• OpenSpec (repositorio)
• Kiro: documentación de Specs
• GitHub Spec Kit (repositorio)
• Pact: Consumer-Driven Contract Testing