JAFSJosé Antonio Fuentes Santiago

SDD: Del caos del vibe coding al rigor de la arquitectura

17-05-2026

En el principio, el programador picaba código línea a línea. Y el software estaba desordenado y lleno de bugs. Las tinieblas del código legacy acechaban los despliegues de los viernes. Pero entonces llegaron los modelos de lenguaje y los agentes de IA, y la comunidad exclamó: "¡Hágase el prompt!". De repente, pasamos al fascinante mundo del vibe coding: tirarle tres frases informales a Cursor o a Claude, mirar cómo se autocompletan quinientas líneas de código por arte de magia y rezar para que compile a la primera.

Otra vez me voy por las ramas... Volvamos al presente.

La cruda realidad es que programar dejándose llevar por la inercia de una IA funciona de maravilla para un prototipo de fin de semana, pero se convierte en una pesadilla insostenible en proyectos medianos o grandes. Los agentes de IA actuales son increíblemente rápidos y eficientes, pero, si no les pones límites claros, derivan hacia resultados improvisados, generan acoplamientos indeseados y acaban desordenando tu arquitectura. De la necesidad de domar a estas inteligencias y devolver el control al desarrollo nace SDD (Spec-Driven Development).

Un poco de historia: De los tests al comportamiento, y de ahí a la especificación

Para entender dónde encaja SDD, conviene hacer un viaje al pasado y recordar a sus primos hermanos más célebres:

  • TDD (Test-Driven Development): Popularizado por Kent Beck a principios de los 2000, nos enseñó la sagrada trinidad del Rojo, Verde, Refactor: escribir el test unitario antes que el código. Fue una revolución para garantizar la calidad técnica a bajo nivel, aunque a veces pecaba de hacernos perder la perspectiva global del producto por centrarnos demasiado en la función.
  • BDD (Behavior-Driven Development): Unos años más tarde, Dan North pensó que debíamos hablar un lenguaje que el negocio pudiera entender. Trajo consigo los escenarios Given-When-Then (Dado-Cuando-Entonces). Así que pasamos de testear funciones aisladas, a probar el comportamiento del sistema.

¿Qué pasa ahora? En esta era en la que delegamos la escritura mecánica del código a agentes autónomos, testear o describir comportamientos de forma aislada se queda corto. Antes de tocar un solo archivo es importante definir las restricciones y el contexto que utilizarán los agentes. Así evitaremos errores como los de la sección siguiente.

Los problemas del vibe coding: cuando la IA es la que te guía

No me malinterpretes, el vibe coding nos ahorra mucho tiempo y nos permite centrarnos en lo importante. Pocas cosas dan más satisfacción que lanzarle un prompt a un agente y ver cómo te escupe en segundos lo que antes te llevaba una tarde entera. El problema aparece cuando dejamos que sea la IA la que siempre tome las decisiones:

Deriva arquitectónica silenciosa

Le pides al agente que implemente la feature A, y funciona. Luego la B, y también. Pero cuando llega la C, resulta que la A y la B han dejado el código en un estado donde te toca reescribir medio proyecto para añadir la nueva implementación. El agente no tiene visión global, ya que resuelve lo que le pides aquí y ahora, y el diseño general comienza a degradarse.

El síndrome de monstruo de Frankenstein

Cada prompt genera código con su propio estilo, sus propias abstracciones y su propia idea de cómo debería estructurarse el proyecto. Al cabo de unas semanas tienes un monstruo hecho de retales donde conviven tres formas distintas de manejar errores, dos patrones de acceso a datos y un servicio que la IA te propuso pero que ahora no sabes si es un repositorio, un caso de uso o vete tú a saber.

Acoplamiento invisible

Cuando no dejas una serie de límites claros, el agente comienza a tomar atajos. ¿Necesita un dato de otro módulo? Lo importa directamente. ¿Una función de utilidad? La mete donde le pilla más cerca. Cuando quieres darte cuenta, tienes dependencias cruzadas por todas partes y un refactor te deja sin tokens en un ratico.

Falsa sensación de velocidad

Este es el más traicionero. Durante las primeras semanas todo va como un tiro: características que salen a velocidad de vértigo, demos que impresionan, métricas de productividad por las nubes. Pero la deuda técnica se acumula en silencio, y cuando explota (además, siempre en el momento menos oportuno), el tiempo que "ahorraste" lo devuelves con intereses.

Un simple "haz que un usuario se pueda registrar" generará, seguramente, un código que funcione... pero que sea muy difícil de mantener.

SDD de lo que usted me habla

Para evitar los problemillas antes mencionados, SDD (Spec-Driven Development) llama a la puerta (como Avón). En esta metodología, el artefacto principal y la "fuente única de verdad" es una especificación ejecutable y versionada en tu repositorio (normalmente en Markdown estructurado). Tú diseñas la arquitectura, los casos de uso, los límites del sistema y los criterios de aceptación. Y a partir de esa documentación, el agente ya puede trazar un plan y generar el código respetando esas reglas.

PARA SABER MÁS

Para escribir el Markdown se pueden seguir patrones como EARS. Eso daría prácticamente para otro post. Sin embargo, Oguz Senna ya escribió este artículo donde desglosa los puntos principales.

Cómo aplicar SDD paso a paso

Seguro que con la descripción de la sección anterior te haces una idea. La teoría suena bien. Pero no hay que quedarse solo con el concepto abstracto, lo importante es saber por dónde empezar, si no, SDD pasa a ser otra sigla bonita para la colección. Así que vamos al grano: ¿cómo se aplica esto en el día a día de un proyecto real?

1. Crea el directorio de especificaciones

Lo primero es tener un sitio donde vivan tus especificaciones. Tan sencillo como crear una carpeta specs/ (o docs/specs/, como prefieras, el nombre es lo de menos). La clave es que las especificaciones vivan junto al código y se versionen con él. Evita tener documentos dispersos por Confluence, One Drive, Google Drive y compañía.

2. Define la arquitectura antes de escribir código

Antes de lanzar el primer prompt al agente, siéntate y diseña. Esto no significa escribir un documento de cien páginas. Se trata de dejar claro:

  • Los módulos o componentes principales y sus responsabilidades.
  • Las interfaces públicas entre ellos: qué datos entran, qué datos salen y qué contratos se respetan.
  • Las restricciones técnicas: qué base de datos usas, qué framework, qué patrones arquitectónicos sigues (hexagonal, capas, microservicios...).
  • Las invariantes del sistema: las reglas que jamás se pueden romper, pase lo que pase.

Este paso es el que da más pereza, pero te aseguro que es el que más penurias te ahorará.

3. Escribe las especificaciones por caso de uso

Aquí es donde SDD se pone interesante. Para cada funcionalidad o caso de uso, crea un archivo Markdown estructurado que incluya:

  • Contexto: qué problema resuelve y por qué existe esta funcionalidad.
  • Requisitos funcionales: qué debe hacer, paso a paso.
  • Criterios de aceptación: cómo saber que está bien hecho (vamos, los Given-When-Then de BDD de toda la vida).
  • Restricciones: qué no debe hacer, qué límites tiene, qué módulos no puede tocar.
  • Dependencias: qué otros componentes o servicios necesita.

La especificación es el contrato entre tú y el agente. Cuanto más clara sea, menos margen tendrá la IA para improvisar y más predecible será el resultado.

4. Alimenta al agente con la especificación

Cuando le pidas al agente que implemente algo, no le sueltes un prompt al aire. Apunta directamente a la especificación: "Implementa el caso de uso descrito en specs/registro-usuario.md respetando la arquitectura definida en specs/arquitectura.md". De esta forma, el agente tiene un marco claro y no necesita inventarse nada.

NOTA EN LA CABAÑA

Muchas veces ya tendrás algún fichero definiendo parte de la arquitectura y lo más importante. Por ejemplo, CLAUDE.md en Claude Code. Eso sí, recuerda que dicho fichero no debe ser el Quijote, ya que se cargará en contexto con cada petición.

5. Valida contra la especificación

Una vez el agente genera el código, no hagas la revisión pensando "a ver qué tal pinta". Compara lo generado con aquello que especificaste punto por punto: ¿respeta las interfaces? ¿Cumple los criterios de aceptación? ¿Se ha saltado alguna restricción? Si algo no cuadra, te tocará o corregir la implementación o, si descubres que la especificación estaba incompleta, actualizarla y pedir al agente que revise los cambios que apliquen.

6. Itera y mantén las especificaciones vivas

Las especificaciones no son documentos estáticos que escribes una vez y olvidas. En un proyecto vivo, puede que el dominio cambie, aparezcan nuevos requisitos o descubras un caso extremo que no habías contemplado. En esos casos la especificación debe actualizarse. Si el código evoluciona pero tu especificación sigue siendo Pikachu, acabará en el mismo sitio que con la documentación tradicional: ficheros obsoletos que si los consultas te generan más dudas que soluciones.

El peligro del plano flotante: Por qué fusionar SDD con DDD

Delegar la generación de código en una especificación SDD suena idílico, pero tiene un punto débil si se aplica en el vacío conceptual. Un agente de IA puede leer tu especificación puramente técnica, asumir que la ha cumplido a la perfección y entregarte un ecosistema de archivos impecables... pero a la hora de la verdad, puede que no funcionen juntos o que fallen en los casos extremos.

Por eso, la fusión de SDD con DDD (Domain-Driven Design para las amistades) es lo que evita que acabes con un software que puede ser técnicamente impoluto, pero muy frágil a nivel conceptual. Podríamos resumirlo de la siguiente manera:

IDEA CLAVE

Escribir SDD sin DDD es como dibujar un plano a mano alzada. A primera vista, se entenderá qué es lo que se quiere hacer, pero cuando comience la construcción, habrá imprecisiones estructurales que provocarán que tarde o temprano el edificio se venga abajo.

Al combinar ambas metodologías, dotas a las especificaciones que lee la IA de un marco semántico e inviolable. El proceso pasa de ser una "escritura de código basada en una especificación técnica aleatoria", a un flujo mucho más inteligente:

1. Modelar el Dominio (DDD)

  • Marca los contextos delimitados
  • Define el lenguaje ubicuo con el equipo de negocio.
  • Protege las reglas mediante agregados, entidades y objetos de valor.

2. Especificar (SDD)

  • Traduce el diseño estratégico en especificaciones estructuradas y claras para la IA.
  • Utiliza los términos exactos del dominio que acabas de aislar.

3. Implementar

Con los dos pasos anteriores. El agente debería generar la solución técnica respetando estrictamente los límites de contexto y las invariantes de tu modelo.

Si no aplicas DDD primero, SDD se convierte en una máquina hiperveloz que generará código huérfano, acoplado y con modelos mutantes que ni se hablan entre sí. Gracias a DDD puedes sentar las bases para disponer del idioma y las reglas correctas; mientras que con SDD, evitarás que la IA no improvise la arquitectura y las invariantes.

Cuándo NO aplicar SDD (o el arte de no matar moscas a cañonazos)

Como toda herramienta, SDD tiene su momento y su lugar. ¿Y qué ocurre cuando no usas la herramienta adecuada? Pregúntale a tu vecindario cuando cuelgues un cuadro usando un martillo neumático. Hay escenarios en los que montar toda la parafernalia de especificaciones y modelado de dominio es un desperdicio de energía monumental:

Cambios pequeños y localizados

Si tienes que añadir un campo a un formulario, cambiar el texto de un botón o ajustar una validación puntual, los LLM actuales son perfectamente capaces de entender la estructura del proyecto por sí solos. Con darles el contexto del archivo y una instrucción clara, el agente sabrá qué tocar sin necesidad de un documento de especificaciones de diez páginas. Reserva el cañón para cuando el objetivo lo merezca.

Corrección de bugs

Aquí mi recomendación es aplicar una especie de TDD express que encaja de maravilla con cualquier agente de IA:

  1. Define el test primero: escribe el caso de prueba que reproduce el comportamiento incorrecto y que, por tanto, fallará. Si está en rojo (recuerda TDD), significa que el bug está bien reproducido.
  2. Dale las instrucciones al agente: describe el problema, apunta al test en rojo y deja que localice la causa raíz y proponga la corrección.
  3. El test tiene que ponerse verde: si el agente ha hecho bien su trabajo, el test pasará. Si no, tocará revisarlo (a no ser que pienses que es mejor decir que no es un bug sino una característica...).

Este flujo es elegante porque convierte al propio test en la especificación del bug: qué se esperaba sucediera, qué ocurría y en qué momento se ha solucionado.

Prototipos y experimentos

Si estás montando un PoC (Proof of Concept) o explorando si algo es técnicamente viable, la especificación puede esperar. En ese contexto, el vibe coding es perfectamente legítimo. El problema viene cuando el prototipo, en lugar de tirarse a la basura tras la validación, acaba convirtiéndose en un producto.

Meme POC

Conclusión

Al igual que siempre repito hasta la sociedad respecto a los principios SOLID, DDD y otros patrones: "no son religiones ni verdades absolutas". Siempre hay que equilibrar su aplicación y uso dependiendo del caso.

Y es que si tenemos una definición excesiva, puedes caer en la trampa de intentar documentar hasta el más mínimo detalle de toda la aplicación antes de programar nada, lo que resucitará al fantasma de las Navidades pasadas, más conocido como viejo modelo en cascada (aún siento escalofríos al pensar en él).

SDD es una herramienta espectacular para trabajar codo con codo con las herramientas de IA actuales sin perder el control de tu arquitectura. Porque sí, la IA pone la velocidad, pero tú sigues poniendo el criterio técnico. Recuerda: la potencia sin control no sirve de nada.

ESTO SE ESTÁ ESCRIBIENDO

Todo esto está tomando forma de libro: Desarrollo con IA en un Apocalipsis Zombi, el tercero de la saga. Aún está en preparación; en su ficha tienes el índice y lo que ya se puede contar. Si quieres que te avisen cuando salga, sigue al autor en Amazon: el refugio no manda correos, pero Amazon sí.