De BDD a SDD: cómo quitar la ambigüedad escribiendo las historias de usuario en Markdown

En el blog de la cátedra ya hemos publicado varias entradas sobre cómo escribir buenas historias de usuario a partir de una épica, cómo redactar criterios de aceptación claros y cómo transformar esos criterios en tests con Cucumber. Esa serie cubre, en esencia, una forma de trabajar en BDD (Behaviour Driven Development): comportamiento primero, escenarios Given-When-Then, validación conjunta con negocio.

Con la IA generando cada vez más código de forma directa, ese trabajo previo; escribir bien la historia y sus criterios, se ha vuelto más importante, no menos. El siguiente paso natural en la serie es hablar de Spec-Driven Development (SDD), y de por qué Markdown es el formato que lo hace posible en el día a día.

El problema: la ambigüedad no se le puede pedir a una IA que la resuelva

En febrero de 2025, Andrej Karpathy (cofundador de OpenAI) acuñó el término vibe coding: dejarse llevar por la IA, aceptar todo lo que propone, dejar de leer los diffs. Funciona para un prototipo de fin de semana. No funciona cuando el código tiene que mantenerse, escalar y pasar por más de una persona.

El dato que mejor lo resume: según Y Combinator, el 25% de las startups de su última cohorte tenían bases de código generadas en un 95% por IA. La pregunta que se queda sin responder es quién entiende y mantiene ese código cuando algo falla.

El origen del problema casi siempre es el mismo: un prompt ambiguo. Si le pedimos a un agente "haz un formulario de registro de usuarios", el agente adivina la validación, el diseño de errores y hasta la arquitectura. Si le damos una especificación precisa: qué campos, qué reglas, qué debe pasar si algo falla, el resultado deja de depender de lo que la IA "cree" que queríamos decir.

Qué es Spec-Driven Development

SDD no es un framework ni sustituye a Scrum. Es un enfoque de trabajo con tres ideas centrales:

1. Se escribe primero una especificación clara de lo que se quiere construir: objetivo, reglas de negocio, criterios de aceptación, restricciones técnicas.
2. Esa especificación se usa como fuente única, tanto para las personas del equipo como para los agentes de IA.
3. El código se genera a partir de la especificación, no de un prompt improvisado sobre la marcha.

GitHub lo resume bien en la documentación de su Spec Kit: "mantener software significa evolucionar especificaciones; el código es el enfoque de última milla".

SDD, TDD y BDD: primos, no competidores

Si ya trabajáis con TDD o BDD, la buena noticia es que SDD no viene a sustituirlos:

• TDD: escribe el test primero. Garantiza corrección a nivel de unidad, pero no captura la intención completa del producto.
• BDD: lo que ya practicamos en el blog con Gherkin y Cucumber; describe el comportamiento primero. Alinea al equipo con negocio, pero deja abiertas muchas decisiones técnicas.
• SDD: define primero el qué y el porqué, y añade el plan técnico y el desglose en tareas. Es el ancla que mantiene alineados a las personas y a los agentes de IA.

En la práctica, las tres conviven: SDD para definir el feature completo, BDD para validar el comportamiento de principio a fin, TDD para asegurar cada unidad de código.

Los tres niveles de SDD

No todas las herramientas ni todos los equipos aplican SDD con la misma intensidad. Es útil pensarlo como una escala:

• Spec-first: se escribe la especificación antes de codificar, se usa para la tarea en curso y después se descarta. Es el nivel más habitual hoy.
• Spec-anchored: la especificación se conserva después de completar la tarea y sirve para evolucionar el feature más adelante.
• Spec-as-source: la especificación es el artefacto principal; solo se edita la spec, y el código se regenera a partir de ella. Todavía experimental, pero es la dirección en la que apunta el ecosistema (herramientas como Tessl Framework ya trabajan así).

Para la mayoría de equipos, empezar en spec-first y evolucionar hacia spec-anchored —conservar la especificación como documentación viva del feature— ya supone un salto de calidad importante.

Por qué Markdown es el vehículo natural

Una especificación solo es útil si la puede leer sin fricción tanto una persona como un agente de IA. Ahí es donde entra Markdown.

Un fichero .md es texto plano con una sintaxis mínima: # para títulos, **negrita**, listas con - o 1., tablas, bloques de código. Se lee perfectamente en bruto, sin convertirlo a HTML ni a PDF, y cualquier editor lo abre sin plugins. Para nuestro caso concreto tiene tres ventajas que ningún otro formato ofrece a la vez:

• Es legible por humanos y por máquinas sin necesidad de parsers complejos ni de exportar nada.
• Se versiona en Git igual que el código: cada cambio en la especificación queda trazado, se puede revisar en un pull request y se puede comparar entre versiones.
• No admite ambigüedad de formato. Un documento de Word puede tener una tabla mal alineada, un color que no se ve igual en dos pantallas o un comentario suelto en un margen. Un .md con una lista de criterios de aceptación es exactamente lo que parece.

Cómo estructurar una historia.md en la práctica

Siguiendo con el ejemplo que ya usamos en anteriores entradas —el alta de un usuario en un formulario de registro—, así es como queda la especificación completa en un único fichero .md:

# HU-014: Registro de usuario

## Historia de usuario
Como visitante de la web,
quiero registrarme con mis datos personales,
para poder acceder a las funcionalidades restringidas del sistema.

## Criterios de aceptación (Gherkin)

Escenario: Registro con datos válidos
  Dado que soy un visitante en la página de registro
  Cuando relleno nombre, apellidos, email y contraseña con datos válidos
  Y acepto los términos y condiciones
  Entonces el sistema crea la cuenta y me redirige al panel principal

Escenario: Email ya registrado
  Dado que soy un visitante en la página de registro
  Cuando introduzco un email que ya existe en el sistema
  Entonces el sistema muestra el error "Este email ya está registrado"
  Y no crea una cuenta nueva

## Especificación técnica
- Nombre: máx. 30 caracteres alfanuméricos, obligatorio
- Apellidos: máx. 60 caracteres alfanuméricos, obligatorio
- Email: formato válido, único en el sistema
- Contraseña: mínimo 8 caracteres, al menos una mayúscula y un número
- Endpoint: `POST /api/usuarios`
- Respuesta de error: HTTP 409 con el código `EMAIL_DUPLICADO`

Con este único fichero, un agente de IA tiene lo que necesita para generar el formulario, la validación, el endpoint y los tests, sin tener que adivinar nada. Y el equipo tiene, en el mismo sitio, la historia, los criterios y la spec técnica: no hace falta ir a tres herramientas distintas para entender qué hay que construir.

Lo que hay que tener en cuenta

SDD no es magia y tiene límites que conviene conocer antes de aplicarlo a todo:

• Escribir buenas specs sigue siendo difícil. Requiere pensar con claridad antes de actuar, y esa disciplina no la pone la herramienta, la pone el equipo.
• No compensa para todo. Para un bug pequeño o un cambio trivial, escribir una especificación completa puede ser más esfuerzo que el propio cambio. SDD rinde más en features medianos o grandes.
• No elimina la revisión humana. Una especificación clara reduce la ambigüedad, pero no garantiza que el agente siga cada instrucción al pie de la letra. Sigue haciendo falta revisar el resultado.

Conclusión

Spec-Driven Development no es una metodología nueva que sustituye a Scrum, ni una moda pasajera ligada a la IA. Es, en el fondo, la misma idea de siempre: pensar antes de construir, pero aplicada con un formato que tanto personas como agentes pueden leer sin ambigüedad: Markdown.

Ya sabíamos escribir historias de usuario y criterios de aceptación en Gherkin. El siguiente paso es sencillo: juntarlo todo en un .md versionado, y dejar que ese fichero, y no el prompt improvisado del momento, sea la fuente de la verdad del equipo.

Esta entrada forma parte de nuestra serie sobre historias de usuario y criterios de aceptación. Si te las has perdido, puedes leer las entradas anteriores del blog: "Escritura de historias de usuario en base al texto de una épica", "Escritura de criterios de aceptación para una historia de usuario" y "Transformación de criterios de aceptación en test Cucumber".