BriarForge/dev-grill-spec-driven

Grillen, dann spezifikationsgetriebene Entwicklung

Zwei Workflows, nacheinander ausgeführt, mit einer Übergabe dazwischen:

1. Grillen (Matt Pocock, grill-me → to-spec): Befrage den Benutzer als Entscheidungsbaum, Runde für Runde, bis nichts mehr stillschweigend angenommen wird. Dann synthetisiere das vereinbarte Verständnis in einer Spezifikation, ohne etwas Neues zu fragen.
2. Bauen (DeepLearning.AI + JetBrains, Spec-Driven Development with Coding Agents): Die Spezifikation landet im Repository als requirements.md, plan.md und validation.md in einem datierten Verzeichnis, wird Aufgaben-Gruppe für Aufgaben-Gruppe auf einem eigenen Branch implementiert, gegen validation.md validiert, im Changelog festgehalten, gemergt und die Roadmap wird neu geplant.

Das Grillen ersetzt das feste Drei-Fragen-Interview (Umfang / Entscheidungen / Kontext) des SDD-Kurses mit einem vollständigen Entscheidungsbaum-Interview. Der SDD-Kurs ersetzt das "Veröffentlichen im Issue-Tracker" von to-spec durch Spezifikationsdateien, die neben dem Code leben und sich mit ihm ändern.

Übersicht

Verwenden, wenn eine Änderung groß genug ist, dass es günstiger ist, sie zuerst aufzuschreiben, als Nacharbeit zu leisten: ein neues Feature, eine Roadmap-Phase, ein MVP-Sprint oder das Hinzufügen von SDD zu einer Legacy-Codebasis. Überspringen für Einzeiler-Fixes und reine Fehlersuche (verwende pstack-engineering für Ursachenanalyse).

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

Harte Tore (niemals überspringen):

• Keine Spezifikationsdatei wird geschrieben, bis der Benutzer bestätigt hat, dass das Grillen zu einem gemeinsamen Verständnis geführt hat (Tor A).
• Kein Code wird geschrieben, bis der Benutzer die Spezifikationsdateien genehmigt hat (Tor B).
• Nichts wird gemergt, bis jeder Punkt in validation.md bestanden ist (Tor C).

Ausführungsanweisungen

Löse SPECS=${SDD_SPECS_DIR:-specs} und `BASE=${SDD_BASE_BRANCH:-}`` am Anfang auf. Pfade unten sind relativ zum Projektstammverzeichnis.

Stufe 0 — Orientieren (Fakten sind dein Job)

1. Lese die AGENTS.md / CLAUDE.md, README.md sowie etwaige Glossare oder ADRs des Projekts. Befolge die eigenen Git-Regeln des Repos (Wrapper, Branch-Namen, kein force-push).
2. Prüfe auf eine Verfassung: $SPECS/mission.md, $SPECS/tech-stack.md, $SPECS/roadmap.md.
   • Alle vorhanden → gehe zu Stufe 1 für das nächste Feature.
   • Fehlend, neues Projekt → Das erste Grillen betrifft die Verfassung selbst (Mission, Zielgruppe, Tech-Stack-Lücken). Seine Ausgabe sind die drei Dateien, wobei roadmap.md in sehr kleine Phasen unterteilt ist, die jeweils unabhängig auslieferbar sind.
   • Fehlend, bestehende Codebasis (Legacy) → Untersuche zuerst den Code und entwerfe die Verfassung basierend auf dem, was tatsächlich vorhanden ist (Stack, Konventionen, ausgelieferte Features als abgeschlossene Phasen), befrage dann nur die Lücken und die zukünftige Roadmap.
3. Wenn der Benutzer kein Feature benannt hat, ist das Ziel die nächste Phase: der erste Roadmap-Abschnitt, dessen Einträge alle nicht markiert sind ([ ]).
4. Untersuche den Code, den das Feature berühren wird. Frage den Benutzer niemals etwas, was das Repository, die Tools oder die Dokumentation beantworten können. Delegiere breite Untersuchungen an einen frischen Unter-Agenten, wenn das Framework einen hat, und blockiere keine unabhängigen Fragen damit.

Stufe 1 — Grillen (Entscheidungsbaum-Interview)

Befrage den Benutzer unerbittlich, bis ein gemeinsames Verständnis erreicht ist. Behandele den Plan als Entscheidungsbaum: Jede Entscheidung verzweigt sich in die Entscheidungen, die von ihr abhängen.

• Arbeite in Runden. Die Frontier ist jede offene Entscheidung, deren Voraussetzungen bereits geklärt sind. Frage die gesamte Frontier in einer Runde ab, dann warte.
• Nummeriere jede Frage und gib deine empfohlene Antwort. Formuliere sie so, dass "Ja" die Empfehlung akzeptiert.
• Eine Frage, die von einer anderen noch in dieser Runde offenen Frage abhängt, gehört zu einer späteren Runde.
• Deckt über die Runden hinweg mindestens die SDD-Achsen ab: Umfang (was es sammelt, bereitstellt, tut; Datenstruktur), Entscheidungen (Speicherung, Sichtbarkeit, Validierung, UX-Muster, Architektur), Kontext (Ton, Einschränkungen, Stack-Grenzen, offene Fragen) und Test-Nahtstellen: wo das Feature getestet wird. Bevorzuge vorhandene Nahtstellen und die höchstmögliche Nahtstelle; ideal ist eine.
• Neue Abhängigkeiten, Schemaänderungen und öffentliche API-Änderungen sind immer explizite Fragen, niemals Annahmen (tech-stack.md ist die maßgebliche Quelle).

Rundenformat:

❓ **Q1** - **<Titel>**: <Frage, ggf. Optionen>

➡️ <Empfohlene Antwort>

---

❓ **Q2** - ...

Wenn das Framework ein strukturiertes Fragenwerkzeug hat (Claude Code AskUserQuestion), kannst du es für Runden mit bis zu vier Multiple-Choice-Fragen verwenden; andernfalls verwende das Textformat oben.

Das Grillen endet, wenn die Frontier leer ist. Fasse die geklärten Entscheidungen in einer kurzen Liste zusammen und bitte den Benutzer um Bestätigung.

Tor A: fahre nicht fort, bis der Benutzer die Zusammenfassung bestätigt.

Stufe 2 — Zur Spezifikation (Synthese, keine neuen Fragen)

Wandle das Gespräch in die Spezifikation um. Interviewe nicht erneut; wenn eine echte Lücke auftaucht, bedeutet das, dass das Grillen einen Zweig übersehen hat: frage nur diese eine Frage, dann fahre fort.

1. Erstelle den Branch von $BASE: phase-<N>-<kebab-name> für eine Roadmap-Phase, andernfalls feature/<kebab-name> (oder die eigene Konvention des Repos).
2. Lese $SPECS/mission.md und $SPECS/tech-stack.md sowie vorhandene Feature-Spezifikationen auf den Hausstil hin erneut.
3. Erstelle $SPECS/YYYY-MM-DD-<feature-name>/ mit dem heutigen Datum und schreibe die drei Dateien aus references/spec-templates.md:
   • requirements.md — der to-spec-Inhalt (Problem, Lösung, eine umfangreiche nummerierte Liste von User Stories, Implementierungsentscheidungen, Testentscheidungen, außerhalb des Rahmens) plus die SDD-Abschnitte Umfang / Entscheidungen / Kontext. Keine Dateipfade oder Code-Schnipsel, außer einem gekürzten Prototyp-Schnipsel, der eine Entscheidung präziser festlegt als Prosa.
   • plan.md — nummerierte Aufgaben-Gruppen, jede unabhängig implementierbar und testbar, mit nummerierten Unteraufgaben.
   • validation.md — automatisierte Prüfungen (genaue Befehle), manueller Durchlauf, Randfälle, Tonfall-Prüfung für benutzerseitige Texte sowie eine Definition of Done.
4. Optional, wenn der Benutzer fragt oder das Repo Arbeit in Issues verfolgt: veröffentliche die Anforderungen auch als Issue (gh issue create) und verlinke es von requirements.md.
5. Zeige dem Benutzer die drei Dateien (Pfade plus eine kurze Zusammenfassung).

Tor B: warte auf Genehmigung. Feedback ("füge eine Aufgaben-Gruppe für X hinzu", "Komponenten kommen in ihre eigenen Dateien") wird zuerst auf die Spezifikation angewendet, und alle Dateien werden synchron gehalten.

Stufe 3 — Implementieren

1. Implementiere Aufgaben-Gruppen in der Reihenfolge. Nach jeder Gruppe: führe die Tests und Typprüfungen des Projekts aus, committe mit einer Nachricht, die die Gruppe benennt, und hake ihre Kästchen in plan.md ab.
2. Wenn die Implementierung zeigt, dass die Spezifikation falsch oder unvollständig war, aktualisiere die Spezifikation im selben Commit wie den Code, der davon abweicht. Spezifikationen und Code driften nie auseinander.
3. Gruppen ohne Abhängigkeiten voneinander können an parallele Unter-Agenten gehen (jeder in einem eigenen Worktree; befolge die Worktree-Regeln des Hosts), die von dir zurückgemergt werden.
4. Keine neuen Abhängigkeiten ohne Genehmigung des Benutzers, selbst wenn eine Gruppe eine "braucht".

Stufe 4 — Validieren

1. Führe jede automatisierte Prüfung in validation.md aus und füge die tatsächliche Ausgabe ein.
2. Gehe die manuellen Prüfungen durch (bei einer UI: führe sie tatsächlich aus: Browser-Automatisierung oder Screenshots, nicht "sollte funktionieren").
3. Optionale Tiefenprüfung: Erzeuge Prüfer aus drei Perspektiven (Korrektheit, Spezifikationskonformität, Wartbarkeit) über den Branch-Diff, behebe dann, was blockiert.
4. Frage den Benutzer, ob die Spezifikation angesichts des Gebauten präzisiert werden muss.

Tor C: jeder Punkt der Definition-of-Done ist bestanden, oder der Benutzer verzichtet explizit auf einen (vermerke den Verzicht in validation.md).

Stufe 5 — Den Kreislauf schließen

1. Markiere die Phase in $SPECS/roadmap.md als abgeschlossen ([x]).
2. Aktualisiere CHANGELOG.md (# Changelog, ## YYYY-MM-DD-Überschriften neueste zuerst, ein Aufzählungspunkt pro sinnvoller Änderung seit dem letzten aufgezeichneten Datum). Verwende eine Projekt-changelog-Fähigkeit, falls vorhanden.
3. Committe, wechsle zu $BASE, merge den Branch, lösche ihn, pushe gemäß den Regeln des Repos.
4. Neuplanung: Frage, ob irgendetwas Gelerntes mission.md, tech-stack.md oder die Roadmap ändert (Phasen zusammenführen, aufteilen oder neu anordnen). Querschnittsentscheidungen (z.B. "Verwende Vitest", "Responsive UI") gehen in tech-stack.md / mission.md und werden auf bestehende Spezifikationen zurückportiert.
5. Biete die nächste Phase an: Sie beginnt erneut bei Stufe 1.

Umgebungsvariablen

Variable	Standard	Beschreibung
SDD_SPECS_DIR	specs	Verfassungs- und Feature-Spezifikationsverzeichnis, relativ zum Projektstammverzeichnis
SDD_BASE_BRANCH	Standardbranch des Repo	Branch, von dem Features abgezweigt und in den sie gemergt werden

Verifikations-Checkliste

• Verfassung existiert (mission.md, tech-stack.md, roadmap.md) vor jeder Feature-Spezifikation
• Jede Grill-Frage wurde mit einer empfohlenen Antwort gestellt; keine Tatsache wurde gefragt, die das Repo beantworten konnte
• Benutzer hat die Entscheidungszusammenfassung bestätigt (Tor A), bevor eine Spezifikationsdatei geschrieben wurde
• requirements.md, plan.md, validation.md existieren unter $SPECS/YYYY-MM-DD-<name>/ auf einem Feature-Branch
• Benutzer hat die Spezifikation genehmigt (Tor B), bevor Code geschrieben wurde
• Jede Aufgaben-Gruppe mit bestandenen Tests committet; Plan-Kästchen abgehakt
• Spezifikation aktualisiert, wo immer die Implementierung davon abgewichen ist
• Alle validation.md-Prüfungen mit tatsächlicher Ausgabe ausgeführt (Tor C)
• Roadmap-Phase abgehakt, Changelog aktualisiert, Branch gemergt und gelöscht
• Neuplanungsfrage gestellt

Bekannte Fallstricke

• Endloses Grillen. Das Grillen endet, wenn die Frontier leer ist, nicht wenn dir die Neugier ausgeht. Stelle keine bereits geklärten Entscheidungen erneut; frage nicht nach Details, die in die Code-Überprüfung gehören.
• Interviewen in der Spezifikationsphase. Stufe 2 synthetisiert; neue Fragen dort bedeuten, dass das Grillen unvollständig war. Frage die eine fehlende Frage, kein zweites Interview.
• Schreiben vor Tor A/B. Der SDD-Kurs ist eindeutig: Nichts wird auf die Festplatte geschrieben, bis das Interview beantwortet ist. Code vor Spezifikationsgenehmigung macht die Methode zunichte.
• Zu große Phasen. Eine Phase, die nicht in einer Sitzung überprüft werden kann, sollte vor der Spezifikation in der Roadmap aufgeteilt werden.
• Spezifikationsdrift. Eine während der Implementierung gewünschte Änderung wird zuerst auf die Spezifikation angewendet, dann auf den Code. Eine Spezifikation, die nicht mehr zum Code passt, ist schlimmer als keine.
• Dateipfade in Anforderungen. Sie veralten schnell; beschreibe stattdessen Module und Schnittstellen (Pfade gehören höchstens in plan.md-Unteraufgaben).
• Repo-Regeln gewinnen. Branch-Namen, Push-Wrapper, Worktree-Positionen und Zuordnungsregeln aus der AGENTS.md des Repos überschreiben die Standardwerte hier.

Siehe references/spec-templates.md für die Dateivorlagen und references/sources.md für die Herkunft der einzelnen Teile.