Esta guía cierra una serie. Si llegaste directo, conviene tener el contexto antes de seguir — porque aquí no explico qué es SDD ni por qué importa: lo voy a dar por sabido y vamos directo a la ejecución con el equipo.
- SDD no reemplazó al QA: lo promovió — Parte 1 — tu nueva posición frente al dev y al PO.
- SDD no reemplazó al QA: lo promovió — Parte 2 — frente al arquitecto y al Scrum Master. Los 7 guardrails y las 3 ceremonias salen de acá.
- Spec-Driven Development en la práctica — la guía hermana: cómo haces tu primer ciclo, sola, con GitHub Spec Kit.
Esa última guía te enseñó a hacerlo tú. Esta te enseña a hacerlo con tu equipo entero — que es un problema completamente distinto. Hacer SDD sola es una herramienta. Hacer SDD en equipo es un cambio de proceso. Y los cambios de proceso no fallan por la herramienta: fallan por la gente que no entendió qué cambió.
Para el QA — junior o senior — que va a ser la primera persona del equipo en llevar SDD a la mesa. No necesitas ser el líder formal. Necesitas entender primero qué cambia, porque vas a ser quien lo explique en el refinamiento, en la daily y en la retro. Esta es la conversación que llevas al próximo sprint planning para entrar bien preparada.
Antes de los pasos — la prueba de que esto no es humo
Te voy a pedir mucho en esta guía: cambiar plantillas, recalibrar ceremonias, pelear con la gerencia cuando la velocity se ilumine. Antes de pedirte nada, te muestro por qué vale la pena.
Quería responder una pregunta concreta: cuando un spec de SDD sale flojo, ¿es culpa de quién lo escribe o de la plantilla con la que lo escribe? Si es culpa del autor, la solución es contratar gente más senior. Si es culpa de la plantilla, la solución es arreglar la plantilla — y eso lo puede hacer cualquier equipo en una tarde. La diferencia, para vos que vas a llevar esto a tu equipo, es enorme.
Para responderla armé un experimento controlado. Lo cuento en detalle en la guía hermana; acá va la versión corta, porque su resultado es la base de todo lo que sigue. Pero antes, tres palabras que voy a repetir toda la guía:
- Spec (de especificación): el documento que describe un feature con tanto detalle que la IA puede generar el código y los tests a partir de él. Es el insumo central de SDD.
- Constitución: el documento donde tu equipo escribe sus reglas de calidad no-negociables. Lo montamos paso a paso en el Paso 1; por ahora alcanza con saber que es “la lista de reglas que ningún spec puede romper”.
- Template del spec: la plantilla sobre la que escribes ese spec — qué secciones tiene, qué te obliga a completar y qué te deja saltear.
El experimento, entonces. Tomé un feature real — POST /api/users/register, el endpoint de registro con email, username, password y edad — y generé su spec dos veces. Mantuve todo idéntico entre las dos corridas: la misma feature, las mismas respuestas a las preguntas de clarificación, la misma constitución, el mismo checklist de 36 ítems para medir el resultado. La única cosa que cambié fue el template. La primera vez usé la plantilla genérica que Spec Kit trae de fábrica. La segunda, una que reestructuré para forzar las técnicas de diseño de pruebas (partición de equivalencia, valores límite, tabla de decisión). Misma persona, mismo día, misma cabeza — solo cambió la plantilla.
Después medí, con el mismo checklist, cuánto de las reglas de la constitución respetaba cada spec generado. A eso le llamo “conformidad”:
Trece ítems del checklist que el primer spec dejaba sin cumplir, el segundo los cumplía. Y no se cerraron porque el autor fuera más inteligente la segunda vez — el autor, las respuestas y el checklist fueron idénticos. Se cerraron con más estructura. El template alineado pedía explícitamente tablas de partición de equivalencia, valores límite, tabla de decisión, catálogo de errores y máquina de estados. El genérico no las pedía. Si el template no las pide, el autor las olvida. Si las pide, aparecen.
De nada sirve escribir las reglas de calidad en un documento aparte si la plantilla del spec no te obliga a cumplirlas. La plantilla es donde las reglas se vuelven reales — o se quedan en decoración.
Traducido a algo accionable: no alcanza con escribir la constitución y pedirle al equipo que “la tenga en cuenta”. Hay que meter cada regla dentro de la plantilla, como una sección obligatoria que el spec no deja vacía. Esa es la idea que sostiene toda la guía — y cada paso que sigue es una forma de hacerla operativa con el equipo.
No te pido que me creas los números: están para que los reproduzcas. En el
repo sdd-demo-registro
vas a encontrar las dos versiones del experimento como ramas separadas de Git
— 001-user-registration (el spec del 42%) y 002-user-registration (el del
97%) — más la constitución, los dos templates y el checklist de 36 ítems con
el que medí cada una. Comparando las dos ramas ves exactamente qué secciones
le agregué al template para subir del 42% al 97%. Sin humo: la evidencia está
ahí.
El mapa del ciclo — qué vamos a montar
Un ciclo SDD multi-rol tiene cinco piezas. Las vamos a montar en orden, porque cada una depende de la anterior. Si saltas una, la siguiente se rompe en silencio.
- La constitución del equipo — las reglas no-negociables, incluidos los 7 guardrails arquitectónicos.
- El template que obliga a cumplir — la plantilla del spec que convierte la constitución en columnas obligatorias.
- El refinamiento multi-rol — donde QA, arquitecto, dev y PO auditan el spec ANTES del pipeline.
- El pipeline y su auditoría — la cadena de agentes que genera código y tests, y cómo la auditas.
- Las ceremonias recalibradas — daily y retro con vocabulario y métricas nuevas.
Y al final, los anti-patrones: las cinco formas concretas en que este experimento se hunde, para que las veas venir.
El error más común es querer transformar todo de golpe. No. El primer ciclo es un piloto: un módulo, un feature, un equipo chico. Montas constitución y template una vez (pasos 1 y 2), y los pasos 3-5 los corres sobre UN feature real. Cuando ese ciclo cierra bien, recién ahí escalas. La velocidad mata este cambio.
Paso 1 — La constitución del equipo
La constitución es el documento donde viven las reglas que la IA no puede romper. No es un manifiesto inspirador: es un contrato técnico. En Spec Kit vive en .specify/memory/constitution.md y la IA la lee en cada generación.
Tu constitución tiene dos capas. La primera son los principios de calidad funcional — en mi experimento fueron cinco, todos no-negociables: ISTQB-first (toda spec trae sus técnicas de diseño de prueba), cero happy-path-only, estados siempre explícitos, prohibido el error leakage, y gatekeeping (ninguna spec pasa sin checklist). Esos los cubrí en la guía hermana.
La segunda capa es la que agrega el equipo, y es la que casi nadie escribe: los 7 guardrails arquitectónicos. Sin ellos, la IA toma decisiones de arquitectura sola, una por feature, sin saber que las está tomando. El resultado lo viste en la Parte 2: un sistema con 4 estrategias de cache, 3 formas de serializar errores y 2 patrones de query — todos con tests verdes, ninguno alineado. Arquitectura por acumulación.
Estos 7 guardrails no los inventas tú. Los recibes del arquitecto, una sola vez, como contrato del módulo. Tu trabajo es exigir que cada spec los traiga explícitos.
Los 7 guardrails arquitectónicos — qué exige cada uno
-
Estrategia de cache — dónde se guarda la copia rápida (memoria, Redis, base), cuánto vive, qué la invalida, y qué pasa cuando muchos usuarios piden el mismo dato y la copia no existe todavía.
-
Patrón de manejo de errores — qué excepciones lanza, qué códigos HTTP devuelve, qué estructura tiene el payload de error, qué se loggea al fallar.
-
Patrón de queries a base de datos — join, batch read, o el camino malo (N+1). La spec dice cuál es aceptable. El test pasa con 2 registros y muere con 2000.
-
Estrategia de observability — qué se loggea, qué métricas se exponen, qué traces se emiten, a qué nivel de detalle.
-
Bounded context — a qué módulo pertenece, qué módulos puede tocar, qué APIs internas consume, qué eventos publica o lee.
-
Contratos hacia afuera — qué APIs expone (con versión), qué consume (con versión), qué pasa si una API consumida cambia su contrato.
-
Presupuesto de rendimiento — latencia máxima, throughput mínimo, memory footprint, y qué hace el sistema cuando uno de los tres se excede.
Un archivo constitution.md versionado en el repo, con los principios
funcionales del QA + los 7 guardrails del arquitecto. Firmado por ambos. Si tu
equipo no tiene arquitecto formal, los guardrails los define quien tome las
decisiones técnicas transversales — pero alguien los tiene que firmar.
Paso 2 — El template que obliga a cumplir
Acá está el corazón de todo, y es lo que el experimento probó: si la plantilla con la que escribes el spec no te obliga a aplicar las reglas de la constitución, esas reglas no se aplican. Por más que estén escritas en otro documento, la gente las olvida bajo presión de sprint.
El template del spec —en Spec Kit es un archivo, .specify/templates/spec-template.md— es donde la constitución se vuelve real. La diferencia entre mi 42% y mi 97% fue exactamente esto: pasé el template de 128 a 259 líneas agregando secciones obligatorias. No le pedí a nadie que fuera más cuidadoso. Le di columnas vacías que el spec obliga a llenar — y lo que el template pide, aparece.
La clave es entender por qué funciona: una tabla vacía es una pregunta que el autor no puede esquivar. Una sección de prosa libre es una invitación a escribir lo fácil y olvidar lo difícil. El template no te hace más inteligente — te hace completa.
Si dejas el template genérico y le pides al equipo que “tenga en cuenta la constitución”, perdiste antes de empezar. La gente, bajo presión de sprint, va a escribir prosa libre y la prosa libre no es auditable a escala de equipo. Reescribir el template es el trabajo de una tarde. Es la tarde de mayor ROI de todo el ciclo.
Un spec-template.md con una sección obligatoria por cada principio de la
constitución y por cada guardrail. Pruébalo: genera un spec de prueba y
verifica que NO se pueda completar dejando huecos en lo que importa. Si se
puede dejar vacío, el template todavía no obliga a cumplir nada.
Paso 3 — El refinamiento multi-rol
Acá es donde el ciclo se vuelve de equipo. El refinamiento deja de ser una charla de estimación y se convierte en el evento más crítico del sprint — porque después del refinamiento, el pipeline ejecuta sin humanos en el medio. Lo que no se cazó acá, se acumula como deuda técnica para siempre.
El cambio de fondo: antes la US salía del refinamiento con 70% de claridad y el 30% restante se descubría escribiendo código. Con SDD ya no hay nadie escribiendo código que descubra nada. La US tiene que salir con 100% de claridad o no sale.
Tu trabajo concreto en este refinamiento es correr la auditoría pre-spec. Llegas con tres preguntas, y si alguna se responde con “no”, la US no entra al pipeline:
Refinamiento — las 3 preguntas que llevas
-
¿Esta US tiene los 7 huecos funcionales cerrados Y los 7 guardrails arquitectónicos explícitos? Si la respuesta es no, no sale del refinamiento.
-
¿Quién es el dueño de cada guardrail aplicable a esta US? El QA y el arquitecto firman el pre-spec audit antes de que entre al pipeline.
-
¿Esta US toca un módulo donde ya detectamos drift arquitectónico antes? Si sí, suma una revisión cross-feature antes de entrar al pipeline.
Un spec auditado y firmado (QA + arquitecto) listo para el pipeline. “Firmado” puede ser un check en el ticket, un approval en el PR del spec, lo que tu equipo use — pero tiene que haber un acto explícito de “esto pasó la auditoría”. Sin firma, no hay gatekeeping.
Paso 4 — El pipeline y su auditoría
El pipeline es la cadena de agentes que toma el spec y produce código + tests. Un pipeline típico tiene cuatro piezas: un orchestrator que coordina, un code generator, un test generator y un validator que verifica que código y tests coincidan.
Suena prolijo. Y acá está la trampa que casi nadie audita: ¿qué pasa si el code generator y el test generator usan el mismo prompt base con la misma spec?
Pasa la trampa circular, pero a nivel infraestructura. Los tests verifican lo que el código hace —no lo que debería hacer— porque ambos artefactos nacen del mismo cerebro mirando la misma fuente. El validator da verde. Todo el mundo feliz. Y el bug viaja a producción con la bendición de una suite de tests que nunca lo iba a cazar.
Cualquier sistema que genere código y tests desde una misma fuente, sin separación de cerebro, tiene la trampa circular incorporada por diseño. Auditar features sin auditar el pipeline es como hacer code review línea por línea sin haber leído nunca el framework subyacente.
Tu trabajo en este paso es la separación de cerebro: asegurar que el test generator no derive del mismo razonamiento que el code generator. En la práctica, eso significa que los tests se anclen al spec (a las tablas de equivalencia, a la máquina de estados, al catálogo de errores que escribiste en el Paso 2), no a lo que el código terminó haciendo. El spec es la fuente de verdad independiente. Si los tests nacen del spec y el código nace del spec, pero por caminos separados, la trampa se rompe.
Un documento de una página: quién diseñó el pipeline, qué prompt usa cada agente, qué fuente comparten, y dónde está garantizada la separación de cerebro entre code y test generator. Si nadie en el equipo puede contestar esto, ese es tu primer hallazgo — y es grande.
Paso 5 — Las ceremonias recalibradas
Con el ciclo corriendo, dos ceremonias dejan de medir lo que importa: la daily y la retro. (El refinamiento ya lo cubrimos en el Paso 3; el sprint review no cambia — y de eso hablamos en los anti-patrones.)
El problema de fondo es la velocity. Cuando el tiempo de implementación deja de ser el cuello de botella, los puntos del sprint explotan — 200%, 300% — y el dashboard se ilumina. Pero esa velocity ya no mide la salud del equipo: mide cuántas features cruzaron el pipeline, no si cruzaron bien. Y los bugs caros aparecen tres sprints después, cuando ya nadie los conecta con la spec que los originó.
Equipos que celebran velocity 300% con SDD están midiendo lo equivocado y no lo saben todavía. La presión de “estamos rápidos, no frenes” va a venir desde arriba en cuanto el dashboard brille. Tu trabajo es darle al SM las métricas nuevas ANTES de que esa presión llegue.
No le des al Scrum Master una clase teórica. Dale las preguntas nuevas, ceremonia por ceremonia, y llévalas tú a la próxima retro con datos reales:
Daily — las 3 preguntas nuevas
-
¿En qué fase del ciclo SDD está cada persona — escribiendo spec, auditando spec, esperando pipeline, auditando output del pipeline? La unidad de progreso ya no es el código: es la claridad de la spec.
-
¿Hay alguna spec esperando entrar al pipeline con guardrails incompletos? Ese es el verdadero blocker del sprint — no la velocity.
-
¿Alguien encontró señales de trampa circular en el output esta semana? Suben al SM y al arquitecto de inmediato.
Retro — las 3 preguntas nuevas
-
¿Cuántas specs entraron al pipeline con guardrails 100% completos versus parciales? Esta métrica reemplaza, en parte, a la velocity.
-
¿Cuántos bugs caros del último mes pudimos rastrear a una spec específica? Y de esos, ¿cuántos eran prevenibles con los 7 huecos o los 7 guardrails?
-
¿Hay drift arquitectónico cross-feature que se acumuló este mes y nadie lo nombró antes? Esta pregunta evita la deuda técnica silenciosa.
Un set de métricas nuevas acordado con el SM, reemplazando o complementando la velocity en la retro. Lo mínimo viable: ”% de specs con guardrails completos” y “bugs caros rastreados a su spec de origen”. Con esas dos ya cambias la conversación.
Los 5 anti-patrones que hunden el primer ciclo
Montaste los cinco pasos. Ahora cuido que no se te caiga. Estos son los cinco errores que vi —o anticipo— y que matan el experimento en silencio.
1. El carrito en memoria — guardrail de cache ausente
Una feature cachea en memoria del servidor porque la spec dijo “rápido”. Hay tres instancias detrás del load balancer, así que el dato está en una memoria y no en las otras. El usuario ve el carrito vacío a veces sí, a veces no. Los tests pasaron porque corrieron contra una sola instancia. Es un bug arquitectónico, no funcional — y se previene con el guardrail de cache en la spec, no con más tests.
2. Celebrar la velocity 300%
El dashboard se ilumina, la gerencia festeja, y nadie mira que los bugs caros también subieron. Si celebras velocity sin la métrica de “bugs rastreados a su spec”, estás midiendo cuántas features cruzaron el pipeline, no cuántas cruzaron bien.
3. Explicarle SDD al cliente en el sprint review
El review sigue exactamente igual: el stakeholder evalúa el producto, no el proceso. Cualquier intento de “explicarle SDD al cliente” es ruido — y casi siempre aparece cuando algo del proceso anda mal y el equipo busca excusas. Defiende el review como el espacio donde el método no se discute, solo el resultado.
4. Template genérico con constitución 'recomendada'
Dejar el template de fábrica y pedirle al equipo que “tenga en cuenta” la constitución. Ya lo viste: 42% versus 97%. La constitución que nadie obliga a cumplir es decoración. Si el template no obliga a llenar la tabla, la tabla queda vacía.
5. Pipeline con un solo cerebro
Code generator y test generator compartiendo prompt y fuente. La trampa circular incorporada por diseño: los tests validan lo que el código hace, no lo que debería. El validator da verde sobre un acuerdo entre dos artefactos que piensan igual. Separación de cerebro o el pipeline es teatro.
El checklist del primer ciclo
Imprímelo. Llévalo a la reunión. Tacha a medida que avanzas.
- Constitución versionada con principios funcionales + 7 guardrails, firmada por QA y arquitecto.
- Template reestructurado: una sección obligatoria por principio y por guardrail. Probado: no se puede dejar huecos en lo que importa.
- Refinamiento multi-rol con los cuatro roles. Pre-spec audit firmado antes del pipeline.
- Pipeline auditado: documentado quién lo diseñó, qué prompt usa cada agente, dónde está la separación de cerebro.
- Métricas nuevas acordadas con el SM para la daily y la retro.
- Un solo feature como piloto. No transformes todo de golpe.
- Los 5 anti-patrones revisados con el equipo antes de arrancar.
Cierre
SDD no te reemplazó. Te promovió. Pasaste de ser el último filtro —el que revisa cuando ya está todo hecho— a ser el primero: el que define, en el refinamiento, qué tiene derecho a entrar al pipeline. Pero esa promoción solo se hace efectiva cuando ocupas la nueva posición de verdad, frente a los cuatro roles, y cuando el equipo te ve hacerlo.
Tienes el mapa. Tienes los pasos. Tienes la prueba de que funciona (42% → 97%, cambiando una variable). Lo único que falta es la parte que ninguna guía puede hacer por ti: levantar la mano en el próximo refinamiento y hacer la pregunta que nadie hizo.
La calidad de un equipo entero adoptando SDD depende, más que nunca, del QA que entendió primero qué cambió. Esa eres tú. Ahora ve y lidéralo.