Spezifikationsgetriebener Entwicklungsworkflow: Von den Anforderungen zum Code

Spec-Driven Development funktioniert, wenn die Spezifikation ein Workflow ist und kein Dokument, das man nach dem Kickoff beiseitelegt. Es geht nicht darum, ein umfangreiches Produktanforderungsdokument zu erstellen.

Es geht darum, eine Abfolge überprüfbarer Artefakte durchzuarbeiten, von denen jedes die Mehrdeutigkeit reduziert, bevor jemand – ob Mensch oder KI-Agent – den Produktionscode ändert.

Wenn Sie nicht wissen, was SDD konzeptionell ist, beginnen Sie mit Was ist Spec-Driven Development? für Definitionen, Vergleiche mit TDD und BDD sowie den Fall, die Spezifikation als Quelle der Wahrheit zu betrachten. Dieser Artikel in der App-Architektur-Dokumentationsgruppe ist der operative Leitfaden. Er führt durch die fünf Phasen, zeigt, was jedes Artefakt enthalten sollte, erklärt, wo KI-Agenten zum Einsatz kommen, und liefert wiederverwendbare Vorlagen, die Sie heute noch in Ihr Repository kopieren können.

SDD ist ein Workflow, kein Dokument

Das häufigste Versagen in der spec-getriebenen Entwicklung besteht darin, die Spezifikation als Bürokratie zu betrachten. Ein Team schreibt ein langes Anforderungsdokument, speichert es in einem Wiki und codiert dann aus dem Gedächtnis und aus Chat-Threads. Die Spezifikation existiert, treibt aber nichts an. Das ist Dokumentations-Theater und schlimmer als keine Spezifikation, weil es falsches Vertrauen schafft.

Ein funktionierender SDD-Workflow erzeugt eine Kette von Artefakten, von denen jedes vor Beginn der nächsten Phase überprüft wird. Anforderungen reduzieren die Produkt-Mehrdeutigkeit. Das Design reduziert die technische Mehrdeutigkeit. Aufgaben reduzieren die Ausführungs-Mehrdeutigkeit. Die Implementierung erzeugt Code gegen ein bekanntes Ziel. Die Validierung beweist, dass die Kette gehalten hat. Wenn eine Phase einen Fehler aufdeckt, korrigieren Sie das Artefakt und führen den Prozess von diesem Punkt aus erneut aus – nicht nachdem dreitausend Zeilen Abweichung in main gelandet sind.

Der Workflow ist tool-unabhängig. Sie können ihn mit Markdown-Dateien in Git ausführen, mit GitHub Spec Kit, mit Cursor-Plänen, mit einem erzwungenen Skills-Paket wie Superpowers oder mit einem einfachen Texteditor und einem disziplinierten Prüfer. Entscheidend sind die Reihenfolge und die Überprüfungsgrenzen, nicht die Marke der Werkzeuge.

Phase 1 – Anforderungen spezifizieren

Die Spezifizierungsphase beantwortet, welches Problem Sie lösen und wie „fertig“ aussieht. Sie vermeidet bewusst, wie man es baut. In dem Moment, in dem Ihre Anforderungsspezifikation „Redis sorted sets verwenden“ sagt, haben Sie aufgehört, zu spezifizieren, und begonnen, im falschen Dokument zu designen. Halten Sie die Implementierung aus den Anforderungen heraus. Legen Sie sie in den Plan.

Problemstellung und Nutzer

Beginnen Sie mit einem Absatz, der das Problem in einfacher Sprache beschreibt. Nennen Sie die betroffenen Nutzer und die Situation, die das Problem schmerzhaft macht. Eine gute Problemstellung ermöglicht es einem Prüfer, der nicht an der Planungsbesprechung teilgenommen hat, zu entscheiden, ob eine vorgeschlagene Lösung tatsächlich den Schmerz adressiert.

Beispiel für eine API-Ratenbegrenzungs-Funktion:

API-Konsumenten im Free-Tier können unbegrenzte Anfragen senden, was zu Kosten-Spitzen und „noisy-neighbor“-Auswirkungen auf bezahlte Tenant führt. Plattform-Operatoren benötigen ein durchsetzbares Limit pro Key ohne manuelle Intervention.

Ziele, Nicht-Ziele und Akzeptanzkriterien

Ziele beschreiben Ergebnisse, die Sie liefern werden. Nicht-Ziele beschreiben verlockende angrenzende Arbeit, die Sie ausdrücklich nicht tun werden. Zusammen begrenzen sie die Kreativität des Agenten, was essenziell ist, wenn KI-Tools andernfalls „hilfreich“ den Umfang erweitern.

Akzeptanzkriterien sollten so präzise sein, dass sich jedes auf mindestens einen Test abbilden lässt. „Der Endpunkt ist sicher“ ist kein Akzeptanzkriterium. „Nicht-authentifizierte Anfragen erhalten HTTP 401“ schon. Wenn Sie kein konkretes Kriterium schreiben können, ist die Anforderung noch zu vage, um implementiert zu werden.

Offene Fragen

Listen Sie alle Entscheidungen auf, die noch nicht geklärt sind. Unklare Fragen sind kein Zeichen des Versagens. Sie sind die Spezifizierungsphase, die ihre Arbeit tut. Klären Sie sie, bevor Sie den Designplan schreiben, oder Sie zahlen für die Mehrdeutigkeit in Form von Implementierungs-Umarbeitungen.

Eine minimale Anforderungsvorlage:

## Problem
[Ein Absatz: Wer leidet, warum und was löst den Schmerz aus.]

## Nutzer
- [Primäre Nutzerrolle]
- [Sekundäre Nutzerrolle]

## Ziele
1. [Messbares Ergebnis]
2. [Messbares Ergebnis]

## Nicht-Ziele
- [Ausdrücklich außerhalb des Umfangs]
- [Ausdrücklich außerhalb des Umfangs]

## Akzeptanzkriterien
- [ ] [Verifizierbares Verhalten]
- [ ] [Verifizierbares Verhalten]

## Offene Fragen
- [ ] [Frage, die das Planen blockiert]

Phase 2 – Das Design planen

Die Planungsphase übersetzt Absicht in technische Entscheidungen. Hier gehören Redis sorted sets hin, zusammen mit Modulgrenzen, Schema-Änderungen, API-Verträgen, Migrationsschritten, Sicherheitsbeschränkungen und der Teststrategie. Der Plan leitet sich von der Anforderungsspezifikation plus den bestehenden Beschränkungen Ihres Projekts ab – Stack-Wahlen, Entscheidungsprotokolle und Konventionen, die in Dateien wie AGENTS.md oder einer Projektcharta gespeichert sind.

Architektur und betroffene Module

Nennen Sie die Module, Dienste oder Pakete, die sich ändern werden, und fassen Sie das Integrationsmuster zusammen. Wenn die Funktion eine Dienstgrenze überschreitet, dokumentieren Sie den Vertrag auf beiden Seiten. Agenten halluzinieren APIs, wenn Verträge implizit sind. Durch ihre explizite Festlegung im Plan werden erfundene Endpunkte und falsche Antwortformate verhindert.

Datenmodell, API-Verträge und Migrationen

Dokumentieren Sie Schema-Änderungen, neue Tabellen oder Felder, Indexanforderungen und Rückwärtskompatibilitätsregeln. Für HTTP-APIs schreiben Sie Methode, Pfad, Anfrageform, Antwortform und Fehlercodes. Für Events schreiben Sie Topic-Namen, Payload-Schemas und Liefersemantiken. Schließen Sie Migrationsschritte und Rollback-Hinweise ein, wenn sich das Datenmodell ändert.

Sicherheit, Observability und Teststrategie

Sicherheitsbeschränkungen gehören in den Plan, nicht als Afterthought in die Code-Review. Notieren Sie Authentifizierungsanforderungen, Autorisierungsregeln, Eingabevalidierungsgrenzen und Daten, die nicht in Logs erscheinen dürfen. Observability sollte Metriken, Logs oder Traces abdecken, die benötigt werden, um zu bestätigen, dass die Funktion in der Produktion funktioniert.

Die Teststrategie verknüpft sich mit den Akzeptanzkriterien. Identifizieren Sie, welche Kriterien Unit-Tests benötigen, welche Integrationstests und welche manuelle Verifikation. Wenn Sie Unit-Tests in Go oder Unit-Tests in Python verwenden, nennen Sie die Pakete und Testdateien, die Sie hinzufügen erwarten. Ein Plan ohne Teststrategie ist ein Plan, der mit Lücken ausgeliefert wird, die Sie erst in der Produktion entdecken.

Phase 3 – Implementierungsaufgaben aufteilen

Die Aufgabenphase zerlegt den Plan in Schnitte, die klein genug sind, um unabhängig implementiert, überprüft und validiert zu werden. Das macht die agentenunterstützte Entwicklung überprüfbar. Anstatt eines riesigen Diffs erhalten Sie eine Abfolge fokussierter Änderungen, von denen jede auf eine benannte Anforderung zurückverwiesen werden kann.

Aufgabengröße und Abhängigkeiten

Eine gute Aufgabe betrifft eine begrenzte Menge an Dateien, wird in einer Agentensitzung abgeschlossen und endet mit einem Verifikationsschritt. Aufgaben sollten Abhängigkeiten explizit deklarieren. Migrationsaufgaben laufen vor Code, der das neue Schema liest. Änderungen an Shared-Libraries laufen vor Konsumenten. Änderungen an Authentifizierungs-Middleware laufen vor Endpunkten, die vom neuen Verhalten abhängen.

Dateien, Validierung und Überprüfungspunkte

Jede Aufgabe sollte die wahrscheinlich zu ändernden Dateien, die erfüllten Akzeptanzkriterien und die Art der Validierung der Vollendung auflisten. Die Validierung kann ein Testbefehl, ein curl-Beispiel oder eine manuelle Prüfung in kopierbaren Schritten sein. Jede Aufgabe endet an einem menschlichen Überprüfungspunkt. Der Prüfer bestätigt, dass das Diff zur Aufgabbeschreibung passt, bevor die nächste Aufgabe beginnt.

Ein minimaler Eintrag für eine Aufgabe:

### Task 3 -- Add rate-limit middleware

**Depends on:** Task 1 (schema), Task 2 (repository)
**Files:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Satisfies:** AC-2 (429 over limit), AC-3 (limit headers in response)
**Validate:** `go test ./middleware/...` passes; curl over limit returns 429 with Retry-After
**Review checkpoint:** Confirm middleware runs after auth, before handler

Achten Sie auf explodierende generierte Aufgabenlisten. KI-Agenten können in Sekunden Pläne mit fünfzig Aufgaben erstellen. Die meisten dieser Aufgaben werden redundant oder zu granular sein, um effizient überprüft zu werden. Eine nützliche Aufgabenliste für eine mittlere Funktion hat oft fünf bis fünfzehn Einträge, nicht fünfzig.

Phase 4 – Eine Aufgabe nach der anderen implementieren

Die Implementierung ist bewusst schmal gehalten. Wählen Sie eine Aufgabe, geben Sie dem Agenten nur den Kontext, den er für diese Aufgabe benötigt, und stoppen Sie, wenn die Validierung besteht. Kontext-Resets zwischen Aufgaben sind eine Funktion, kein Fehler. Sie verhindern, dass frühere Annahmen spätere Arbeit verschmutzen, und halten Diffs überprüfbar.

Beschränkungen aus dem Spec-Stack anwenden

Der implementierende Agent sollte die Anforderungsspezifikation, den Designplan, die aktuelle Aufgabbeschreibung und projektweite Beschränkungen lesen. Beschränkungen sind der Abschnitt mit dem höchsten ROI, den die meisten Teams überspringen. Sie sagen dem Agenten, was er nicht tun soll – verwandte Module nicht refaktorisieren, öffentliche API-Signaturen außerhalb dieser Funktion nicht ändern, keine neuen Abhängigkeiten einführen, ohne den Plan zu aktualisieren.

Den Plan aktualisieren, wenn die Realität abweicht

Die Implementierung wird Überraschungen aufdecken. Eine Bibliothek unterstützt das angenommene Verhalten nicht. Eine Migration dauert länger als erwartet. Ein Edge Case fehlte in den Akzeptanzkriterien. Wenn das passiert, aktualisieren Sie die Spezifikation, bevor Sie fortfahren. Korrigieren Sie die Anforderungen oder den Plan, lassen Sie ihn kurz überprüfen und setzen Sie die Implementierung dann gegen das korrigierte Artefakt fort. Code, der sich stillschweigend von der Spezifikation entfernt, ist der Weg, wie Abweichung permanent wird.

Phase 5 – Gegen die Spezifikation validieren

Die Validierung ist der Punkt, an dem SDD sich bezahlt macht. Ohne sie ist die Spezifikation eine Planungsübung. Mit ihr ist die Spezifikation ein Vertrag, gegen den Sie den ausgelieferten Code prüfen können.

Automatisierte Prüfungen

Führen Sie die vollständige Testsuite, Linting und Typprüfungen in der CI aus. Verdrahten Sie diese in Ihre Pipeline, indem Sie Muster aus dem GitHub Actions Cheat Sheet verwenden, wenn Sie einen praktischen Startpunkt benötigen. Automatisierte Prüfungen fangen Regressionen. Sie fangen keine falsch gebauten, aber korrekt implementierten Funktionen, weshalb die Überprüfung der Akzeptanzkriterien nach wie vor wichtig ist.

Akzeptanzkriterien und manuelle Überprüfung

Gehen Sie jedes Akzeptanzkriterium aus der Anforderungsspezifikation durch. Markieren Sie jedes als erfüllt, fehlgeschlagen oder aufgeschoben mit Begründung. Die manuelle Überprüfung fängt UX-Probleme, Sicherheitslücken und falsches Verhalten, das Tests übersehen haben, weil die Tests geschrieben wurden, um einer fehlerhaften Spezifikation zu entsprechen.

Spec-zu-Code-Diff

Der letzte Validierungsschritt vergleicht die Implementierung mit dem Designplan. Entsprachen die geänderten Dateien den Dateien, die der Plan vorhergesagt hat? Entsprachen die architektonischen Entscheidungen im Code den dokumentierten Entscheidungen? Unerwartete Dateien im Diff sind ein Signal – entweder war der Plan unvollständig oder der Agent ist abgewichen. Beide verdienen Aufmerksamkeit vor dem Merge. Specs, Tests und Code in Einklang halten in der KI-Entwicklung verwandelt diese einmalige Diff-Überprüfung in eine wiederholbare Nachverfolgungstabelle und eine Reihe von CI-Prüfungen, sodass Abweichungen bei jedem PR erkannt werden und nicht nur, wenn jemand daran denkt hinzuschauen.

Wo KI-Agenten im Workflow passen

KI-Agenten sind Beschleuniger in jeder Phase, keine Ersatz für die Überprüfung. Das produktive Muster ist: Entwurf, Überprüfung, Verfeinerung, dann weiter. Bitten Sie einen Agenten, die Anforderungsspezifikation aus einer Problembeschreibung zu entwerfen, und bearbeiten Sie die Absicht, bis Ziele, Nicht-Ziele und Akzeptanzkriterien stimmen. Bitten Sie einen Agenten, den Designplan aus den genehmigten Anforderungen zu entwerfen, und überprüfen Sie die architektonischen Entscheidungen, bevor Code existiert. Bitten Sie einen Agenten, eine Aufgabe nach der anderen zu implementieren, wobei Sie jedes Diff genehmigen, bevor die nächste Aufgabe beginnt.

Agenten sind besonders nützlich bei der Erstellung von ersten Entwürfen und Boilerplate-Tests. Menschen sind besonders nützlich beim Fangen von falschen Zielen, unsicherer Architektur und subtiler Scope Creep. Der Workflow scheitert, wenn eine Seite übersprungen wird – wenn Agenten ohne Spezifikationen implementieren oder wenn Menschen Spezifikationen schreiben, ohne sie jemals gegen Code zu validieren.

Dieser Workflow-Artikel bleibt absichtlich tool-unabhängig. Tool-spezifische Ausführungsguides – Editor-Setup, Slash-Befehle, Agenten-Konfiguration – gehören in den Cluster KI-Entwicklungswerkzeuge. Der Prozess-Pfeiler lebt hier unter Dokumentationspraktiken, weil die Artefakte wichtiger sind als der Anbieter.

Häufige Fehler, die die Spec-Driven Development töten

Riesige Spezifikationen vor jeder Validierung. Ein dreißigseitiges Anforderungsdokument, das vor einem Prototyp oder Spike geschrieben wird, ist Wasserfall-Bürokratie, nicht SDD. Schreiben Sie die minimale Spezifikation, die die Mehrdeutigkeit für die nächste Phase entfernt, und validieren Sie Annahmen früh. Nicht jede Funktion benötigt den vollen Fünf-Phasen-Loop – Spec-Driven Development vs Vibe Coding erklärt, wann eine leichtere Struktur ausreicht.

Vage Akzeptanzkriterien. Adjektive wie „schnell“, „sauber“ und „nutzerfreundlich“ sind keine Akzeptanzkriterien. Ersetzen Sie sie durch messbares Verhalten. Wenn Sie es nicht testen können, können Sie es nicht zuverlässig implementieren – besonders mit einem KI-Agenten.

Fehlende Nicht-Ziele. Ohne Nicht-Ziele erweitern Agenten den Umfang standardmäßig. Sie fügen Caching-Schichten hinzu, refaktorisierten benachbarte Module und führen Abhängigkeiten ein, um die Sie nicht gebeten haben. Nicht-Ziele sind der Weg, im Voraus „Nein“ zu sagen.

Kein Testplan in der Designphase. Tests, die nur nach der Implementierung geschrieben werden, neigen dazu, das Gebaute zu bestätigen, nicht das Beabsichtigte. Der Plan sollte benennen, welche Akzeptanzkriterien auf welche Testtypen abgebildet werden, bevor die erste Produktionsdatei geändert wird.

Überprüfung an Phasengrenzen überspringen. Die Spezifikation wird vor dem Plan überprüft. Der Plan wird vor den Aufgaben überprüft. Aufgaben werden vor der Implementierung überprüft. Jedes Tor ist billig. Abweichungen nach einem großen Merge zu beheben ist teuer.

Generierte Aufgaben explodieren lassen. Behandeln Sie eine KI-generierte Aufgabenliste mit fünfzig Einträgen als ersten Entwurf, nicht als Zeitplan. Führen Sie redundante Einträge zusammen, teilen Sie überdimensionierte und löschen Sie Aufgaben, die nicht auf eine Anforderung abbildbar sind.

SDD funktioniert, wenn jede Phase die Mehrdeutigkeit reduziert. Es scheitert, wenn es Bürokratie erzeugt.

Wiederverwendbare Vorlagen

Kopieren Sie diese in Ihr Repository und passen Sie sie an. Speichern Sie Spezifikationen neben dem Feature-Branch, überprüfen Sie sie in Pull Requests und halten Sie sie in der Versionskontrolle, damit Agenten und Menschen dieselbe Quelle lesen.

Anforderungsvorlage

# Feature -- [name]

## Problem
## Nutzer
## Ziele
## Nicht-Ziele
## Akzeptanzkriterien
## Offene Fragen

Designvorlage

# Design -- [feature name]

## Zusammenfassung
## Betroffene Module
## Datenmodell-Änderungen
## API-Verträge
## Migrationen
## Sicherheit
## Observability
## Teststrategie
## Risiken und Gegenmaßnahmen

Aufgabenlisten-Vorlage

# Tasks -- [feature name]

## Task 1 -- [title]
Depends on:
Files:
Satisfies:
Validate:
Review checkpoint:

## Task 2 -- [title]
...

Validierungs-Checkliste

# Validation -- [feature name]

## Automatisiert
- [ ] Alle Tests bestehen
- [ ] Linting sauber
- [ ] Typprüfung sauber

## Akzeptanzkriterien
- [ ] AC-1 --
- [ ] AC-2 --

## Spec-zu-Code
- [ ] Geänderte Dateien entsprechen dem Plan
- [ ] Keine undokumentierten architektonischen Änderungen
- [ ] Spezifikation aktualisiert, wenn sich die Implementierung unterschied

Fazit

Spec-Driven Development geht nicht darum, mehr Dokumente zu schreiben. Es geht darum, durch Spezifizieren, Planen, Aufgabenstellung, Implementierung und Validierung zu gehen, mit einem Überprüfungstor an jedem Schritt. Jede Phase sollte dem nächsten Akteur – Mensch oder Agent – weniger Vermutungen hinterlassen als die Phase zuvor.

Beginnen Sie klein. Führen Sie den vollen Workflow für eine mittelgroße Funktion durch. Halten Sie Artefakte in Markdown im Repository. Aktualisieren Sie die Spezifikation, wenn die Realität abweicht. Validieren Sie vor dem Merge. Wenn die Kette funktioniert, erhalten Sie weniger Abweichung, kleinere überprüfbare Diffs und eine dauerhafte Aufzeichnung der Absicht, die Sitzungs-Resets und Team-Übergaben übersteht.

Wenn die Kette zu Bürokratie wird, schneiden Sie den Umfang – nicht die Überprüfung. Eine zweiseitige Spezifikation, die validiert wurde, schlägt eine dreißigseitige Spezifikation, die niemand gelesen hat.

Nützliche Links

• GitHub Spec Kit Dokumentation – Open-Source-Toolkit, das einen ähnlichen Specify-Plan-Tasks-Implement-Loop implementiert
• Superpowers Quickstart: Install, Workflow, and Tryout – ein installierbares Skills-Paket, das diesen gleichen Fünf-Phasen-Loop mit obligatorischen Überprüfungstoren automatisiert
• Martin Fowler über Spec-Driven Development Tools – Analyse von Kiro, Spec Kit und Tessl