Grill, luego desarrollo guiado por especificaciones

¿Qué hace Grill, luego desarrollo guiado por especificaciones?

Dos flujos de trabajo, ejecutados consecutivamente, con una transición entre ellos:

1. Grill (Matt Pocock, grill-me → to-spec): entrevista al usuario como un árbol de diseño, ronda tras ronda, hasta que nada se asuma en silencio. Luego sintetiza el entendimiento acordado en una especificación sin preguntar nada nuevo.
2. Build (DeepLearning.AI + JetBrains, Spec-Driven Development with Coding Agents): la especificación aterriza en el repositorio como requirements.md, plan.md y validation.md en un directorio con fecha, se implementa grupo de tarea por grupo de tarea en su propia rama, se valida contra validation.md, se registra en el changelog, se fusiona y se replanifica la hoja de ruta.

El grill reemplaza la entrevista fija de tres preguntas del curso SDD (Alcance / Decisiones / Contexto) con una entrevista completa de árbol de diseño. El curso SDD reemplaza la "publicación en el rastreador de incidencias" de to-spec con archivos de especificación que viven junto al código y cambian con él.

Resumen

Úsalo cuando un cambio sea lo suficientemente grande como para que escribirlo primero sea más barato que rehecho: una nueva funcionalidad, una fase de hoja de ruta, un sprint de MVP, o añadir SDD a una base de código heredada. Sáltalo para correcciones de una línea y para búsquedas de errores puros (usa pstack-engineering para causas raíz).

Frases desencadenantes: "grill me then spec it", "grill to spec", "spec-driven", "SDD", "feature spec", "work on the next phase", "start the next feature".

Compuertas duras (nunca saltar):

• No se escribe ningún archivo de especificación hasta que el usuario confirme que el grill alcanzó un entendimiento compartido (Compuerta A).
• No se escribe código hasta que el usuario haya aprobado los archivos de especificación (Compuerta B).
• No se fusiona nada hasta que todos los elementos de validation.md pasen (Compuerta C).

Instrucciones de ejecución

Resuelve SPECS=${SDD_SPECS_DIR:-specs} y BASE=${SDD_BASE_BRANCH:-<rama por defecto del repositorio>} al inicio. Las rutas a continuación son relativas a la raíz del proyecto.

Etapa 0 — Orientarse (los datos son tu trabajo)

1. Lee el AGENTS.md / CLAUDE.md del proyecto, el README.md, y cualquier glosario o ADR. Sigue las reglas de git del propio repositorio (envoltorios, nomenclatura de ramas, sin force-push).
2. Verifica si existe una constitución: $SPECS/mission.md, $SPECS/tech-stack.md, $SPECS/roadmap.md.
   • Todos presentes → ve a la Etapa 1 para la siguiente funcionalidad.
   • Faltan, proyecto nuevo → el primer grill trata sobre la propia constitución (misión, audiencia objetivo, brechas tecnológicas). Su resultado son los tres archivos, con roadmap.md dividido en fases muy pequeñas, cada una entregable de forma independiente.
   • Faltan, base de código existente (heredada) → primero explora el código y redacta la constitución a partir de lo que realmente hay (stack, convenciones, funcionalidades entregadas como fases completadas), luego grill solo las brechas y la hoja de ruta futura.
3. Si el usuario no nombró una funcionalidad, el objetivo es la siguiente fase: la primera sección de la hoja de ruta cuyos elementos están todos sin marcar ([ ]).
4. Explora el código que la funcionalidad tocará. Nunca le hagas al usuario una pregunta que el repositorio, las herramientas o la documentación puedan responder. Delega la exploración amplia a un subagente nuevo si el arnés lo tiene, y no bloquees preguntas no relacionadas en ello.

Etapa 1 — Grill (entrevista de árbol de diseño)

Entrevista al usuario sin descanso hasta alcanzar un entendimiento compartido. Trata el plan como un árbol de diseño: cada decisión se ramifica en las decisiones que dependen de ella.

• Trabaja en rondas. La frontera es cada decisión abierta cuyos prerrequisitos ya están resueltos. Pregunta toda la frontera en una ronda, luego espera.
• Numera cada pregunta y da tu respuesta recomendada. Redáctala para que "sí" acepte la recomendación.
• Una pregunta que depende de otra aún abierta en esta ronda pertenece a una ronda posterior.
• Cubre, a lo largo de las rondas, al menos los ejes de SDD: Alcance (lo que recopila, expone, hace; forma de los datos), Decisiones (almacenamiento, visibilidad, validación, patrón de UX, arquitectura), Contexto (tono, restricciones, límites del stack, preguntas abiertas) y Puntos de prueba: dónde se probará la funcionalidad. Prefiere puntos existentes y el punto más alto posible; lo ideal es uno solo.
• Nuevas dependencias, cambios de esquema y cambios en la API pública son siempre preguntas explícitas, nunca suposiciones (tech-stack.md es la autoridad).

Formato de ronda:

❓ **P1** - **<título>**: <pregunta, opciones si las hay>

➡️ <respuesta recomendada>

---

❓ **P2** - ...

Si el arnés tiene una herramienta de preguntas estructuradas (Claude Code AskUserQuestion), puedes usarla para rondas de hasta cuatro preguntas de opción múltiple; de lo contrario, usa el formato de texto anterior.

El grill termina cuando la frontera está vacía. Resume las decisiones acordadas en una lista breve y pide al usuario que confirme.

Compuerta A: no continúes hasta que el usuario confirme el resumen.

Etapa 2 — Hacia la especificación (síntesis, sin nuevas preguntas)

Convierte la conversación en la especificación. No vuelvas a entrevistar; si aparece una brecha real, significa que el grill omitió una rama: pregunta solo esa pregunta, luego reanuda.

1. Crea la rama desde $BASE: phase-<N>-<nombre-kebab> para una fase de hoja de ruta, de lo contrario feature/<nombre-kebab> (o la convención del repositorio).
2. Vuelve a leer $SPECS/mission.md y $SPECS/tech-stack.md, y las especificaciones de funcionalidades existentes para conocer el estilo de la casa.
3. Crea $SPECS/YYYY-MM-DD-<nombre-funcionalidad>/ con la fecha de hoy y escribe los tres archivos a partir de references/spec-templates.md:
   • requirements.md — el contenido de to-spec (problema, solución, una lista numerada extensa de historias de usuario, decisiones de implementación, decisiones de prueba, fuera de alcance) más las secciones SDD de Alcance / Decisiones / Contexto. Sin rutas de archivo ni fragmentos de código, excepto un fragmento de prototipo recortado que fije una decisión con más precisión que la prosa.
   • plan.md — grupos de tareas numerados, cada uno implementable y comprobable de forma independiente, con subtareas numeradas.
   • validation.md — verificaciones automatizadas (comandos exactos), recorrido manual, casos límite, verificación de tono para el texto dirigido al usuario, y una Definición de Hecho.
4. Opcional, si el usuario lo solicita o el repositorio rastrea el trabajo en incidencias: también publica los requisitos como una incidencia (gh issue create) y enlázala desde requirements.md.
5. Muestra al usuario los tres archivos (rutas más un breve resumen).

Compuerta B: espera la aprobación. Los comentarios ("añade un grupo de tareas para X", "los componentes van en sus propios archivos") se aplican a la especificación primero, y todos los archivos se mantienen sincronizados.

Etapa 3 — Implementar

1. Implementa los grupos de tareas en orden. Después de cada grupo: ejecuta las pruebas y la verificación de tipos del proyecto, haz commit con un mensaje que nombre el grupo, marca sus casillas en plan.md.
2. Si la implementación muestra que la especificación era incorrecta o incompleta, actualiza la especificación en el mismo commit que el código que se aparta de ella. Las especificaciones y el código nunca divergen.
3. Los grupos sin dependencia entre sí pueden ir a subagentes paralelos (cada uno en su propio árbol de trabajo; sigue las reglas de árbol de trabajo del anfitrión), fusionados por ti.
4. No se añaden nuevas dependencias sin la aprobación del usuario, incluso si un grupo "necesita" una.

Etapa 4 — Validar

1. Ejecuta cada verificación automatizada en validation.md y pega la salida real.
2. Recorre las verificaciones manuales (para una interfaz de usuario, condúcela realmente: automatización del navegador o capturas de pantalla, no "debería funcionar").
3. Revisión profunda opcional: genera revisores desde tres perspectivas (corrección, conformidad con la especificación, mantenibilidad) sobre el diff de la rama, luego corrige lo que impida avanzar.
4. Pregunta al usuario si la especificación necesita aclararse a la luz de lo construido.

Compuerta C: todos los elementos de la Definición de Hecho pasan, o el usuario renuncia explícitamente a uno (registra la renuncia en validation.md).

Etapa 5 — Cerrar el ciclo

1. Marca la fase como completa en $SPECS/roadmap.md ([x]).
2. Actualiza CHANGELOG.md (# Changelog, encabezados ## YYYY-MM-DD del más nuevo al más antiguo, un punto por cambio significativo desde la última fecha registrada). Usa una habilidad de changelog del proyecto si existe.
3. Haz commit, cambia a $BASE, fusiona la rama, elimínala, haz push según las reglas del repositorio.
4. Replanifica: pregunta si algo aprendido cambia mission.md, tech-stack.md o la hoja de ruta (fusiona, divide o reordena fases). Las decisiones transversales (por ejemplo, "usar Vitest", "interfaz de usuario responsiva") van a tech-stack.md / mission.md y se retroportan a las especificaciones existentes.
5. Ofrece la siguiente fase: comienza de nuevo en la Etapa 1.

Variables de entorno

Variable	Valor por defecto	Descripción
SDD_SPECS_DIR	specs	Directorio de constitución y especificaciones de funcionalidades, relativo a la raíz del proyecto
SDD_BASE_BRANCH	rama por defecto del repositorio	Rama desde la que se cortan y a la que se fusionan las funcionalidades

Lista de verificación

• Existe la constitución (mission.md, tech-stack.md, roadmap.md) antes de cualquier especificación de funcionalidad
• Cada pregunta del grill se hizo con una respuesta recomendada; no se preguntó ningún hecho que el repositorio pudiera responder
• El usuario confirmó el resumen de decisiones (Compuerta A) antes de escribir cualquier archivo de especificación
• requirements.md, plan.md, validation.md existen en $SPECS/YYYY-MM-DD-<nombre>/ en una rama de funcionalidad
• El usuario aprobó la especificación (Compuerta B) antes de escribir código
• Cada grupo de tareas se confirmó con las pruebas pasando; las casillas del plan están marcadas
• La especificación se actualizó donde la implementación se apartó de ella
• Todas las verificaciones de validation.md se ejecutaron con salida real (Compuerta C)
• Fase de hoja de ruta marcada, changelog actualizado, rama fusionada y eliminada
• Se preguntó sobre replanificación

Errores conocidos

• Grillar para siempre. El grill termina cuando la frontera está vacía, no cuando te quedas sin curiosidad. No vuelvas a preguntar decisiones ya resueltas; no preguntes sobre detalles que pertenecen a la revisión de código.
• Entrevistar en to-spec. La Etapa 2 sintetiza; las nuevas preguntas allí significan que el grill estuvo incompleto. Pregunta la única pregunta faltante, no una segunda entrevista.
• Escribir antes de la Compuerta A/B. El curso SDD es explícito: nada se escribe en disco hasta que se responda la entrevista. Código antes de la aprobación de la especificación derrota el método.
• Fases demasiado grandes. Una fase que no se pueda revisar en una sola sesión debe dividirse en la hoja de ruta antes de especificar.
• Deriva de la especificación. Un cambio solicitado durante la implementación se aplica primero a la especificación, luego al código. Una especificación que ya no coincide con el código es peor que ninguna.
• Rutas de archivo en los requisitos. Se vuelven obsoletas rápidamente; describe módulos e interfaces en su lugar (las rutas pertenecen como máximo a las subtareas de plan.md).
• Las reglas del repositorio ganan. Los nombres de rama, envoltorios de push, ubicaciones de árbol de trabajo y reglas de atribución del AGENTS.md del repositorio anulan los valores predeterminados aquí.

Consulta references/spec-templates.md para las plantillas de archivos y references/sources.md para saber de dónde vino cada parte.