CommunityRedacción y edicióngithub.com

sddl

Habilidad de agente para Desarrollo Guiado por Especificaciones (Spec-Driven Development): con un Spec estructurado como única fuente de verdad, doble bucle (bucle de formación + bucle de derivación) + verificaciones de consistencia C1-C4, llevando la programación con IA del modo conversacional al modo guiado por especificaciones.

¿Qué es sddl?

SDDL (Spec-Driven Development Loop) es una habilidad para agentes de IA que transforma la programación asistida por IA de un enfoque conversacional a uno guiado por especificaciones. Su núcleo es un Spec estructurado que actúa como la única fuente de verdad, con un proceso de doble bucle: el bucle de formación (Formation Loop) para definir 'qué hacer' y el bucle de derivación (Derivation Loop) para 'hacerlo bien'. El bucle de formación incluye desde la entrevista de requisitos hasta la congelación del Spec, mientras que el bucle de derivación genera tests, código y documentación a partir del Spec congelado, verificando la consistencia mediante cuatro niveles (C1-C4). Esta habilidad es ideal para proyectos nuevos, diseño de sistemas o cualquier tarea que requiera 'definir antes de actuar', pero no para scripts rápidos o prototipos. Soporta comandos por fases como `/sddl:init`, `/sddl:interview`, `/sddl:spec`, `/sddl:confirm`, `/sddl:freeze`, `/sddl:derive`, `/sddl:verify` y `/sddl:archive`, y su progreso es visible en la estructura de directorios, lo que facilita la reanudación tras interrupciones.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add xt-mahh/sddl

Installed? Explore more Redacción y edición skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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):

ComandoFaseQué haceResultado
/sddl:initInicializaciónCrear estructura de directorios, leer código/requisitos existentesEsqueleto sddl/ + state.yaml
/sddl:interviewFormaciónEntrevista de requisitos por capas (L0-L2 obligatorias)Declaración de requisitos
/sddl:specFormaciónGenerar borrador de spec L1-L5 + marcar puntos de decisiónspecs/<dominio>/spec.yaml
/sddl:confirmFormaciónResumen de puntos de decisión + confirmación clarifydecisions/<dominio>-confirmation.yaml
/sddl:freezeFormaciónVerificación SQC + congelaciónspec_status: frozen
/sddl:deriveDerivaciónDerivar tests/código/docs del specsrc/ tests/ docs/
/sddl:verifyDerivaciónVerificación C1-C4 + determinación de convergenciachecks/*.json + convergencia/ruta
/sddl:archiveArchivoArchivar cambios, fusionar specsActualización specs/ + CHANGELOG

Principios Centrales

  1. 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)
  2. Determinismo primero: cuando se pueda resolver con análisis estático/schema/ejecución de tests, nunca usar la LLM para adivinar
  3. La convergencia es un sistema de ingeniería: puertas de condiciones duras + tasa de consenso de condiciones blandas + restricciones de presupuesto + respaldo humano
  4. 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
  5. 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)
ComandoAcción clavePunto de verificación
interviewPreguntas por capas L0-L2 (≤10 preguntas obligatorias), produce declaración de requisitosDeclaración de requisitos completa
specGenerar spec L1-L5 + marcar puntos de decisión (registrar DP en zonas ambiguas)Esqueleto SQC-def aprobado
confirmResumen de puntos de decisión → clarify uno por uno para confirmar (incluye entrada personalizada)Sin puntos de decisión pendientes
freezeVerificación SQC completa + firma del registro de confirmaciónSQC 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)
ComandoAcción clavePunto de verificación
deriveDerivar tests/código/docs del specArtefactos ejecutables
verifyVerificación por capas C1-C4 + determinación de convergenciaPuertas duras + consenso blando + cobertura must
archiveArchivar cambios, fusionar specsCHANGELOG + 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)
  • --json produce evidencia legible por máquina (para que la LLM la cite en la revisión)

Principio de división del trabajo (importante):

CapaResponsable
Evidencia determinista (condiciones duras): validez del schema/existencia de la interfaz/tests pasan/tabla de símbolosScripts
Revisión semántica (condiciones blandas): cobertura de comportamiento/THEN aseverable/cobertura real de tests/veracidad de la documentaciónLLM 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):

EscenarioLeer
Ejecutar interviewreferences/formation-loop.md (fase 1)
Generar specreferences/spec-schema.md + templates/spec-template.yaml
Verificación SQCreferences/sqc-checklist.md (def con scripts, sem con LLM)
Confirmación de puntos de decisióntemplates/decision-summary.md
Derivación de artefactosreferences/derivation-loop.md (fases 1-2)
Verificación C1-C4references/checker-matrix.md (def con scripts, sem con LLM)
Revisión semánticareferences/llm-review.md (central: cómo hace la LLM la revisión)
Enrutamiento/reescritura/presupuestoreferences/derivation-loop.md (fases 3-5)
Propuestas de cambioreferences/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)

  1. 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
  2. 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
  3. Progreso visible: al inicio/fin de cada comando, informar la fase actual + el siguiente paso
  4. Escritura de estado: al final de cada comando, escribir state.yaml + git commit
  5. Informes de verificación: cada verificación (SQC/C1-C4) escribe checks/*.json, con un resumen legible + detalles legibles por máquina

Errores Comunes

  1. 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:freeze es un límite duro, no se deriva sin congelar.
  2. 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.
  3. 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.
  4. 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).
  5. 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.
  6. 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.
  7. Presupuesto sin registro — No actualizar el presupuesto en state.yaml = pérdida de control de costes. Actualizar al final de cada comando.
  8. 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.
  9. 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 _store interno.
  10. Funciones de consulta puras con efectos secundarios — T1 midió: detectDiscrepancy modificaba 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

Skills relacionados