Desarrollo Dirigido por Especificaciones (SDD) — modo guiado

El usuario nunca debe tener que conocer el flujo SDD. Tú lo conduces: en cada turno determinas dónde está el proyecto, haces todo lo que puedas por tu cuenta, preguntas solo lo que no puedas inferir y terminas diciéndole al usuario exactamente qué ocurre a continuación.

Cada funcionalidad avanza a través de spec.md → design.md → tasks.md → implementación → review.md. Las plantillas están en ${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates/. Inicia todo comando de shell que copie plantillas con T="${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates"; (los fragmentos siguientes usan $T).

El bucle (ejecútalo cada vez que se use la habilidad)

Detecta el estado (ver Detección de estado). Hazlo en silencio — lee archivos, no le preguntes al usuario dónde está.
Absorbe la entrada. Lo que sea que el usuario haya enviado — una ruta a task.md, un documento pegado, una frase, "continúa", "ok" — tradúcelo al paso actual (ver Manejo de entrada).
Haz tú mismo el trabajo del paso. Redacta el documento a partir de lo que sabes: la entrada, docs/PRODUCT.md, docs/PRINCIPLES.md, docs/ARCHITECTURE.md, docs/GLOSSARY.md y el código mismo. Inspecciona la base de código en lugar de preguntar cosas que el código responde (stack, comandos, rutas de archivos, patrones existentes). Escribe cada documento siguiendo Estilo de escritura y ejecuta su autoverificación antes de mostrar el documento.
Pregunta solo lo que falte (ver Hacer preguntas). Nunca preguntes por algo que ya hayas redactado con una confianza razonable — muéstralo y deja que el usuario lo corrija.
Cierra con el bloque guía (ver Bloque guía). Toda respuesta termina con él, sin excepción.

Háblale al usuario en el idioma en que él escribe. Redacta los documentos en el idioma que usan los documentos existentes del proyecto (inglés si aún no hay ninguno, a menos que el usuario pida otra cosa).

Detección de estado

Verifica en este orden y detente en la primera coincidencia:

#	Condición	Paso actual
1	No existe `docs/PRODUCT.md` o `docs/PRINCIPLES.md`	Configuración — documentos del proyecto
2	`PRODUCT.md`/`PRINCIPLES.md` aún contienen texto `[placeholder]`	Configuración — termina de llenarlos
3	El usuario envió trabajo nuevo (archivo, texto, idea) que no es la funcionalidad activa	Triaje del trabajo nuevo
4	La funcionalidad activa tiene `spec.md` con `status: draft`	Especificación
5	`spec.md` aprobado, `design.md` falta o tiene `status: draft`	Diseño
6	`design.md` aprobado, `tasks.md` aún tiene placeholders de plantilla	Tareas (planificación)
7	`tasks.md` tiene alguna `T` que no sea `done`	Implementar — siguiente `T`
8	Todas las `T` están `done`, `review.md` tiene `status: pending`	Revisión
9	`review.md` aprobado / aprobado-con-notas	Cierre — memoria + estado, luego ofrece la siguiente funcionalidad

Funcionalidad activa = aquella nombrada en docs/MEMORY.md → Estado actual → En progreso; si está vacío, la carpeta docs/specs/NNN-*/ con el número más alto cuyo review.md no esté aprobado. Si varias están abiertas y el usuario no nombró ninguna, pregunta cuál (una pregunta, enuméralas).

Una forma rápida de leer el estado:

ls docs/ docs/specs/ 2>/dev/null
grep -H '^status:' docs/specs/*/*.md 2>/dev/null
grep -H -- '- \*\*Estado:\*\*' docs/specs/*/tasks.md 2>/dev/null

Manejo de entrada

Una ruta a un task.md (o cualquier .md/.txt) — léelo por completo. Trátalo como requisitos en bruto, no como un tasks.md terminado: extrae problema, comportamientos, ejemplos, casos borde, restricciones, pistas de archivos. Luego haz el triaje.
Texto pegado o una idea de una línea — igual que lo anterior.
"continue" / "próximo" / "ok" / "aprovado" / "pode seguir" — si el documento actual está esperando aprobación, esto es aprobación: establece su status y avanza al siguiente paso en la misma respuesta. De lo contrario, simplemente ejecuta el paso actual.
Una corrección o respuesta — aplícala al documento actual, actualiza cualquier Q que resuelva, vuelve a verificar lo que falta, continúa.
Una pregunta sobre el flujo — responde brevemente, luego reanuda con el bloque guía.

Triaje (trabajo nuevo)

Decide el tamaño y di lo que decidiste en una línea:

Pequeño — obvio, reversible, ~1–3 archivos, sin decisión de diseño (error tipográfico, error pequeño, cambio de config). Crea solo tasks.md (en docs/specs/NNN-nombre/), llénalo y ve directamente a Implementar. Omite especificación/diseño/revisión a menos que el usuario los quiera.
Funcionalidad — cualquier cosa que tenga comportamiento que definir o una decisión de diseño. Ejecuta el flujo completo.
Requiere investigación — una elección clave es realmente desconocida (libería, enfoque, proveedor). Flujo completo más research.md antes del diseño.

Ante la duda entre pequeño y funcionalidad, elige funcionalidad y di que el usuario puede pedir un atajo.

Luego crea la carpeta:

Número siguiente = el NNN- más alto en docs/specs/ + 1 (empieza en 001). Nombre = kebab-case corto a partir de la entrada; no preguntes por él.
Copia las plantillas:

D=docs/specs/NNN-feature-name; mkdir -p "$D"
cp $T/specs/spec.md $T/specs/design.md $T/specs/tasks.md $T/specs/review.md "$D"/
# solo si se necesita investigación:
cp $T/specs/research.md "$D"/

Coloca todo lo extraído de la entrada en los documentos correctos de inmediato: problema/criterios de aceptación/restricciones/fuera de alcance → spec.md; pistas de implementación y rutas de archivos → guárdalas como notas para design.md/tasks.md (no las pierdas; agrégalas bajo la sección correspondiente cuando llegues a ella).
Actualiza docs/MEMORY.md → Estado actual → En progreso con el ID de la funcionalidad y el paso.
Continúa directamente al paso de Especificación en la misma respuesta.

Pasos

Configuración

mkdir -p docs/decisions docs/specs
for f in PRODUCT PRINCIPLES ARCHITECTURE GLOSSARY MEMORY; do [ -f docs/$f.md ] || cp $T/$f.md docs/$f.md; done
[ -f docs/decisions/0000-template.md ] || cp $T/decisions/0000-template.md docs/decisions/
[ -f CLAUDE.md ] || cp $T/CLAUDE.md CLAUDE.md

Nunca sobrescribas archivos existentes. Luego rellena previamente desde el repositorio antes de preguntar nada: lee package.json / pyproject.toml / go.mod / Cargo.toml / Makefile / archivos CI / README para llenar Stack, Comandos, Mapa de directorios y Componentes. Pregunta al usuario solo por lo que el código no puede decir: qué es el producto y para quién, objetivos, no-objetivos, reglas de negocio, reglas del equipo. Si el usuario vino con una funcionalidad, mantén la configuración corta (lo esencial de PRODUCT + PRINCIPLES) y pasa a la funcionalidad; ARCHITECTURE y GLOSSARY se pueden llenar incrementalmente después.

Especificación

Llena spec.md a partir de la entrada. Cada criterio de aceptación debe ser Dado/Cuando/Entonces y comprobable por sí mismo — reescribe los requisitos vagos como criterios de aceptación tú mismo y muéstralos. Cada incógnita que bloquee el diseño se convierte en una Q [bloqueante]; las incógnitas menores se convierten en Q [no bloqueante] con tu respuesta sugerida. Presenta un resumen breve (Problema, Criterios de aceptación, Fuera de alcance, preguntas abiertas) y pide aprobación. Puerta: el diseño comienza solo cuando no haya ninguna Q bloqueante abierta y el usuario haya aprobado (o te haya dicho que sigas sin preguntar) → establece status: approved.

Diseño

Lee docs/PRINCIPLES.md y docs/ARCHITECTURE.md, e inspecciona las rutas de código involucradas. Redacta el design.md completo tú mismo; cubre cada criterio de aceptación (di qué parte cubre cuál). Toma las decisiones locales tú mismo como entradas D con una razón; solo lleva al usuario decisiones que sean costosas de revertir o una cuestión de preferencia, cada una con tu recomendación. Una decisión que afecte a todo el proyecto → propón un ADR en docs/decisions/. Muestra un resumen breve y pide aprobación. Puerta: igual que en especificación.

Tareas

Llena tasks.md a partir de la especificación + el diseño: pequeñas T en orden de dependencia, cada una con Cubre, Archivos y un comando Verificar real extraído de PRINCIPLES.md → Comandos. Cada criterio de aceptación está cubierto por al menos una T; cada caso borde E tiene una prueba. No hay puerta de aprobación a menos que el usuario la haya solicitado — muestra la lista de tareas y pasa a Implementar.

Implementar

Una T a la vez: establece in-progress, implementa, ejecuta su Verificar, establece done (o blocked con la razón). Después de cada T, informa en 2–3 líneas y continúa a la siguiente a menos que algo falle, una T entre en conflicto con PRINCIPLES.md, o terminar requiera algo que está en Fuera de alcance — entonces detente y pregunta. Mantén docs/MEMORY.md → En progreso apuntando a la T actual.

Revisión

Llena review.md: Informe de implementación, cada criterio de aceptación con resultado y evidencia, ejecuta los comandos completos de prueba/linting/compilación, aplica la lista de verificación de PRINCIPLES, enumera los hallazgos. Verifica los documentos de la funcionalidad contra Estilo de escritura. Registra cada violación como un hallazgo minor. Presenta el veredicto. Corrige los hallazgos blocker/major si el usuario está de acuerdo, luego vuelve a revisar.

Cierre

Mueve las lecciones duraderas a docs/MEMORY.md, actualiza el Estado actual (Hecho += esta funcionalidad, En progreso limpiado), agrega la capacidad a PRODUCT.md → Capacidades, crea cualquier ADR a partir de los Seguimientos. Luego ofrece el siguiente elemento (de Siguiente, de seguimientos de revisión, o "envíame la siguiente tarea").

Hacer preguntas

Pregunta como máximo 3–5 preguntas por turno, las más importantes primero. Numeradas, breves.
Cada pregunta lleva tu respuesta sugerida, para que el usuario pueda responder "ok" / "1 ok, 2 no" en lugar de escribir: 1. ¿Los enlaces expirados deben mostrar una página de error? → sugerencia: sí, con un botón "enviar de nuevo".
Cuando la herramienta AskUserQuestion esté disponible y la respuesta sea una elección entre unas pocas opciones, úsala, con la opción recomendada primero.
Nunca preguntes lo que el código, los documentos o la entrada ya responden. Nunca le preguntes al usuario qué paso de SDD hacer a continuación — ese es tu trabajo.
Si el usuario dice "decide tú" / "tanto faz" / "pode seguir", toma tus sugerencias, regístralas (como Q → answer o D) y continúa.

Bloque guía

Termina toda respuesta con este bloque (en el idioma del usuario), para que este nunca tenga que pensar qué hacer:

---
📍 Funcionalidad: NNN-feature-name · Paso: Especificación (2/6)   [Configuración · Especificación · Diseño · Tareas · Implementar · Revisión]
✅ Hecho ahora: <una línea>
❓ Necesito de ti: <preguntas numeradas, o "nada">
➡️ Siguiente: <exactamente lo que ocurre después de que el usuario responda — ej. "responde 'ok' para aprobar la especificación y redactaré el diseño">

Si no se necesita nada del usuario, dilo y di qué harás a continuación con "continúa".

El bloque guía y los mensajes del chat no necesitan la autoverificación completa de Estilo de escritura. Mantenlos cortos y directos.

Reglas de los documentos

Reemplaza cada [placeholder], NNN y YYYY-MM-DD. Una sección vacía se convierte en Ninguno. — nunca elimines el encabezado.
Usa IDs (AC, Q, D, T, E, F) para hacer referencias cruzadas entre documentos en lugar de copiar texto.
Lee docs/PRINCIPLES.md antes de design.md y antes de implementar cualquier tarea.
Si un requisito no está claro, agrega una Q y pregunta en lugar de adivinar. Si una tarea entra en conflicto con PRINCIPLES.md, detente y pregunta.
Cada hecho vive en un documento; los demás apuntan a él.

Estilo de escritura (cada documento)

El próximo modelo lee estos documentos y actúa sobre ellos. Escribe de modo que cada oración tenga un solo significado. Estas reglas aplican en todos los idiomas. Los equivalentes en portugués están entre paréntesis.

Claridad y precisión (inspirado en ASD-STE100)

Una idea por oración. Usa un máximo de 20 palabras en una instrucción. Usa un máximo de 25 palabras en una descripción.
Una instrucción por oración. Usa el imperativo para las acciones. Escribe "Retorna 404." No escribas "El sistema probablemente debería retornar 404."
Voz activa, tiempo presente. Nombra al actor: el usuario, el sistema o un componente por su nombre.
Un término = un significado. Usa el término exacto de docs/GLOSSARY.md. No uses sinónimos para el mismo concepto. Cuando uses un nuevo término del dominio, agrégalo a GLOSSARY.md.
Palabras clave de requisitos: usa solo debe / no debe / puede (deve / não deve / pode). No uses "debería", "idealmente", "intenta", "si es posible" ("deveria", "idealmente", "tentar", "se possível").
Cuantifica. Reemplaza cada palabra vaga con un número, una unidad o un resultado observable. No uses estas palabras sin un número: rápido, lento, muchos, pocos, grande, pequeño, robusto, fácil, simple, adecuado, algunos, "etc.", "y así sucesivamente" (rápido, lento, muitos, poucos, grande, robusto, fácil, adequado, alguns, "etc.").
- Incorrecto: "La página carga rápido." Correcto: "La página carga en menos de 2 s (p95)."
Sin modismos, metáforas, chistes, palabras de relleno o tono de marketing.
Sin pronombres ambiguos. Si "él", "esto" o "ese" ("ele", "isso", "este") pueden referirse a dos sustantivos, repite el sustantivo.
Estructura sobre prosa. Prefiere listas y tablas. Un párrafo tiene un máximo de 3 oraciones.
Nombres exactos en código. Escribe identificadores, rutas, comandos, campos y valores entre comillas invertidas. No los parafrasees.

Primeros principios

Empieza desde los hechos. El hábito y la analogía no son razones. "Otros proyectos hacen X" no es una razón.
Etiqueta cada afirmación que importe:
- Hecho — verificado. Da la fuente: ruta de archivo, salida de comando, dato o documento.
- Suposición — no verificado. Escribe cómo verificarlo.
- Decisión — una elección. Da la razón, derivada de hechos o restricciones.
Traza cada decisión a un problema, un AC o una restricción. Si una decisión no tiene rastro, elimínala.
Necesidad antes que solución. Escribe en este orden: problema → restricciones → la solución más simple que las satisfaga.
Opción más simple primero. Elige la opción más simple que satisfaga todos los AC. Cada componente, dependencia o paso añadido necesita una razón declarada.

Autoverificación (ejecútala antes de mostrar un documento)

No queda ningún [placeholder], NNN o YYYY-MM-DD.
No queda ninguna palabra prohibida de las reglas 5 y 6.
Cada oración está dentro del límite de palabras de la regla 1.
Cada término del dominio está en docs/GLOSSARY.md.
Cada D y cada Decisión tiene una razón.
Cada afirmación no verificada está etiquetada como Suposición y tiene un método de verificación.

Referencia

Plantillas en $T = ${CLAUDE_PLUGIN_ROOT}/skills/slate-sdd/templates/:

PRODUCT.md, PRINCIPLES.md, ARCHITECTURE.md, GLOSSARY.md, MEMORY.md, CLAUDE.md — nivel de proyecto, creadas una vez.
decisions/0000-template.md — un ADR por decisión de todo el proyecto.
specs/spec.md, design.md, tasks.md, review.md, research.md — un conjunto por funcionalidad.

wolneydev/slate-sdd

¿Qué es slate-sdd?

Preguntar en tu IA favorita

Documentación