Bucle de Desarrollo Guiado por Especificaciones (SDDL)
Código abierto: https://github.com/xt-mahh/sddl (2026-08-06, Licencia MIT) Metodología completa + scripts de verificación + proyectos de ejemplo en el repositorio de GitHub.
Resumen
SDDL lleva la programación con IA del modo "conversacional" al modo "guiado por especificaciones". Promesa central: primero define claramente qué hacer, luego escribe código — con un Spec estructurado como única fuente de verdad, un doble bucle cerrado que garantiza calidad y auditabilidad.
Bucle de Formación (responde "qué hacer") Bucle de Derivación (responde "cómo hacerlo bien")
Requisitos ──▶ Entrevista ──▶ Borrador Spec ──▶ Spec congelado ──▶ tests/código/docs ──▶ Convergencia
└─▶ Control calidad SQC ──┘ └─▶ Verificación C1-C4 ─┘
└─▶ Confirmación puntos decisión ──┘
¿Por qué usar SDDL? Los problemas de la programación conversacional: deriva del contexto (después de 50 turnos se olvida lo acordado en el turno 3), múltiples artefactos desincronizados (código cambiado, tests/documentación no actualizados), y aceptación subjetiva ("parece correcto" en lugar de "cumple la especificación"). SDDL resuelve estos tres problemas con un Spec estable y completamente cargable + verificaciones de consistencia por capas.
Cuándo Usar
Disparadores:
- El usuario quiere iniciar un nuevo proyecto, escribir una función principal, diseñar la arquitectura del sistema
- El usuario dice "primero planifica", "primero diseña", "primero escribe la especificación", "cómo hacer esta función"
- Tareas que requieren la producción simultánea de múltiples artefactos (código + tests + documentación)
- Proyectos con ≥ 5 interfaces, o ≥ 5 criterios de aceptación de tipo must, y vida útil esperada > 2 semanas
No aplicar (escribir código directamente, no usar esta habilidad):
- Scripts de un solo uso / prototipos / POC / código de investigación exploratoria
- Herramientas pequeñas de un solo archivo (interfaces < 5, sin necesidad de múltiples artefactos)
- El usuario dice explícitamente "escribe directamente" o "hazlo rápido"
Comandos por fases (forma de interacción principal de esta habilidad):
| Comando | Fase | Qué hace | Resultado |
|---|---|---|---|
/sddl:init | Inicialización | Crear estructura de directorios, leer código/requisitos existentes | Esqueleto sddl/ + state.yaml |
/sddl:interview | Formación | Entrevista de requisitos por capas (L0-L2 obligatorias) | Declaración de requisitos |
/sddl:spec | Formación | Generar borrador de spec L1-L5 + marcar puntos de decisión | specs/<dominio>/spec.yaml |
/sddl:confirm | Formación | Resumen de puntos de decisión + confirmación clarify | decisions/<dominio>-confirmation.yaml |
/sddl:freeze | Formación | Verificación SQC + congelación | spec_status: frozen |
/sddl:derive | Derivación | Derivar tests/código/docs del spec | src/ tests/ docs/ |
/sddl:verify | Derivación | Verificación C1-C4 + determinación de convergencia | checks/*.json + convergencia/ruta |
/sddl:archive | Archivo | Archivar cambios, fusionar specs | Actualización specs/ + CHANGELOG |
Principios Centrales
- El Spec es un oráculo, pero puede ser cuestionado: los defectos descubiertos durante la derivación → descongelar → volver al bucle de formación para revisar → volver a congelar (pasando por la puerta de calidad completa, sin omitirla)
- Determinismo primero: cuando se pueda resolver con análisis estático/schema/ejecución de tests, nunca usar la LLM para adivinar
- La convergencia es un sistema de ingeniería: puertas de condiciones duras + tasa de consenso de condiciones blandas + restricciones de presupuesto + respaldo humano
- Los puntos de decisión no son silenciosos: en zonas ambiguas, la IA da un valor por defecto + marca el punto de decisión, el usuario confirma antes de congelar
- El progreso es el directorio: fase completada = archivo existente (Convention over Config), reanudación gratuita tras interrupción
El Directorio es el Estado (Convention over Config)
No mires el archivo de estado, mira el directorio para saber el progreso. Este es el mecanismo de visibilidad del progreso de esta habilidad (junto con los commits de git como puntos de control).
<proyecto>/
├── sddl/
│ ├── specs/ # existe = entrevista completada, spec generado
│ │ └── <dominio>/spec.yaml # status: frozen = congelación completada
│ ├── changes/ # propuestas de cambio (desarrollo incremental, pueden ser paralelas)
│ ├── decisions/ # registros de confirmación de puntos de decisión
│ │ └── <dominio>-confirmation.yaml
│ ├── checks/ # archivos de informes de verificación (JSON legible por máquina)
│ │ ├── sqc-<dominio>-v1.json
│ │ └── c1-c4-<dominio>-v1.json
│ └── state.yaml # único metadato: puntero de fase + presupuesto + última verificación
├── src/ # aparece después del bucle de derivación
├── tests/ # aparece después del bucle de derivación
├── docs/ # aparece después del bucle de derivación (contiene particiones current/planned)
└── (git commit al completar cada fase)
state.yaml minimalista (solo almacena punteros, no detalles de progreso):
spec_status: frozen # interviewing | drafting | reviewing | frozen | evolved
current_phase: derivation # formation | derivation | complete
budget: { formation: 40%, implementation: 12%, revision: 100% }
last_check: { type: sqc, spec: auth-v0.1.0, result: pass, at: 2026-08-06T16:00 }
Regla de reanudación: al recargar la habilidad, escanea el directorio — si no hay specs/, empezar desde interview; si hay specs/ pero no decisions/, empezar desde confirm; si hay decisions/ pero spec no está frozen, empezar desde freeze; si hay src/ pero no checks/, empezar desde derive; si hay checks/, empezar desde verify.
Fase completada = git commit (asistido por IA): después de que cada comando se ejecute con éxito, hacer commit (feat(sddl): interview complete), garantizando la trazabilidad.
Orquestación del Doble Bucle
Bucle de Formación (hacer lo correcto) — 5 comandos
/sddl:interview → /sddl:spec → /sddl:confirm → /sddl:freeze
│ │ │ │
└─ Revisión ──┴──────┴──────┘
(SQC no pasa / usuario cambia puntos de decisión → volver al paso anterior, máximo 5 rondas)
| Comando | Acción clave | Punto de verificación |
|---|---|---|
| interview | Preguntas por capas L0-L2 (≤10 preguntas obligatorias), produce declaración de requisitos | Declaración de requisitos completa |
| spec | Generar spec L1-L5 + marcar puntos de decisión (registrar DP en zonas ambiguas) | Esqueleto SQC-def aprobado |
| confirm | Resumen de puntos de decisión → clarify uno por uno para confirmar (incluye entrada personalizada) | Sin puntos de decisión pendientes |
| freeze | Verificación SQC completa + firma del registro de confirmación | SQC sin blocker + frozen |
Bucle de Derivación (hacer las cosas bien) — 3 comandos
/sddl:derive → /sddl:verify → (convergencia) → Completado
│ │
└─ Ruta ───────┘
(violación → redirigir código/tests/docs o descongelar y volver al bucle de formación)
| Comando | Acción clave | Punto de verificación |
|---|---|---|
| derive | Derivar tests/código/docs del spec | Artefactos ejecutables |
| verify | Verificación por capas C1-C4 + determinación de convergencia | Puertas duras + consenso blando + cobertura must |
| archive | Archivar cambios, fusionar specs | CHANGELOG + actualización del spec |
Scripts de Verificación (scripts/) — Evidencia Determinista, No Juicios Semánticos
Los scripts solo se encargan de la evidencia determinista (type checking/ejecución de tests/tabla de símbolos/YAML), la revisión semántica la realiza la capacidad LLM del agente:
# Verificación determinista SQC (puerta del bucle de formación) — el script da los hechos
python3 scripts/check_sqc.py sddl/specs/<dominio>/spec.yaml --verbose
# Verificación determinista C1-C4 (puerta del bucle de derivación) — el script da los hechos
python3 scripts/check_c1_c4.py . --verbose
# Restauración de estado (después de interrupción) — escanea el directorio y da el progreso actual + siguiente comando
python3 scripts/sddl_status.py .
- Código de salida: 0 = pass/converged, 1 = fail (se puede enganchar en CI)
--jsonproduce evidencia legible por máquina (para que la LLM la cite en la revisión)
Principio de división del trabajo (importante):
| Capa | Responsable |
|---|---|
| Evidencia determinista (condiciones duras): validez del schema/existencia de la interfaz/tests pasan/tabla de símbolos | Scripts |
| Revisión semántica (condiciones blandas): cobertura de comportamiento/THEN aseverable/cobertura real de tests/veracidad de la documentación | LLM del agente (ver references/llm-review.md) |
No uses heurísticas de scripts para hacer juicios semánticos — el emparejamiento de cadenas produce falsos negativos explosivos (T1 midió C1-sem en 0.48). Los scripts son recolectores de evidencia, el agente es el juez.
Cuándo Leer Cada Referencia
Cargar bajo demanda, no leer todo de una vez (divulgación progresiva):
| Escenario | Leer |
|---|---|
| Ejecutar interview | references/formation-loop.md (fase 1) |
| Generar spec | references/spec-schema.md + templates/spec-template.yaml |
| Verificación SQC | references/sqc-checklist.md (def con scripts, sem con LLM) |
| Confirmación de puntos de decisión | templates/decision-summary.md |
| Derivación de artefactos | references/derivation-loop.md (fases 1-2) |
| Verificación C1-C4 | references/checker-matrix.md (def con scripts, sem con LLM) |
| Revisión semántica | references/llm-review.md (central: cómo hace la LLM la revisión) |
| Enrutamiento/reescritura/presupuesto | references/derivation-loop.md (fases 3-5) |
| Propuestas de cambio | references/formation-loop.md (gestión de cambios) |
Presupuesto y Degradación
- Tres presupuestos: formation (2M tokens / 5 rondas) / implementation (15M / 4 sesiones) / revision (5M, L2 descuenta 10%, L3 descuenta 25%, primera L3 gratis)
- El presupuesto se registra en state.yaml, se actualiza en cada comando
- Presupuesto agotado → modo conducido por humano, sin degradación automática (la calidad del spec es la base)
- Ruta de degradación: D1 degradación semántica → D2 should/could mover a lista de riesgos → D3 reducir variantes → D4 dividir spec → D5 entrega de mejor esfuerzo
Normas de Experiencia (Importante)
- Comandos por fases: nunca ejecutar todo el doble bucle en una sola respuesta — cada comando es una unidad de interacción independiente, con puntos de verificación entre ellos
- Puntos de decisión con clarify, entrada personalizada explícitamente visible: un clarify por punto de decisión, con explicación del impacto; opciones de negocio ≤ 3, la 4ª posición fija para "Otra (Entrada personalizada)" (probado: clarify no tiene 'Otra' automático, opciones máximo 4, debe haber un marcador explícito); el texto de la pregunta indica "para otros valores, seleccione Entrada personalizada"; los valores personalizados del usuario siguen el protocolo de captura (registrar value+reason → sincronizar spec → marcar registro como modified); los puntos de decisión abiertos usan clarify sin opciones
- Progreso visible: al inicio/fin de cada comando, informar la fase actual + el siguiente paso
- Escritura de estado: al final de cada comando, escribir state.yaml + git commit
- Informes de verificación: cada verificación (SQC/C1-C4) escribe
checks/*.json, con un resumen legible + detalles legibles por máquina
Errores Comunes
- Saltar el bucle de formación e ir directamente a la derivación — Escribir código sin haber congelado el Spec = volver a la programación conversacional.
/sddl:freezees un límite duro, no se deriva sin congelar. - Decisión silenciosa en puntos de decisión — No marcar DP en zonas ambiguas y escribir directamente un valor por defecto = distorsión de la intención del usuario. Cualquier "elección por el usuario" debe registrar un DP.
- Ciclo de autovalidación del verificador — Confiar en las etiquetas puestas por la IA. C1-def debe hacer una inferencia estructural (analizar el AST del test), no confiar en etiquetas.
- Puntuación absoluta de la revisión semántica — Una puntuación de 0-100 de la LLM no es fiable. Usar Checklist binario + tasa de consenso por votación (recuento objetivo).
- Reescritura que elude la puerta de calidad — Si spec_error modifica directamente el spec = estándar auto-relajado. Debe descongelar → volver al bucle de formación → volver a congelar.
- Inflado del archivo de estado — Escribir todo el progreso en state.yaml = volver a la "mentira documental". state.yaml solo almacena punteros, los detalles están en los propios archivos.
- Presupuesto sin registro — No actualizar el presupuesto en state.yaml = pérdida de control de costes. Actualizar al final de cada comando.
- Revisión semántica con emparejamiento de cadenas burdo — T1 midió: el emparejamiento de palabras clave redujo C1-sem a 0.48 (explosión de falsos negativos). Priorizar votación con Checklist LLM; la heurística solo como fallback, y debe ser semántica (extraer aserciones del AST + palabras clave estructuradas); el resultado de la primera ronda no es fiable, requiere revisión humana.
- Fuga de estado compartido entre tests — T1 midió: el store en memoria compartido entre tests provocó fallos de aserción. Al derivar, añadir fixture de aislamiento (autouse reset); las aserciones de los tests deben usar la interfaz pública, no acceder al
_storeinterno. - Funciones de consulta puras con efectos secundarios — T1 midió:
detectDiscrepancymodificaba internamente el status, violando B006 del spec (debe mantener draft). Las interfaces de consulta pura (que devuelven informes/consultas) no deben modificar el estado; C2-sem debe verificar esto.
Lista de Verificación
- Estructura de directorios
sddl/correcta (specs/changes/decisions/checks/state.yaml) - spec.yaml pasa SQC-def (schema válido/referencias completas/aseverabilidad/cobertura de puntos de decisión)
- Todos los puntos de decisión están confirmed/modified/delegated (sin pending)
- Registro de confirmación firmado (overall: approved)
- spec_status: frozen antes de entrar en derivación
- C1-def hizo inferencia estructural (no confiar en etiquetas)
- Condiciones duras (C1-def/C2-def/C3/C4b-def) todas pasan
- Tasa de consenso de condiciones blandas alcanzada (c1_sem≥0.95 c2_sem≥0.95 c4a≥0.90 c4b_sem≥0.90)
- Cobertura de criterios de aceptación must al 100%
- Presupuesto en state.yaml actualizado
- git commit de fase completada realizado
Recetas de Una Sola Vez
Nuevo proyecto desde cero
/sddl:init → /sddl:interview → /sddl:spec → /sddl:confirm → /sddl:freeze
→ /sddl:derive → /sddl:verify → /sddl:archive
Rellenar spec para código existente (proyecto de refactorización)
/sddl:init (leer código existente) → /sddl:spec (extraer estado actual inversamente + marcar puntos de decisión)
→ /sddl:confirm → /sddl:freeze → /sddl:verify (verificar consistencia spec↔code)
Desarrollo de funcionalidad incremental (spec ya congelado)
/sddl:init → escribir propuesta changes/<nombre>/ → /sddl:confirm (puntos de decisión afectados)
→ /sddl:freeze → /sddl:derive → /sddl:verify → /sddl:archive
Habilidades Relacionadas
writing-plans: Escribir planes de implementación (los changes/tasks.md de SDDL pueden usarlo)test-driven-development: TDD es el medio de verificación de SDDL (ejecución de tests C3)hermes-agent-skill-authoring: Normas de creación de esta propia habilidad