GitHub Spec Kit a fondo: qué es, qué hace, y por qué importa para QA

Esta semana iba a publicar la guía hands-on de Spec-Driven Development (SDD). Cambié el plan.

Después de que salió el artículo sobre Spec-Driven Development para QA, me llegaron varios mensajes de gente que entendió la filosofía pero se quedó con la misma pregunta: “¿qué es exactamente GitHub Spec Kit? ¿cómo se usa? ¿de qué me sirve a mí como QA?”.

Y tienen razón en preguntarlo. Tirarles encima una guía paso a paso con comandos como /speckit-specify y /speckit-clarify sin haberles contado primero qué es esa herramienta, qué hace, qué NO hace y por qué importa — sería exactamente el tipo de contenido vacío contra el que escribo. Comandos sin contexto. Pasos sin entender. Humo.

Así que la guía espera al martes. Hoy va este artículo introductorio. Es el puente entre el “¿por qué SDD?” del artículo anterior y el “cómo lo aplicas en tu proyecto” de la guía que viene. Si lo lees con calma, cuando llegue la guía vas a entender cada comando antes de copiarlo — que es exactamente lo que SDD intenta enseñar.

Lo primero — Spec Kit no es una IA

Este es el malentendido más común. Lo escucho cada semana.

Spec Kit es una herramienta de línea de comandos (CLI) open source publicada por GitHub. Una colección de scripts y templates que se instala en tu proyecto y se opera desde la terminal. No piensa, no escribe código por sí solo, no inventa specs.

Su trabajo es estandarizar el ciclo SDD y conectarlo con tu agente preferido — Claude Code, Copilot, Cursor, el que uses. Spec Kit es el orquestador. La IA es el ejecutor. Son cosas distintas y separables.

Lo que SÍ hace Spec Kit:

• Te da slash commands estandarizados (/speckit-specify, /speckit-clarify, etc.)
• Versiona los artefactos que produce el ciclo (constitución, spec, plan, tasks)
• Aplica gates obligatorios entre fases — no puedes saltar de spec a implementación sin pasar por validación
• Conecta hooks de git automáticos (branch por feature, commits etiquetados)
• Mantiene una convención de carpetas estándar (.specify/, specs/NNN-feature/)

Lo que NO hace Spec Kit:

• No escribe la constitución por ti. Los principios salen de tu cabeza.
• No testea. La IA escribe tests, pero Spec Kit no los corre ni valida cobertura.
• No reemplaza el juicio humano. Es una compuerta, no un cerebro.
• Necesita un equipo comprometido con el proceso. El PM tiene que contestar las clarificaciones que dispara, y nadie puede saltarse las compuertas entre fases solo porque aprieta el deadline.

El ciclo SDD en una imagen mental

Spec Kit organiza el trabajo en 7 fases conectadas por gates obligatorios. Cada fase tiene un comando, produce un artefacto, y cierra una pregunta concreta.

Las primeras dos son planificación (qué reglas, qué construir). Las dos del medio son validación (es ahí donde tu rol QA pesa más). Las tres últimas son ejecución (donde la IA toma protagonismo).

Los artefactos que produce — qué archivos vas a tener

Cada comando deja un archivo concreto en tu repo. Versionable, revisable, comparable entre branches.

Las dos compuertas que separan SDD real de “darle un prompt y rezar”

Esto es lo que hace que Spec Kit valga la pena instalar. Dos comandos que bloquean el avance hasta que se cumplan condiciones explícitas.

/speckit-clarify — la compuerta antes del plan

Spec Kit detecta ambigüedades en tu spec y te las pregunta antes de avanzar. Si escribiste “el sistema debe ser robusto”, te pregunta: ¿robusto cómo? ¿qué umbral? ¿bajo qué carga? Si escribiste “el usuario se autentica”, te pregunta: ¿qué pasa si la sesión expira? ¿se permite multi-device?

No puedes pasar a /speckit-plan con ambigüedades sin resolver. Spec Kit te lo bloquea.

Por qué importa: lo que tú haces hoy a pulmón en sprint planning — preguntar “¿qué pasa si…?”, “¿qué entendemos por X?” — Spec Kit lo dispara como compuerta obligatoria. Las ambigüedades que en un proyecto normal aparecen como bugs en el sprint 4, acá aparecen el día 1.

/speckit-checklist — la compuerta antes de implementar

Genera un checklist personalizado a tu proyecto y a la constitución que escribiste. NO es genérico. Tú defines qué se valida.

Por ejemplo, si tu constitución dice “toda spec debe aplicar las 4 técnicas ISTQB del Cap. 4”, el checklist va a tener ítems del tipo:

• El spec declara las clases de equivalencia para cada input
• El spec declara los valores límite con valor-1 / valor / valor+1
• El spec incluye una tabla de decisión exhaustiva
• El spec declara estados permitidos, transiciones permitidas, y transiciones prohibidas

Cada ítem se marca como ✅ Satisfecho, ⚠️ Parcial, o ❌ Gap. Si el checklist tiene gaps, no avanzas a implementación.

Por qué para QA importa concretamente

Cuatro razones aterrizadas, no abstractas:

1. Las clarificaciones son tu trabajo, automatizado. Lo que tú haces hoy en refinement (preguntar lo que el PM no pensó), Spec Kit lo dispara como compuerta. Tu rol pasa de “el que pregunta cosas molestas” a “el que valida que las preguntas se respondieron bien”. El cambio no es menor.

2. Los artefactos son tu test plan. El spec.md con sus acceptance scenarios, decision tables, state machines, error catalog — es exactamente la estructura de un test plan ISTQB. Lo que antes te tomaba un día escribir, ya viene generado.

3. La review de PR tiene una vara objetiva. Antes “se ve bien” o “me parece raro”. Ahora: ¿este código honra el spec o no? Si lo honra, aprobás. Si no, vuelve. Sin debate de gustos.

4. 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. Acá no, porque los tests están atados al contrato, no al código.

Lo que Spec Kit NO te da (la lista anti-mágica)

Para evitar expectativas que después decepcionan:

Cómo se instala (el resumen rápido)

La guía completa sale el martes con cada paso, pero el resumen es:

# 1. Instalar uv (gestor moderno de paquetes Python)
brew install uv

# 2. Inicializar Spec Kit en tu proyecto
mkdir mi-proyecto && cd mi-proyecto
uvx --from git+https://github.com/github/spec-kit.git specify init .

# 3. Elegir tu agente cuando te lo pregunte (Claude Code, Copilot, Cursor)
# 4. Abrir el proyecto en tu agente y verificar slash commands

Si el paso 4 te muestra /speckit-constitution, /speckit-specify y compañía en el autocompletado de tu agente, ya está. Tu primer ciclo SDD está a un comando de distancia.

El cierre — qué te llevas de este post

Spec Kit no es una IA. Es la disciplina del ciclo SDD vuelta comando ejecutable. La diferencia entre un equipo que dice “usamos SDD” y uno que realmente lo hace, es si tienen los gates instalados — o si los saltean cuando aprieta el deadline.

Si llegaste hasta acá y tienes dudas concretas sobre cómo aplicarlo en tu equipo, escríbeme. Leo todas las respuestas, y los bloqueos reales me sirven para escribir las próximas piezas de esta serie.