Spec-to-Code (SDD): qué es, por qué existe y cómo se aplica en proyectos

SDD (Spec‑Driven Development, también llamado Spec‑to‑Code) no es una herramienta ni una metodología nueva con ceremonias. Es una filosofía de ingeniería: la especificación se convierte en el contrato central del sistema y el resto de artefactos (diseño, tareas, código, pruebas) se organizan como derivados verificables de ese contrato.

Nuestra tesis: cuando el código se produce rápido (porque el equipo es bueno, porque hay librerías maduras o porque usamos IA), el cuello de botella se desplaza a donde siempre ha sido incómodo: acordar qué significa “correcto” y demostrarlo. SDD existe para que esa discusión no viva en chats, ni en recuerdos, ni en revisiones subjetivas, sino en un contrato versionado y enlazado con evidencia.

De dónde viene el término SDD

SDD no nace con los agentes de IA. El nombre Specification‑Driven Development ya aparece, al menos, en la literatura académica de principios de los 2000: en 2004, Ostroff, Makalsky y Paige publican Agile Specification‑Driven Development, donde el enfoque se entiende como una combinación de Test‑Driven Development con Design by Contract (contratos/precondiciones/postcondiciones) en entornos que permiten expresar especificaciones de forma más formal. Ese “SDD clásico” no habla de generación automática ni de agentes; habla de usar especificaciones (tests y contratos) como guía y como mecanismo de verificación en un marco ágil. Como ejemplo temprano, en 2004 Ostroff, Makalsky y Paige publican Agile Specification‑Driven Development (York University; también recogido en XP 2004 de Springer), donde SDD se entiende como una combinación de TDD y Design by Contract (contratos/precondiciones/postcondiciones) en un marco ágil: especificaciones formales y contratos como base de desarrollo y verificación.

La reaparición de SDD con la llegada de la IA generativa

Lo que ocurre en 2024–2025 es una reaparición del término con una reinterpretación industrial: SDD vuelve a circular, pero ahora asociado a flujos donde la especificación en Markdown actúa como insumo principal para que modelos (con o sin agentes) produzcan plan, tareas, código y validaciones. GitHub, por ejemplo, describe el workflow en el propio repositorio de Spec Kit (el documento spec-driven.md) y lo presenta como un experimento abierto: especificaciones en Markdown como entrada para derivar plan, tareas e implementación en flujos asistidos por IA. Microsoft lo aterriza desde el día a día del IDE en su artículo sobre Spec Kit, e InfoQ lo enmarca como un paradigma donde la especificación se vuelve el eje de generación y gobernanza.

La reaparición como reacción al “vibe coding”

Hay otro matiz que explica por qué esta filosofía vuelve con fuerza: no solo reaparece “porque hay IA”, sino porque hay una forma concreta de usarla que escala mal. A finales de 2024 y, sobre todo, en 2025, se populariza el patrón de iterar producto a base de prompts sueltos y correcciones locales: funciona para prototipos, pero en cuanto hay integración, equipo y mantenimiento, la “verdad” se queda atrapada en el repositorio y en la cabeza de quien estuvo ahí. Ese estilo tiene nombre propio en la conversación técnica —vibe coding— y el “nuevo SDD” se vende, explícitamente, como antídoto: reemplazar prompts como fuente de verdad por un contrato versionado que delimita qué es correcto y qué no.

Por eso muchos textos contemporáneos presentan SDD como disciplina para evitar drift (deriva) entre intención y código: la spec deja de ser un artefacto aspiracional y se convierte en una referencia que se consulta en review, que se actualiza cuando cambia el comportamiento esperado y que empuja descomposición y verificación. Este encuadre aparece tal cual en varios textos contemporáneos: Marcus Ohlsson, por ejemplo, lo discute en sus “initial thoughts” sobre SDD (IA como catalizador, pero contrato como núcleo), y la documentación de Spec Kit insiste en la misma idea: usar especificación y trazabilidad para que la implementación no sea una ruleta de prompts. En paralelo, Microsoft lo explica desde la práctica cotidiana (Spec Kit en el IDE) e InfoQ lo sitúa como parte de un giro hacia especificaciones como eje de gobernanza cuando el código se produce a más velocidad.

Qué es SDD y qué no es

SDD es un cambio de jerarquía entre artefactos. En lugar de tratar la spec como “documentación útil si hay tiempo”, la tratamos como autoridad operativa del “debería”: qué prometemos, qué permitimos, qué prohibimos, qué invariantes nunca deben romperse.

El código, entonces, deja de ser el lugar donde se negocia el producto. Pasa a ser una implementación que se acepta o se rechaza contra un contrato explícito. Esto vale igual si el código lo escribe una persona, un equipo o un agente: el punto es que el criterio de corrección no se improvisa.

Por qué reaparece SDD después de la era Agile

Para entender el “por qué ahora” conviene mirar el contexto. En los últimos 20 años hemos interiorizado prácticas ágiles (Scrum, XP y derivados) que nos enseñaron una lección útil: optimiza el ciclo de feedback y entrega algo que funcione. El problema es que, en muchas organizaciones, esa lección se simplificó hasta convertirse en hábito: historias en un board, conversaciones distribuidas, y una confianza tácita en que “el código es la documentación”. Eso puede funcionar en equipos pequeños y dominios simples, pero empieza a fallar en cuanto hay integración, varios equipos tocando contratos, semántica delicada y hace aguas en cuanto empiezan a rotar miembros del equipo. Quizás en un principio todos conocen la motivación e intención del producto a construir, pero si el equipo cambia, la interpretación de la intención con toda probabilidad también.

Ahí es donde SDD vuelve a tener sentido como filosofía. No porque Agile esté “mal”, sino porque Agile —en su versión más extendida— suele dejar la definición de “correcto” en un lugar difuso: un mix de tickets, conversaciones y conocimiento tribal. Cuando el sistema crece, ese mix produce dos síntomas que se repiten: (1) divergencia entre equipos (cada uno implementa su interpretación razonable) y (2) revisión subjetiva (aceptamos cambios por intuición porque no hay un contrato común). SDD reaparece para atacar eso desde la raíz: convertir lo esperado en un artefacto versionado, discutible y verificable.

La diferencia clave, por tanto, no es “SDD vs Scrum/XP” como si compitieran. Scrum y XP organizan el trabajo y promueven feedback rápido; SDD organiza la autoridad del sistema. En un equipo ágil puedes seguir teniendo sprints, dailies o Kanban. Lo que cambia con SDD es el criterio de validación:

«Las historias dejan de ser el contrato y pasan a ser un input»

El contrato se materializa en una spec con invariantes, criterios de aceptación y ejemplos, enlazada con evidencia (tests/checks). Si el software se mueve más rápido que nuestra capacidad de alinear semántica, SDD es la forma de volver a poner un contrato en el centro sin volver a la burocracia.

SDD no es una vuelta a la Cascada (Waterfall)

Y aquí viene el “qué no es”. SDD no es Waterfall con otro nombre. No es escribir un documento perfecto para predecir el futuro. No es “documentar más”. En SDD documentamos menos cosas, pero cosas correctas: las que reducen ambigüedad, coordinan al equipo y permiten verificar.

Tampoco es sinónimo de un toolkit concreto. Hay herramientas que lo operacionalizan mejor o peor, pero de momento, en este artículo vamos a olvidarnos de estas herramientas y vamos pensar en un equipo de personas que lo apliquen. Si los artefactos existen, se revisan y gobiernan el cambio, hay SDD. Si los artefactos se ignoran, no.

La tesis técnica de fondo: primero definimos, luego demostramos

Un sistema de software no se define por el código que escribimos, sino por el conjunto de reglas que prometemos: requisitos, restricciones, invariantes, contratos de integración y criterios de aceptación. Antes de implementar, lo que estamos haciendo es especificar qué consideramos válido y qué consideramos un fallo.

A partir de ahí, el trabajo de desarrollo tiene una responsabilidad muy concreta: traducir esa definición a una implementación sin perder semántica por el camino. Si el sistema termina “funcionando” pero viola una regla, no hemos entregado el producto: hemos entregado una interpretación.

El punto incómodo llega al final: cuando “terminamos”, en realidad empieza la pregunta que importa. ¿Cumple el sistema lo que dijimos que debía cumplir? ¿Respeta las reglas del dominio? ¿El producto resultante es, de verdad, lo que queríamos construir? Esa fase es validación, y no se resuelve con intuición ni con demos optimistas: se resuelve con criterios de aceptación y con evidencia.

En la práctica, esa evidencia suele materializarse en tests (y checks) vinculados a cada criterio de aceptación. No porque los tests sean perfectos, sino porque son el mecanismo más operativo para evitar el autoengaño: si no podemos demostrar que el contrato se cumple, estamos pidiendo confianza.

SDD, en el fondo, es esto: cerrar el bucle entre lo definido y lo validado. La especificación es la autoridad del “debería”; la evidencia es la autoridad del “hace”. Y el equipo mantiene ambos sincronizados para que el sistema no evolucione por accidentes.

Antes de aplicar SDD: qué tiene que estar ya resuelto

SDD no cubre el ciclo completo de desarrollo de software. No define cómo descubrimos el producto, ni cómo alineamos stakeholders, ni cómo priorizamos. SDD empieza cuando ya existe una intención mínimamente estable y el problema pasa de “¿qué estamos construyendo?” a “¿cómo lo construimos sin perder la semántica por el camino?”.

Dicho de otra manera: SDD no sustituye discovery. Lo que hace es convertir intención en contrato y usar ese contrato para gobernar delivery.

Estas son las precondiciones que, si no se cumplen, suelen indicar que el proyecto aún no está listo para SDD (o que solo podemos aplicar un SDD muy ligero):

1. Stakeholders y objetivo suficientemente alineados
   • Debe existir una definición operativa de éxito: qué problema resolvemos, para quién, y qué cambiaría si lo resolvemos.
   • Si aún estamos en “no sabemos qué queremos”, pedir una spec es prematuro: estaremos congelando hipótesis como si fueran contrato.
2. Alcance y no‑alcance explícitos (aunque sean imperfectos)
   • Una spec sin límites invita a que el sistema crezca por suposiciones.
   • Si no podemos decir “esto entra” y “esto no entra”, el primer artefacto que toca escribir no es una spec: es un recorte de alcance.
3. Un lenguaje común del dominio
   • Si el equipo no comparte definiciones básicas (“activo”, “accionable”, “fraude”, “aprobado”), no hay contrato posible.
   • Señal de no‑preparación: cada sprint reabre debates semánticos sobre los mismos conceptos.
4. Capacidad de producir evidencia (tests/checks) en el entorno real
   • SDD se apoya en demostrar cumplimiento. Si no hay CI razonablemente determinista o no podemos automatizar validaciones mínimas, el contrato se vuelve opinable.
   • En proyectos donde testear es “difícil por defecto”, el primer trabajo es reducir esa fricción (infra, harness, datos de prueba, etc.).
5. Ownership claro del contrato
   • Alguien (no “todo el mundo”) debe ser responsable de mantener la spec y de arbitrar cambios de intención.
   • Si el ownership es difuso, aparece teatro documental: la spec existe, pero nadie la actualiza bajo presión.
6. Un umbral de cambio para decidir cuánto SDD aplicar
   • Si intentamos aplicar el pipeline completo a cambios triviales, el equipo lo rechazará.
   • Si no hay criterio de “modo ligero vs modo completo”, SDD se convierte en burocracia o en humo.

Si estas condiciones no existen, el síntoma típico es que la spec se llena de ambigüedades, el plan se vuelve una negociación constante y la verificación llega tarde. En ese escenario, el problema no es “que SDD no funcione”: es que todavía no hay contrato posible.

La jerarquía de artefactos: por qué SDD necesita piezas (y cuáles son)

Si SDD es una filosofía, su manifestación práctica es una disciplina de artefactos. No por burocracia, sino porque, sin artefactos, no hay contrato que sobreviva a la presión.

Y conviene decirlo explícitamente: no existe un estándar oficial de “los artefactos de SDD”. No hay un ISO de spec.md ni una lista canónica de ficheros que, por existir, te conviertan mágicamente en un equipo SDD. Lo que sí existe es un patrón recurrente: distintas variantes (académicas, industriales, toolkits) acaban convergiendo en el mismo mecanismo de control: un contrato funcional, un contrato técnico, una descomposición revisable y una forma de verificar.

Por eso hablamos de jerarquía y de roles, no de nombres. En algunos sitios verás requirements/design/tasks; en otros spec/plan/tasks; en otros habrá ADRs, esquemas OpenAPI o documentos de calidad en lugar de “constitución”. La forma cambia, pero la intención es estable:

«que el “debería” sea legible y versionable, que el “cómo” no se invente, que el trabajo sea auditables por partes y que la evidencia cierre el bucle«

La forma más estable de explicarlo es esta cadena de derivación:

• Constitución (guardrails): reglas tranversales no negociables del proyecto.
• Spec (contrato funcional): qué debe hacer el sistema y bajo qué reglas.
• Plan (contrato técnico): cómo lo construiremos sin inventar arquitectura.
• Tasks (unidades de trabajo): cómo partimos el cambio para que sea revisable.
• Implementación + evidencia: el código y las pruebas que demuestran cumplimiento.

No hace falta que estos artefactos se llamen así. Lo importante es el rol que cumplen y el orden de autoridad. En SDD, cuando hay conflicto, el contrato manda. El código no “gana” por existir.

Constitución: los límites que evitan debates infinitos

La constitución es un documento corto que responde a “cómo trabajamos aquí” y que evita que cada PR sea una negociación desde cero.

Incluye cosas como estrategia de testing, estándares de calidad, límites de performance razonables, convenciones, y reglas de seguridad básicas. No es un manual de estilo. Es un set de guardrails que reduce variabilidad.

En filosofía SDD, la constitución es clave porque evita un fallo común: que cada cambio meta un pequeño “criterio de calidad” distinto. Si la calidad cambia por PR, la base del sistema se erosiona.

Spec: el contrato del “debería” (sin decisiones técnicas)

La spec no es un catálogo de user stories. Es un contrato de comportamiento. Una spec útil suele tener:

• Invariantes: reglas que siempre deben cumplirse.
• Criterios de aceptación: condiciones verificables de “hecho”.
• Ejemplos y edge cases: escenarios que delimitan semántica.
• Alcance y no‑alcance: límites explícitos para no inventar producto.

Lo importante: la spec habla del “qué” y del “por qué”, no del stack. Si mezclamos el “cómo” aquí, convertimos la spec en un documento de implementación y perdemos el contrato.

Ejemplo mínimo (GTD, a propósito simple):

• Invariante: una tarea no puede estar en Inbox y NextAction a la vez.
• Criterio: promocionar a NextAction elimina el estado Inbox.
• Edge case: un texto no accionable no se puede promocionar.

No es una plantilla. Son tres líneas. Pero ya tenemos semántica operativa, no poesía.

Plan: decisiones con “motivo de cambio” (lo que no queremos que nadie invente)

El plan existe porque hay decisiones que, si se toman mal, cuestan meses. No queremos que esas decisiones aparezcan por accidente.

Un plan útil fija arquitectura, límites, contratos y restricciones. No pretende capturar cada detalle. Pretende capturar lo que tiene coste de cambio alto: cómo versionamos APIs, cómo persistimos datos, qué consistencia prometemos, dónde ponemos lógica de dominio, qué observabilidad exigimos.

La guía práctica: si una decisión te dolería cambiar dentro de seis meses, probablemente merece estar en el plan. Si no, quizá es ruido.

Tasks: la unidad de control que hace SDD operativo

Tasks es la parte que convierte filosofía en delivery. Sin tasks pequeñas, SDD se queda en “bonita teoría”.

La razón es simple: la revisión humana y la verificación automática tienen límites. Si un cambio es demasiado grande, nadie lo audita con confianza. Da igual quién lo haya implementado.

Una task bien formada suele tener:

• Referencia a la sección de spec que cubre.
• Referencia a las restricciones del plan que aplica.
• Un criterio de done verificable.
• Tests esperables.
• Superficie de cambio acotada (rutas, módulos, contratos tocados).

Regla práctica: si una task no cabe en un PR que podamos revisar con calma en 10–15 minutos, está mal cortada.

SDD no es “escribir specs”: es meter checkpoints antes de producir código

El cambio cultural de SDD no está en escribir documentos. Está en introducir puertas de calidad que frenan el impulso de implementar antes de entender.

En la práctica, hay dos checkpoints que separan equipos que “dicen” que hacen SDD de equipos que lo hacen.

Checkpoint 1: acuerdo sobre el contrato. Si no estamos de acuerdo con la spec, no se implementa. Esto evita el patrón de “ya lo aclararemos después”, que siempre sale caro.

Ejemplos clásicos de cómo aparece este checkpoint en proyectos reales:

• “¿Qué significa exactamente ‘activo’?” En un producto con estados (cuentas activas/inactivas, proyectos activos/archivados, suscripciones), un requisito tipo “mostrar solo elementos activos” parece trivial… hasta que descubres tres interpretaciones válidas. ¿Activo es “no archivado”? ¿O “con actividad en los últimos N días”? ¿O “con un flag + fecha de expiración”? Sin checkpoint, cada equipo implementa su lectura y el bug llega en integración. Con checkpoint, esa discusión se cierra en la spec como una regla explícita (y normalmente con 2–3 ejemplos), y el test suite se convierte en el árbitro.
• Ambigüedad en reglas de negocio: “aplica descuento si el cliente es premium” se rompe en cuanto entran excepciones (periodos de gracia, upgrades/downgrades, prorrateos). El checkpoint fuerza a listar excepciones relevantes y a convertirlas en criterios de aceptación. Impacto típico: menos retrabajo en QA, menos cambios urgentes “porque negocio quería decir otra cosa”, y menos PRs reabiertos por discusiones semánticas.
• Contrato entre frontend y backend: cuando un endpoint “debe devolver X”, el checkpoint obliga a fijar el contrato de respuesta (campos, errores, paginación, orden) antes de que cada parte avance por su cuenta. Impacto: se reduce el trabajo de integración, desaparecen “fixes” de última hora por campos faltantes, y el equipo deja de usar el backend de staging como si fuera una spec cambiante.

En proyectos grandes, este checkpoint suele sentirse como una inversión pequeña que evita un coste enorme: reduce el número de rondas de aclaración a mitad de implementación, reduce cambios divergentes y, sobre todo, convierte la revisión en una comparación contra contrato, no contra opiniones.

Checkpoint 2: acuerdo sobre restricciones técnicas. Si el plan no fija límites, acabamos discutiendo arquitectura en cada PR. El plan no elimina debates, pero los adelanta cuando aún son baratos.

Ejemplos clásicos de este checkpoint (y su impacto):

• Consistencia y transacciones: “crear pedido y reservar inventario” puede implementarse como una transacción local, como un workflow con eventos, o como un sagas con compensaciones. Si no fijamos restricción (“necesitamos consistencia fuerte en stock” o “aceptamos consistencia eventual con compensación”), cada implementación será distinta y el sistema se vuelve incoherente. Con checkpoint, la decisión queda en el plan y los PRs se revisan contra ella. Impacto: menos re-arquitecturas a mitad de camino y menos incidentes por comportamientos no alineados.
• Límites de performance y acceso a datos: un requisito tipo “lista de tareas con filtros” puede acabar en N+1 queries, en cargas completas en memoria o en paginación mal definida. El checkpoint técnico define límites (paginación obligatoria, índices, timeouts, cache) y evita que se cuelen “soluciones que funcionan en local” pero mueren en producción. Impacto: menos deuda invisible y menos rework de performance en fases tardías.
• Seguridad y cumplimiento: si el plan no fija “autorización obligatoria en endpoints X”, “PII no en logs” o “auditoría mínima en cambios sensibles”, esos requisitos aparecen tarde, como parche. Con checkpoint, se convierten en restricciones upfront y pasan a formar parte de la definición de done (tests de autorización, linters/herramientas de seguridad, checks en CI). Impacto: menos sorpresas en auditorías y menos correcciones urgentes en fases de release.
• Decisiones de integración: “integramos con proveedor A” no basta; hay que fijar idempotencia, reintentos, timeouts y manejo de fallos. Sin checkpoint, cada módulo elige su estrategia y el sistema se comporta de forma impredecible. Con checkpoint, hay una política común y el plan actúa como contrato técnico.

Estos checkpoints son válidos incluso sin IA. De hecho, muchos equipos senior ya operaban así de forma implícita. SDD lo hace explícito, versionable y repetible: la spec cierra semántica y el plan cierra límites, antes de que el código (quien sea que lo escriba) multiplique el coste del cambio.

Por qué SDD aparece ahora: cuando la implementación deja de ser el cuello de botella

Durante años, la ingeniería de requisitos pedía más rigor. El problema era la economía: escribir y mantener un contrato completo parecía más caro que “seguir iterando”.

Pero cuando la implementación se acelera, el coste relativo cambia. Si podemos producir código en horas, pero seguimos tardando semanas en alinear semántica y revisar cambios, el sistema se vuelve frágil.

SDD no promete eliminar retrabajo. Promete moverlo a un lugar donde es más barato: alinear intención antes de generar volumen de código. Y promete algo más importante: recuperar trazabilidad, para que un cambio de requisito no sea un juego de adivinar impactos.

La adopción responsable reconoce un matiz: SDD sigue siendo un enfoque emergente en su estandarización. No hay receta universal. Lo que hay es una idea fuerte: un contrato central y un pipeline que alinea artefactos.

Trade‑offs reales: el overhead existe y hay que diseñarlo

SDD no es gratis. La pregunta no es “¿tiene overhead?”. La pregunta es “¿cuándo compensa y cómo lo hacemos sobrevivible?”.

Cuándo compensa

Suele compensar cuando hay riesgo, coordinación o semántica:

• Dominios con reglas: el producto es lógica, no pantallas.
• Sistemas vivos: features N→N+1 donde lo nuevo interactúa con lo existente.
• Equipos paralelos: frontend/backend o varios equipos tocando contratos.
• Integraciones: APIs, eventos, esquemas que no pueden derivar sin dolor.

Cuándo no compensa (o requiere modo ligero)

Cambios triviales no justifican el pipeline completo. Un ajuste de copy, un refactor local con una prueba de regresión, una corrección evidente: si pedimos spec+plan+tasks completos, la gente dejará de usarlo.

Aquí entra un concepto sano: SDD ligero. Mantener el contrato mínimo (una task bien definida y evidencia) sin forzar artefactos grandes. No es un downgrade ideológico; es una condición de supervivencia.

El riesgo de sprawl documental

Un fallo frecuente es cambiar “lógica implícita” por “montañas de Markdown”. Eso no es progreso. En SDD, el orden documental también se diseña: naming, ownership, cadencia de actualización, y reglas de qué entra en spec y qué entra en plan.

Si la spec crece sin estructura, deja de ser un contrato y vuelve a ser un wiki.

Antipatrones: cómo se rompe SDD en dos sprints

SDD pierde credibilidad por fallos previsibles. Nombrarlos nos ahorra discursos.

Spec vaga → suposiciones → deuda. Si no hay invariantes ni ejemplos, cualquier implementación “parecerá” correcta. Luego pagamos el coste en bugs, soporte y refactors.

Tasks grandes → diffs in‑auditables. Si un PR es imposible de revisar, lo aceptamos por presión. Eso convierte CI en un trámite y la revisión en fe.

Spec sin ownership → teatro documental. Si nadie mantiene el contrato, la gente deja de confiar en él. Y cuando se pierde la confianza, el contrato muere.

“Compila = ok”. Compilar no prueba semántica. En SDD la evidencia manda: tests relevantes, checks, y cuando aplica, señales de observabilidad.

SDD como excusa para no entender el sistema. El contrato no reemplaza el pensamiento. Solo lo hace explícito.

Diagnóstico rápido: si cada sprint reabrimos debates sobre el significado de conceptos del dominio, el problema no es el proceso. Es que el contrato no existe o no se mantiene.

Cómo funciona SDD en la práctica

Antes de entrar en el ejemplo, dejemos una cosa clara: este equipo es humano y el enfoque es agnóstico de herramientas y formatos. En SDD no existe una obligación de que la documentación sea Markdown, YAML o un set concreto de ficheros. SDD no formaliza el soporte; formaliza qué artefactos necesitas, para qué sirven y cómo se usan para implementar y, después, validar.

Un equipo humano puede escribir la spec en Notion, Confluence, un Word compartido o incluso en un cuaderno de notas, siempre que el contrato sea legible, versionable de algún modo y se use de verdad en revisión y validación. Lo que sí conviene evitar es confundir este SDD (filosofía de contrato + evidencia) con Agentic SDD, que es la variante donde la documentación se diseña deliberadamente para ser consumida por agentes de IA y por eso tiende a estandarizar formatos, estructura y trazabilidad máquina‑amigable. Esa variante es la que hoy tiene más repercusión, pero aquí queremos que se entienda el enfoque sin casarlo con un stack ni con un toolkit.

Contexto práctico del ejemplo

Imaginemos un equipo pequeño pero realista construyendo un sistema de gestión de tareas y listas. No un “todo en uno”, sino un producto con semántica suficiente para equivocarse: inbox, listas, estados, fechas, recurrencias simples y permisos básicos. El equipo tiene:

• Product (PM/PO) que trae objetivos, prioridades y feedback.
• Tech lead que gobierna arquitectura, calidad y decisiones con coste de cambio.
• Backend y Frontend que implementan y mantienen contratos.
• QA (o alguien haciendo el rol) que ayuda a convertir intención en criterios verificables.

El proyecto arranca como arrancan casi todos: objetivos, un alcance inicial y una primera iteración de pantallas. La diferencia con SDD es cuándo el equipo decide “hacerlo serio”: en el momento en que ven que hay reglas, integración y riesgo de interpretaciones.

Paso 0: antes de la spec, el equipo cierra lo mínimo del producto

Aquí SDD no inventa nada nuevo: se hace discovery, se prioriza, se habla con stakeholders. Lo importante es que el equipo sale de esa fase con tres cosas que permiten un contrato:

• Un objetivo claro (por ejemplo: capturar tareas rápido y revisar listas semanalmente).
• Un alcance inicial y un no‑alcance explícito (por ejemplo: “sin colaboración multiusuario en v1”, “sin calendarios externos”).
• Un vocabulario común (“tarea”, “lista”, “inbox”, “completada”, “próxima acción”).

Si esto no está, escribir una spec solo congelará incertidumbre.

Paso 1: el equipo crea la constitución (guardrails) para no negociar calidad en cada PR

El tech lead propone una constitución corta: estrategia de testing, convenciones de naming, límites de performance razonables, reglas de seguridad (autorización siempre en endpoints sensibles, PII fuera de logs), y un estándar mínimo de CI.

Impacto inmediato: cuando luego aparezca un PR con “ya lo testeará QA”, el equipo tiene un contrato transversal para decir que no. No es debate; es guardrail.

Paso 2: escriben la spec como contrato funcional (qué debe pasar y qué no)

En lugar de partir por pantallas, el equipo parte por semántica. El PM y el QA ayudan a traducir intención a criterios verificables; el backend y frontend ayudan a detectar ambigüedades.

Ejemplos de contenido típico (no exhaustivo) en esta app:

• Invariantes
  • Una tarea no puede estar simultáneamente en Inbox y en una Lista.
  • Completar una tarea no debe eliminar historial relevante (p. ej., fecha de completado).
• Criterios de aceptación
  • “Crear tarea en Inbox desde texto” crea una tarea con estado Inbox.
  • “Mover tarea de Inbox a Lista” elimina el estado Inbox y asigna Lista.
• Edge cases
  • Una tarea vacía o sin acción (“mejorar mi vida”) no se puede promover a “Próxima acción” (si ese concepto existe en v1) o se marca como “pendiente de clarificar”.

El checkpoint aquí es explícito: el equipo lee la spec y decide si está cerrada lo suficiente como para implementar sin inventar reglas. Cuando alguien dice “depende”, eso se convierte en texto y ejemplos. La spec no busca ser perfecta; busca ser suficiente.

Paso 3: derivan el plan técnico para fijar restricciones que no quieren que aparezcan por accidente

Con la spec estable, el tech lead y el equipo escriben un plan: arquitectura, contratos y decisiones con coste de cambio.

En nuestra app, el plan podría fijar:

• Modelo de dominio (entidades y reglas donde viven invariantes).
• Contratos de API (paginación obligatoria, errores tipados, versionado si aplica).
• Persistencia (migraciones desde el día uno, índices para listados por estado/lista).
• Observabilidad (logs estructurados, métricas básicas de latencia en endpoints críticos).
• Seguridad (autorización por usuario, validaciones de input, rate limit si aplica).

Checkpoint técnico: si aparece una decisión que va a condicionar el diseño (por ejemplo, “soportar offline” o “consistencia eventual”), se discute ahora y se escribe. Si no, acabará apareciendo como parche cuando ya haya código.

Paso 4: descomponen en tasks pequeñas, trazadas a spec/plan

Aquí el equipo convierte el contrato en trabajo revisable. No hay “implementar app de tareas”. Hay tareas que se pueden auditar.

Ejemplos de tasks que suelen salir bien:

• “Caso de uso: CreateInboxTask(text). Validaciones + tests unitarios de dominio.”
• “Caso de uso: MoveTaskToList(taskId, listId). Regla: deja de ser Inbox. Tests de transición.”
• “API: GET /tasks?state=inbox con paginación. Contract tests del esquema.”
• “UI: Inbox list con estado vacío y loading. Tests de UI básicos si procede.”

Cada task define su done: qué parte de la spec cubre, qué restricciones del plan aplica y qué tests deben existir.

La organización práctica suele ser simple: el equipo mantiene los artefactos en el soporte que ya usa (Notion/Confluence/docs en repo), define una forma de versionarlos (historial, cambios aprobados, PRs si están en Git) y hace que cada PR o cambio trace la task correspondiente. Con eso, la trazabilidad deja de ser un deseo. Con eso, la trazabilidad deja de ser un deseo.

Paso 5: implementan por PRs pequeños y revisan contra contrato, no contra intuición

El equipo implementa una task por PR. Da igual si el código lo escribe una persona o se apoya en IA: el mecanismo es el mismo.

En review, las preguntas cambian:

• ¿Cumple los criterios de aceptación de la spec?
• ¿Respeta los invariantes del dominio?
• ¿Introduce comportamiento no especificado?
• ¿Respeta las restricciones del plan (contratos, arquitectura, seguridad)?
• ¿Qué evidencia aporta (tests, checks, contratos)?

Esto tiene un efecto colateral muy valioso: reduce el “debate de estilo” y aumenta el “debate de semántica”, que es donde se paga el mantenimiento.

Paso 6: validan: cada criterio de aceptación tiene evidencia

Cuando “terminan” una iteración, la validación no es una demo bonita. Es comprobar que el sistema hace lo que el contrato dice.

En esta app, esa evidencia suele quedar repartida así:

• Unit tests para invariantes y transiciones (dominio).
• Integration tests para casos de uso completos (persistencia + lógica).
• Contract tests para APIs (esquemas y errores).
• E2E (si aplica) para flujos críticos (crear → mover → completar).

El QA deja de ser el último filtro manual y pasa a ser un coproductor del contrato: ayuda a que los criterios sean verificables y a que los tests cubran casos que suelen escaparse.

Paso 7: cuando cambia el producto, se actualiza la spec primero

A mitad de proyecto, negocio decide: “una tarea puede pertenecer a varias listas” o “queremos tareas recurrentes”. En un equipo sin contrato, esto suele acabar en patches. Con SDD, el movimiento es otro:

1. se actualiza la spec (nuevas reglas, nuevos ejemplos),
2. se revisa el plan (qué decisiones cambian),
3. se regeneran/ajustan tasks,
4. se implementa por PRs pequeños con evidencia.

Esto no evita el coste del cambio. Evita el coste oculto: inconsistencias, regresiones y “comportamientos fantasma” que nadie prometió pero alguien introdujo.

Ese es el núcleo de SDD en la práctica: no una secuencia ceremonial, sino un sistema de control. El equipo produce un contrato, deriva trabajo revisable, implementa con evidencia y mantiene sincronizada la intención con lo que el sistema realmente hace.