Habilidad de Desarrollo Guiado por Especificaciones (SDD)
Guía a los usuarios a través de Spec-Kit de GitHub para el Desarrollo Guiado por Especificaciones, una metodología que invierte el desarrollo de software tradicional al hacer que las especificaciones sean ejecutables y generen implementaciones funcionales directamente.
Filosofía Central
El Desarrollo Guiado por Especificaciones enfatiza:
- Desarrollo impulsado por la intención: Define el "qué" antes del "cómo"
- Creación de especificaciones enriquecidas: Utiliza barreras de protección y principios organizativos
- Refinamiento en múltiples pasos: No es generación de código de una sola vez
- Nativo para IA: Dependencia significativa de capacidades avanzadas de IA
Recuerda: Esto es desarrollo nativo para IA. Las especificaciones no son solo documentación, sino artefactos ejecutables que impulsan directamente la implementación. El agente de IA las utiliza para generar código funcional que coincida con la intención definida en las especificaciones.
Criterios de Aceptación: Formato Gherkin (Obligatorio)
Cada historia de usuario en cada spec.md (o specify.md) DEBE incluir criterios de aceptación en formato Gherkin, además de su descripción en prosa. Esto aplica tanto para proyectos greenfield como brownfield, para cada historia de usuario, y ya sea que el artefacto haya sido producido por /speckit.specify o escrito a mano para un repositorio que no utiliza la plantilla generada por CLI. La prosa describe de qué trata la historia; los escenarios Gherkin dicen exactamente cómo verificarla — eso es lo que hace que una especificación sea ejecutable en lugar de descriptiva.
Formato — un bloque de código gherkin directamente debajo de cada historia de usuario, con 1 a 4 escenarios: primero el camino feliz, luego los casos límite o negativos que son relevantes para esa historia (no todos los casos límite de la especificación — esos pertenecen a la sección de Casos Límite de la propia especificación; solo aquellos específicos de esta historia).
Scenario: <nombre corto y específico — no "camino feliz">
Given <la condición previa / estado inicial>
When <la única acción que realiza el actor>
Then <el resultado observable y comprobable>
And <resultado adicional, si es necesario>
Scenario: <el caso límite/negativo para esta historia>
Given <condición previa>
When <acción>
Then <resultado — lo que NO debería suceder es un Then válido>
Reglas de escritura:
- Un
Whenpor escenario. Múltiples acciones significan múltiples escenarios — esto mantiene cada escenario mapeado a una prueba. Thendebe ser observable, no interno: "el usuario ve un mensaje de confirmación", no "el estado se actualiza correctamente". Si no puedes decir cómo alguien lo verificaría, no está listo.- Reutiliza el vocabulario de la propia especificación. Los pasos Given/When/Then deben usar los mismos sustantivos que la historia de usuario y los requisitos funcionales (nombres de activos, tipos de ofertas, nombres de campos) — no parafraseados.
- No replantees los requisitos funcionales como Gherkin. Los criterios de aceptación verifican la historia; los RFs se rastrean por separado. La superposición está bien, la duplicación de cada RF como un escenario no.
- Numera los escenarios para trazabilidad cuando una historia tenga más de uno:
Scenario: AC-1 — ...,Scenario: AC-2 — ...(opcional para historias de un solo escenario).
Al resumir (la plantilla de 10 puntos, "Lo que se generó"), informa el número de escenarios junto con los recuentos de historias de usuario/criterios de éxito, p. ej., "5 historias de usuario (11 escenarios Gherkin), 8 criterios de éxito." Si a una historia de usuario le faltan criterios de aceptación, márcala en "🔍 Elementos importantes a revisar" antes de pasar a /speckit.plan — los planes basados en historias sin criterios de aceptación tienden a especificar pruebas de manera insuficiente.
ACs de Comportamiento: solo para historias con LLM en el bucle
Gherkin asume que una ejecución decide si pasa o falla. Eso se rompe cuando la salida de un modelo decide el resultado: una ejecución exitosa de una historia no determinista no prueba casi nada. Para esas historias, agrega un bloque de ACs de Comportamiento debajo del bloque Gherkin.
Genéralo solo cuando el resultado observable de la historia dependa de la salida de un modelo. Ejemplos: un prompt, system prompt, misión, archivo de habilidad o descripción de herramienta cambia; un modelo elige la acción, juzga o resuelve algo, o escribe el texto visible para el usuario; el modelo o sus parámetros cambian. No lo generes para código determinista, renderizado de UI de datos almacenados, infraestructura, o una historia donde haya una llamada a un modelo pero su salida no se afirme. En caso de duda, haz una pregunta; no agregues el bloque de forma especulativa. Una especificación sin historias con LLM en el bucle no tiene ACs de Comportamiento en absoluto, y ningún marcador de posición vacío.
Formato: un bloque por historia que califique, directamente después de su Gherkin.
**ACs de Comportamiento** (LLM en el bucle: <lo que el modelo decide>)
- **Casos:** <N> casos en `<ruta al conjunto de casos>`, de fallos reales / trazas / transcripciones; entradas sintéticas solo para llenar vacíos, nunca salidas esperadas sintéticas
- **Ejecuciones:** k = <k> por caso (≈ 3 / tasa de fallo esperada; 20-30 si se desconoce)
- **Barrera de aprobación:** <métrica> ≥ <umbral> sobre k, supera la línea base por más que el ruido (comparación pareada contra la versión actual)
- **Calificador:** verificación de código | juez LLM (binario, uno por modo de fallo) | humano; un juez también nombra su validación: TPR/TNR ≥ 0.9 (mínimo 0.8) en etiquetas humanas retenidas, o "NO VALIDADO" dicho claramente
- **Comando:** `<un comando que lo ejecuta e imprime la tasa de aprobación, costo y latencia>`
Reglas:
- Solo cuenta una ejecución real del modelo. Un mock, una simulación de palabras clave o una puntuación predicha no es un resultado. Si no se puede ejecutar (costo, claves), di que la historia es NO EVALUADA. No falsifiques un número.
- Prefiere un calificador de código. Usa un juez solo para lo que el código no puede verificar.
- Gherkin sigue aplicando. Los escenarios Gherkin cubren el caparazón determinista (artefactos escritos, barreras mantenidas). Los ACs de Comportamiento cubren el comportamiento del modelo.
- plan.md lleva la evaluación: la ubicación del conjunto de casos, el comando de ejecución, el costo por ejecución, y cuándo se ejecuta (por PR, o solo antes de fusionar si es costoso).
Al resumir, cuéntalos por separado, p. ej., "5 historias de usuario (11 escenarios Gherkin, 2 con ACs de Comportamiento)". Marca en "Elementos importantes a revisar" cualquier historia con LLM en el bucle que carezca del bloque, y cualquier juez marcado como NO VALIDADO.
Árbol de Decisión Rápido
¿Es un proyecto nuevo (greenfield)?
→ Consulta Flujo de Trabajo Greenfield para el proceso completo de 6 pasos
¿Es una base de código existente (brownfield)?
→ Consulta Flujo de Trabajo Brownfield para obtener orientación sobre ingeniería inversa e integración
¿Necesitas ayuda con la instalación?
→ Consulta Guía de Instalación para configuración y solución de problemas
Inicio Rápido de Instalación
Recomendado (Persistente):
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
Uso único:
uvx --from git+https://github.com/github/spec-kit.git specify init <NOMBRE_DEL_PROYECTO>
Verificar:
specify check
Para opciones de instalación detalladas, solución de problemas y variables de entorno, consulta Guía de Instalación.
Agentes de IA Compatibles
Funciona con:
- ✅ Claude Code
- ✅ GitHub Copilot
- ✅ Gemini CLI
- ✅ Cursor
- ✅ Qwen Code
- ✅ opencode
- ✅ Windsurf
- ✅ Kilo Code
- ✅ Auggie CLI
- ✅ CodeBuddy CLI
- ✅ Roo Code
- ✅ Codex CLI
- ✅ Amp
- ⚠️ Amazon Q Developer CLI (no admite argumentos personalizados para comandos slash)
Resumen de Artefactos y Bucle de Retroalimentación
FLUJO DE TRABAJO CRÍTICO: Después de que cualquier comando SDD genere o modifique artefactos, sigue automáticamente este bucle de retroalimentación para mantener al usuario informado:
Después de que Cada Comando se Complete
-
Detectar Cambios en los Artefactos
- Identificar qué artefactos se crearon o modificaron:
constitution.md(principios del proyecto)spec.md(especificación de requisitos)plan.md(plan de implementación técnica)tasks.md(desglose de tareas procesables)- Informes de análisis de flujos de trabajo brownfield
- Identificar qué artefactos se crearon o modificaron:
-
Leer y Resumir
- Leer el(los) artefacto(s) relevante(s)
- Extraer información clave:
- Para constitution.md: Principios centrales, estándares de codificación, restricciones
- Para spec.md: Requisitos principales, historias de usuario (con sus criterios de aceptación Gherkin), criterios de éxito
- Para plan.md: Elecciones de pila tecnológica, decisiones de arquitectura, hitos
- Para tasks.md: Número de tareas, categorías principales de tareas, dependencias
- Para informes de análisis: Patrones actuales, deuda técnica, puntos de integración
-
Presentar Resumen Estructurado (Usar la Plantilla de 10 Puntos a Continuación)
- Mostrar qué se generó y por qué
- Destacar las decisiones más importantes con su justificación
- Incluir indicadores de calidad y advertencias
- Mantener el resumen enfocado y procesable
- Usar encabezados claros para cada sección
-
Incluir Estado de la Función (Enfoque Híbrido)
- Línea de estado breve en cada resumen
- Estado detallado a pedido con
/speckit.status - Consulta la sección "Seguimiento del Estado de las Funciones" a continuación
-
Ofrecer Opciones de Retroalimentación
- Opción A: "Se ve bien, continuar al siguiente paso"
- Opción B: "Me gustaría modificar [sección específica]"
- Opción C: "Regenerar con estos cambios: [entrada del usuario]"
- Opción D: "Explica por qué se tomó [decisión específica]"
Plantilla de Resumen de 10 Puntos
Usa este formato estructurado DESPUÉS de que cualquier comando SDD se complete:
## ✅ [Nombre del Comando] Completado - Esto es lo que Acaba de Suceder
### 🎯 Decisiones Clave Tomadas (Top 3)
1. [Decisión] - **Justificación:** [Por qué se eligió esto]
2. [Decisión] - **Justificación:** [Por qué se eligió esto]
3. [Decisión] - **Justificación:** [Por qué se eligió esto]
### 📋 Lo Que Se Generó
- [Artefacto 1]: [Breve descripción del contenido]
- [Artefacto 2]: [Breve descripción del contenido]
### 🔍 Elementos Importantes a Revisar (Top 3)
1. [Elemento crítico a verificar y por qué es importante]
2. [Detalle importante a verificar y su impacto potencial]
3. [Caso límite a considerar y cómo afecta al diseño]
### ⚠️ Cuidado Con (Top 2)
- [Problema potencial o trampa] - **Cómo evitarlo:** [Orientación]
- [Error común] - **Cómo evitarlo:** [Orientación]
### 🔄 Lo Que Esto Permite a Continuación (2 Opciones)
- **Opción 1:** [Siguiente paso] - Mejor si: [Condición]
- **Opción 2:** [Paso alternativo] - Mejor si: [Condición]
📊 **Estado de la Función:** [Nombre de la Función Actual] ([Etapa]) → Siguiente: [Próxima Función]
Progreso: [●●●○○] [X]% | Completadas: [N] de [Total] funciones | Dependencias: [Estado]
**Tus opciones:** [A] Proceder [B] Modificar [C] Explicar más [D] Mostrar estado completo
Ejemplo: Resumen Mejorado Después de `/speckit.specify`
## ✅ Specify Completado - Esto es lo que Acaba de Suceder
### 🎯 Decisiones Clave Tomadas
1. **Autenticación: Tokens JWT** - Justificación: Arquitectura sin estado, escalable horizontalmente, estándar de la industria
2. **Requisitos de contraseña: 12+ caracteres con complejidad** - Justificación: Equilibra seguridad (directrices NIST) con usabilidad
3. **Tiempo de sesión: 24 horas** - Justificación: Estándar para aplicaciones web, equilibra seguridad vs comodidad del usuario
### 📋 Lo Que Se Generó
- `.speckit/features/user-auth/specify.md`: Requisitos completos con 5 historias de usuario (12 escenarios de criterios de aceptación Gherkin), 8 criterios de éxito, 3 casos límite
### 🔍 Elementos Importantes a Revisar
1. **Flujo de restablecimiento de contraseña** - Verifica que los requisitos de correo electrónico coincidan con tu infraestructura (servidor SMTP, plantillas)
2. **Autenticación multifactor** - Actualmente marcada como "mejora futura"; puede que necesite estar en el MVP
3. **Límite de tasa** - Establecido en 5 intentos de inicio de sesión cada 15 minutos; considera si esto se ajusta a tu política de seguridad
### ⚠️ Cuidado Con
- **Dependencia del servicio de correo electrónico no especificada** - Cómo evitarlo: Agregar servicio de correo electrónico a las dependencias de plan.md
- **Cumplimiento de GDPR para datos de usuario** - Cómo evitarlo: Revisar los requisitos de retención de datos y eliminación de usuarios
### 🔄 Lo Que Esto Permite a Continuación
- **Opción 1:** Ejecutar `/speckit.plan` para diseñar la implementación técnica - Mejor si: Los requisitos se ven bien
- **Opción 2:** Modificar specify.md - Mejor si: Necesitas ajustar requisitos o agregar funciones
📊 **Estado de la Función:** user-authentication (Especificado) → Siguiente: profile-management
Progreso: [●●○○○] 40% | Completadas: 1 de 5 funciones | Dependencias: database-setup ✅
**Tus opciones:** [A] Proceder a la planificación [B] Modificar requisitos [C] Explicar elección de JWT [D] Mostrar estado completo
Cuándo Omitir el Resumen
Solo omite el paso de resumen cuando:
- El usuario lo solicite explícitamente ("omitir resúmenes" o "ejecutar todos los pasos automáticamente")
- Se esté re-ejecutando un comando sin cambios en los artefactos
- El comando falle o produzca errores (en su lugar, soluciona problemas)
Beneficios de Este Flujo de Trabajo
- Elimina la sensación de "caja negra": Explicaciones claras de lo que se generó y por qué
- Permite retroalimentación temprana: Detecta malentendidos antes de la implementación
- Mantiene la agilidad: Revisión rápida con formato estructurado, no procesos de aprobación largos
- Genera confianza: El usuario ve el razonamiento de la IA y las decisiones con su justificación
- Proporciona contexto: El estado de las funciones mantiene a los usuarios orientados en el proyecto general
Seguimiento del Estado de las Funciones
Enfoque Híbrido
Después de cada comando SDD, incluye una línea breve de estado de la función en el resumen. Proporciona estado detallado a pedido con /speckit.status.
Formato de Línea de Estado Breve
Incluye esto al final de cada resumen:
📊 **Estado de la Función:** [Nombre de la Función Actual] ([Etapa]) → Siguiente: [Nombre de la Próxima Función]
Progreso: [●●●○○] [X]% | Completadas: [N] de [Total] funciones | Dependencias: [Dep] ✅/⏸️
Valores de Etapa:
Especificando(20% completado)Planificando(40% completado)Tareando(60% completado)En Progreso(80% completado)Completa(100% completado)
Indicador de Progreso:
- Usa círculos rellenos (●) para etapas completadas
- Usa círculos vacíos (○) para etapas pendientes
- Calcula el porcentaje basado en la etapa
Panel de Estado Detallado
Cuando el usuario solicite el estado completo (opción D) o ejecute /speckit.status, muestra:
📊 Panel de Estado de Funciones del Proyecto
🎯 FUNCIÓN ACTUAL
├─ [nombre-de-la-función] ([Etapa] - [X]% completado)
│ ├─ ✅ Requisitos especificados
│ ├─ 🔄 Plan de implementación en progreso
│ ├─ ⏸️ Tareas no iniciadas
│ └─ ⏸️ Implementación no iniciada
│ Bloqueos: [Ninguno | Descripción]
│ Dependencias: [nombre-de-la-función] ✅
✅ FUNCIONES COMPLETADAS ([N])
├─ [función-1] (100% completado)
└─ [función-2] (100% completado)
📋 PRÓXIMAS FUNCIONES ([N])
├─ [función-3] (depende de: [función-actual])
└─ [función-4] (depende de: [función-3])
⚠️ FUNCIONES BLOQUEADAS
...
[Trucado para la traducción]