Spec-Driven Development en la práctica — tu primer ciclo completo desde la mirada del QA (con GitHub Spec Kit)

Esta guía es la tercera pieza de una serie. Si llegas directo y no leíste las anteriores, conviene pasar primero por ahí:

• Spec-Driven Development para QA — qué es SDD, por qué importa para tu rol, el cambio cultural.
• GitHub Spec Kit a fondo — la herramienta que vamos a instalar y usar en esta guía: qué es, qué hace, qué NO hace.

Esta guía asume que ya tienes ese contexto. Si solo quieres practicar los comandos puedes saltar directo, pero algunos conceptos (constitución, compuertas, las 4 técnicas ISTQB) van a aparecer como si ya los conocieras.

Hoy bajamos a tierra. Pero antes de tocar un comando, te quiero contestar la pregunta que se hace cualquier QA cuando ve una herramienta nueva: ¿para qué me sirve esto un lunes de sprint?

El caso concreto — un lunes a la mañana

Te llega esto en Jira:

TICKET-1042 — Agregar endpoint de registro de usuario para Academia sin Humo, nuestra plataforma pública de práctica para automatización QA. Inputs: email, username, password, age. Reglas de negocio: a confirmar.

Tu cabeza arranca. ¿Qué validaciones? ¿Edad mínima? ¿Ya hay máquina de estados o se inventa ahora? ¿Cómo manejamos colisiones de email/username sin filtrar info? ¿Cuánto dura el link de verificación? ¿Qué pasa si el email tiene un +alias?

Hoy las opciones que tienes son tres, y ninguna buena:

• Pedir reunión con el PM → pierde la mañana de los dos, y muchas preguntas siguen abiertas porque el PM tampoco las pensó.
• Arrancar sin preguntar → tres sprints después aparecen 4 bugs en prod por reglas que nadie escribió.
• Escribir casos de prueba “razonables” basados en suposiciones → el dev implementa otras suposiciones, los tests no cazan nada y los bugs sí.

Con SDD el flujo cambia:

Qué ganas concretamente:

• Los bugs de requerimientos desaparecen — la categoría más cara en cualquier proyecto. SDD los caza en la fase de clarificación, no en producción.
• El test plan ya existe: los acceptance scenarios son tus casos, las tablas de equivalencia son tus particiones, la state machine son tus tests de transición. Lo que antes te tomaba un día, ahora viene generado.
• La review de PR tiene una vara objetiva: ¿este código honra el spec? Si no, vuelve. Sin debate.
• Los tests sobreviven al refactor: si el dev cambia la implementación pero el spec se mantiene, los tests siguen siendo válidos. Antes cada refactor te rompía media suite.

¿Cuándo sí y cuándo no usar SDD?

SDD no es bala de plata. Tiene casos donde brilla y casos donde estorba.

Para qué tipos de pruebas te sirve directamente:

Lo que vas a tener al terminar esta guía

1. Setup — instalar Spec Kit en 3 minutos

Spec Kit es un CLI que se distribuye como paquete Python. Para correrlo no necesitas instalar Python ni gestionar entornos virtuales — usamos uv, que es el gestor moderno de paquetes Python de Astral. Si no lo tienes, instálalo primero:

brew install uv

Verifica:

uv --version

Ahora arranca un proyecto nuevo. Vamos a crear un demo de registro de usuario, pero el flujo es el mismo para cualquier feature:

mkdir -p ~/Proyectos/sdd-demo-registro
cd ~/Proyectos/sdd-demo-registro
uvx --from git+https://github.com/github/spec-kit.git specify init .

Spec Kit te va a hacer dos preguntas:

1. ¿Qué agente vas a usar? Selecciona Claude Code. Si usas Copilot o Cursor, elige el que corresponda. Spec Kit instala los slash commands específicos para tu agente.
2. ¿Inicializar git? Sí. Spec Kit usa branches para aislar features y la integración es automática.

Cuando termina, vas a tener una estructura como esta:

sdd-demo-registro/
├── .specify/
│   ├── memory/              ← donde vive la constitución del proyecto
│   ├── templates/           ← los templates que usa para generar artefactos
│   └── scripts/             ← scripts de soporte
├── .claude/
│   └── commands/            ← los slash commands de Spec Kit, cargados en Claude Code
└── (tu proyecto aquí)

Abre el directorio en Claude Code:

claude

Y verifica que los slash commands se cargaron correctamente:

/speckit-

Debería autocompletar con /speckit-constitution, /speckit-specify, /speckit-clarify, /speckit-plan, /speckit-tasks, /speckit-implement, entre otros.

cp ~/Proyectos/proyecto-anterior/.specify/memory/constitution.md \
   ~/Proyectos/proyecto-nuevo/.specify/memory/constitution.md

2. La constitución de tu proyecto — donde tu rol QA cambia el juego

La constitución es el primer artefacto que vas a escribir, y es el más importante. Es un archivo .md con los principios non-negotiable de tu proyecto. Spec Kit lo lee al inicio de cada comando y los usa como reglas que la IA no puede violar.

Aquí es donde tu rol como QA toma protagonismo. Los devs van a poner principios sobre arquitectura, naming, dependencias. Tú vas a poner principios sobre calidad y verificación.

Generala con:

/speckit-constitution

Spec Kit te va a pedir que listes los principios. Esto NO lo improvises: piensa qué es no-negociable en tu proyecto desde la mirada QA. Para el demo de registro, yo definí estos cinco:

P1. ISTQB-FIRST Antes de generar código, todo spec debe aplicar las 4 técnicas Cap. 4 del syllabus ISTQB: partición de equivalencia, valores límite, tabla de decisión, transición de estados. Si una de las cuatro no aplica, el spec debe declarar explícitamente por qué.

P2. ZERO HAPPY-PATH-ONLY Todo caso de uso debe cubrir las 4 categorías mínimas: válido típico, valor límite, inválido por reglas de validación, error de sistema. Specs con solo el camino feliz se rechazan.

P3. STATES MUST BE EXPLICIT Si una entidad tiene estados, el spec debe declarar el conjunto cerrado de estados permitidos, las transiciones permitidas, y las transiciones prohibidas con su justificación. Lo que no está declarado prohibido, la IA va a asumir que es permitido.

P4. ERROR LEAKAGE FORBIDDEN Las respuestas de error visibles para el cliente no pueden revelar: qué campo causó el conflicto, stack traces, identificadores internos, queries, ni detalles de infraestructura. Las diferencias de timing entre “existe” y “no existe” cuentan como leak.

P5. GATEKEEPING BEFORE CODE /speckit-clarify es obligatorio antes de /speckit-plan. Un checklist constitution-grade es obligatorio antes de /speckit-implement. Saltarse cualquiera de los dos invalida el ciclo.

Spec Kit guarda la constitución en .specify/memory/constitution.md y la versiona (v1.0.0). Cada vez que corras un comando posterior, esos cinco principios van a estar en el contexto del agente.

3. /speckit-specify — tu primer spec generado

Con la constitución lista, genera tu primer spec. Este es el comando que define qué se va a construir, expresado en lenguaje de negocio (sin código).

/speckit-specify

Spec Kit te va a pedir la descripción del feature. Para el demo voy a usar un caso del proyecto Academia sin Humo — una plataforma pública con bugs intencionales para que practiques automatización contra una app real. El ticket que llegó al sprint:

TICKET-1042 — Agregar endpoint de registro de usuario para Academia sin Humo. Inputs: email, username, password, age. Reglas de negocio: a confirmar.

Cuando termina de generar, Spec Kit hace algo crucial: si detecta ambigüedades en tu input, te pregunta antes de seguir. La cantidad y el contenido de las preguntas dependen de:

• Qué tan ambiguo es tu input
• Qué reglas declara tu constitución (Spec Kit se asegura de que el spec las pueda cumplir)
• Qué información falta para definir la lógica de negocio

En mi corrida del demo, recibí 3 clarificaciones. Las tuyas pueden ser distintas en cantidad y contenido. Las mías fueron:

Esto es /speckit-clarify aplicado implícitamente. Spec Kit lo dispara dentro de /speckit-specify cuando detecta ambigüedades. Es la primera compuerta del principio P5 de tu constitución funcionando en automático.

Para el demo, mis respuestas fueron:

• Q1: verificación pendiente por email — estados: pending_verification → active | expired
• Q2: ambos — email y username globalmente únicos
• Q3: 16 años — GDPR digital consent threshold

Después de que respondes las preguntas, Spec Kit genera dos archivos:

• specs/001-user-registration/spec.md — el spec en sí
• specs/001-user-registration/checklists/requirements.md — un checklist de calidad que valida si el spec está bien escrito

Spec Kit también automatiza algo que vas a agradecer: crea una rama (branch) en tu repositorio git con el nombre 001-user-registration. Lo hace a través de un git hook — un pequeño script que git ejecuta automáticamente cuando ocurren ciertos eventos (en este caso, al generar el spec).

¿Por qué importa esta convención de una feature por rama? Imagínate que tu equipo está trabajando en tres features al mismo tiempo: registro, login y recuperación de contraseña. Si todos esos specs vivieran en la rama main, los archivos de cada feature se mezclarían y revisar qué cambió por qué razón sería un infierno.

Con una rama por feature obtienes cuatro cosas que importan:

• Cada spec, plan, tareas y código del feature viven aislados en su propia rama.
• El equipo trabaja en paralelo sin pisarse — tú en registro, otra persona en login, sin conflictos.
• El Pull Request final muestra solo lo que cambió por ese feature específico, no una mezcla.
• Si decides descartar el feature, borrar la rama lo elimina todo en un comando — sin dejar rastros sueltos en main.

Es la misma convención que usan equipos serios de desarrollo desde hace años. Spec Kit la trae instalada por defecto para que no tengas que pensarlo.

4. Revisar antes de generar código — donde la IA todavía te necesita

Aquí es donde la mayoría de la gente comete el primer error: leer el spec por encima, decir “se ve bien”, y saltar a /speckit-plan. Si haces eso, estás condenando el ciclo.

Tu trabajo en este paso es leer el spec.md línea por línea y responder dos preguntas:

Una vez que el spec está limpio, genera un checklist constitution-grade con /speckit-checklist. Este checklist NO es el genérico que ya viene en requirements.md. Es uno específico que valida tu spec contra los principios que pusiste en tu constitución.

/speckit-checklist Genera un checklist constitution-grade que valide explícitamente
los 5 principios de la constitución: P1 ISTQB-FIRST con las 4 técnicas Cap. 4 (con
tablas), P2 ZERO HAPPY-PATH-ONLY con las 4 categorías, P3 STATES MUST BE EXPLICIT
con allowed + forbidden transitions, P4 ERROR LEAKAGE FORBIDDEN con catálogo de
errores, P5 GATEKEEPING como bloqueante. Cada item verificable contra spec.md, con
cross-reference a la sección donde se cumple, o marcado como [Gap] si no.

Spec Kit genera specs/001-user-registration/checklists/constitution.md con típicamente entre 30 y 40 ítems agrupados por principio. Cada uno marcado como ✅ Satisfecho, ⚠️ Parcial, o ❌ Gap.

Lo que hagas en este paso decide la mitad de la calidad del ciclo. La otra mitad la decide la fase de plan, que viene a continuación.

5. De la spec al código — /speckit-plan, /speckit-tasks, /speckit-implement

Con el spec validado, las siguientes tres fases bajan progresivamente al código.

/speckit-plan — el diseño técnico

/speckit-plan

Genera specs/001-user-registration/plan.md. Este archivo traduce tu spec a decisiones técnicas: qué stack, qué módulos, qué endpoints, qué tabla de base de datos, qué librerías. Es lo que en cualquier proyecto sería el documento de “arquitectura del feature”.

Tu trabajo como QA en este paso:

• Verificar que las decisiones técnicas honren los principios constitucionales. Si la constitución dice “no leak en errores” (P4), el plan debe declarar el catálogo de errores con shape genérico, NO una página de Sentry expuesta al cliente.
• Verificar que los puntos de testing estén identificados. ¿Dónde van los tests unitarios? ¿Qué cubre integración vs end-to-end? Si el plan no lo dice, vas a heredar una suite improvisada.

/speckit-tasks — el desglose ejecutable

/speckit-tasks

Genera specs/001-user-registration/tasks.md: una lista ordenada de tareas atómicas, cada una pequeña y verificable. Es la traducción del plan en items que cualquiera del equipo puede ejecutar sin decisiones grandes pendientes.

Tu trabajo como QA:

• Confirmar que cada tarea tiene criterios de aceptación claros, no solo descripción.
• Confirmar que las tareas de testing aparecen junto a las de implementación, no relegadas al final como un bloque “agregar tests”.

/speckit-implement — donde la IA escribe código

/speckit-implement

Aquí es donde la IA finalmente escribe código. Toma las tareas, las ejecuta una por una, y genera commits.

6. Las 4 técnicas ISTQB — dónde aplicar cada una en el ciclo

Esta es la sección que más me piden. Si tu mirada QA está formada en ISTQB Cap. 4, sabes que las 4 técnicas no son intercambiables: cada una sirve para un tipo de hueco distinto. SDD te da los puntos exactos donde aplicarlas.

Partición de equivalencia → en spec.md (sección Inputs)

Cada input del spec debe declarar sus clases válidas e inválidas. Para el demo:

Dónde aplicarla: cuando lees spec.md después de /speckit-specify, busca si los Functional Requirements declaran estas clases. Si dicen “el email debe ser válido” sin definir qué es válido, marca gap.

Valores límite → también en spec.md (sección Boundary Values)

Para cada input numérico o con longitud, declarar los tres valores críticos: valor-1 / valor / valor+1. Para el demo:

Dónde aplicarla: el spec debe enumerar estos valores explícitamente, no decir “validar el rango”. La razón: si la implementación usa >= cuando debería usar >, los tests de boundary lo cazan al primer commit.

Tabla de decisión → en spec.md (sección Decision Table) o en plan.md

Cuando el sistema toma decisiones basadas en combinaciones de inputs, una tabla de decisión las hace exhaustivas. Para el registro:

Dónde aplicarla: cuando lees spec.md, debe haber una tabla así (o equivalente). Si solo hay prosa describiendo “se valida cada input”, marca gap. La tabla es el contrato de la lógica.

Transición de estados → en spec.md (sección State Machine)

Si tu feature tiene estados (pendiente, activo, expirado, eliminado), la spec debe declarar los tres bloques completos:

Estados permitidos (conjunto cerrado):

• pending_verification — cuenta creada, email no verificado, sign-in rechazado
• active — email verificado, cuenta usable
• expired — ventana de verificación vencida, sign-in rechazado

Transiciones permitidas:

Transiciones PROHIBIDAS (la mitad que casi nadie escribe):

• active → pending_verification — no se puede regresar una cuenta verificada
• active → expired — las cuentas verificadas no expiran por este lifecycle
• expired → active directo — debe pasar por re-verificación

7. Cierre — qué tienes y qué viene

Si seguiste la guía completa, ahora tienes:

• ✅ Spec Kit instalado y funcionando con Claude Code
• ✅ Una constitución QA-first con 5 principios verificables
• ✅ Un spec generado, clarificado, y validado contra tu constitución
• ✅ Un plan técnico y tareas listas para que la IA implemente
• ✅ Las 4 técnicas ISTQB mapeadas a fases concretas del ciclo

Lo más importante: tienes un flujo repetible. La próxima feature de tu proyecto sale por exactamente los mismos pasos. Y los bugs que antes aparecían en producción, ahora aparecen en el spec — donde cuestan 100x menos arreglarlos.

Qué leer después

Si te interesó esto, en el blog tienes el artículo conceptual que explica el porqué — Spec-Driven Development para QA: el futuro o el reemplazo.

Estoy preparando dos piezas más para esta serie:

1. SDD para devs, PM, PO y arquitectos — porque SDD no es solo de QA, y el rol de cada uno cambia.
2. El hueco que descubrí en Spec Kit cuando lo llevé al límite — un experimento que prueba dónde Spec Kit todavía está flojo, y cómo arreglarlo en tu propio fork.

Si quieres recibirlas apenas salen, suscríbete al newsletter. No spam — solo la siguiente pieza cuando esté lista.