Spezifikationsgetriebener Entwicklungsworkflow: Von den Anforderungen zum Code

Spec-getriebene Entwicklung funktioniert, wenn die Spezifikation ein Workflow ist und nicht ein Dokument, das nach dem Kickoff in einem Schrank verschwindet. Das Ziel ist es nicht, ein umfangreiches Produktanforderungsdokument zu erstellen.

Das Ziel ist es, eine Sequenz von überprüfbaren Artefakten zu durchlaufen, die jeweils die Ambiguität reduzieren, bevor jemand – ob Mensch oder KI-Agent – Produktionscode ändert.

Wenn Sie nicht wissen, was SDD (Spec-Driven Development) konzeptionell ist, beginnen Sie mit Was ist Spec-Driven Development? für Definitionen, Vergleiche mit TDD und BDD sowie die Begründung dafür, die Spezifikation als Single Source of Truth zu behandeln. Dieser Artikel im App-Architektur-Dokumentationscluster 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 bietet wiederverwendbare Vorlagen, die Sie heute noch in Ihr Repository kopieren können.

SDD ist ein Workflow, kein Dokument

Der häufigste Fehler bei der spec-getriebenen Entwicklung besteht darin, die Spezifikation als Bürokratie zu behandeln. Ein Team schreibt ein langes Anforderungsdokument, speichert es in einem Wiki und codiert dann aus dem Gedächtnis und basierend auf Chat-Verläufen. Die Spezifikation existiert, treibt aber nichts voran. Das ist Dokumentations-Theater und schlimmer als gar keine Spezifikation, da es falsches Vertrauen schafft.

Ein funktionierender SDD-Workflow erzeugt eine Kette von Artefakten, von denen jedes überprüft wird, bevor die nächste Phase beginnt. Anforderungen reduzieren die Produktambiguität. Das Design reduziert die technische Ambiguität. Aufgaben reduzieren die Ausführungsambiguität. Die Implementierung erzeugt Code gegen ein bekanntes Ziel. Die Validierung beweist, dass die Kette hielt. Wenn eine Phase einen Fehler aufdeckt, beheben Sie das Artefakt und starten Sie von diesem Punkt neu – nicht nachdem dreitausend Zeilen Abweichung im Hauptzweig gelandet sind.

Der Workflow ist werkeunabhängig. Sie können ihn mit Markdown-Dateien in Git durchführen, mit dem GitHub Spec Kit, mit Cursor-Plänen oder mit einem einfachen Texteditor und einem disziplinierten Reviewer. Entscheidend ist die Sequenz und die Review-Gates, nicht die Marke des Tools.

Phase 1 – Die Anforderungen spezifizieren

Die Spezifizierungsphase beantwortet die Frage, welches Problem Sie lösen und was „fertig“ bedeutet. Sie vermeidet bewusst die Frage, wie es gebaut werden soll. Der Moment, in dem Ihre Anforderungsspezifikation sagt „verwende Redis-Sortierte-Sets“, haben Sie aufgehört zu spezifizieren und mit dem Design im falschen Dokument begonnen. Halten Sie Implementierungsdetails aus den Anforderungen heraus. Geben Sie sie in den Plan.

Problemstellung und Nutzer

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

Beispiel für eine API-Ratelimiting-Funktion:

API-Konsumenten auf der kostenlosen Ebene können unbegrenzte Anfragen senden, was zu Kostenspitzen und Noisy-Neighbor-Effekten bei bezahlten Tenants führt. Plattformbetreiber benötigen ein durchsetzbares Limit pro Schlüssel ohne manuelle Intervention.

Ziele, Nicht-Ziele und Akzeptanzkriterien

Ziele beschreiben die Ergebnisse, die Sie liefern werden. Nicht-Ziele beschreiben verlockende benachbarte Arbeiten, die Sie explizit nicht ausführen werden. Zusammen begrenzen sie die Kreativität des Agents, was essenziell ist, wenn KI-Tools ansonsten „hilfreicherweise“ den Umfang erweitern.

Akzeptanzkriterien sollten präzise genug sein, dass jedes mindestens einen Test abbildet. „Der Endpunkt ist sicher“ ist kein Akzeptanzkriterium. „Unauthententifizierte Anfragen erhalten HTTP 401“ ist eines. Wenn Sie kein konkretes Kriterium schreiben können, ist die Anforderung immer noch zu vage, um implementiert zu werden.

Offene Fragen

Listen Sie jede Entscheidung auf, die noch nicht getroffen ist. Unklare Fragen sind kein Zeichen von Versagen. Sie sind das Ergebnis der Spezifizierungsphase, die ihre Arbeit tut. Beantworten Sie sie, bevor Sie den Designplan schreiben, oder Sie werden die Ambiguität in Form von Implementierungs-Neuarbeit bezahlen.

Eine minimale Anforderungsvorlage:

## Problem
[Einer 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
- [Explizit außerhalb des Umfangs]
- [Explizit außerhalb des Umfangs]

## Akzeptanzkriterien
- [ ] [Überprüfbares Verhalten]
- [ ] [Überprüfbares Verhalten]

## Offene Fragen
- [ ] [Frage, die die Planung blockiert]

Phase 2 – Das Design planen

Die Planungsphase übersetzt Absicht in technische Entscheidungen. Hier gehören Redis-Sortierte-Sets hin, zusammen mit Modulgrenzen, Schema-Änderungen, API-Verträgen, Migrationsschritten, Sicherheitsbeschränkungen und der Teststrategie. Der Plan leitet sich aus der Anforderungsspezifikation und den bestehenden Beschränkungen Ihres Projekts ab – Stack-Entscheidungen, Entscheidungsprotokolle und Konventionen, die in Dateien wie AGENTS.md oder einer Projektverfassung 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. Agents halluzinieren APIs, wenn Verträge implizit sind. Sie explizit im Plan zu machen, verhindert erfundene Endpunkte und falsche Antwortstrukturen.

Datenmodell, API-Verträge und Migrationen

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

Sicherheit, Observability und Teststrategie

Sicherheitsbeschränkungen gehören in den Plan, nicht als nachträglicher Gedanke in der 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-Testing in Go oder Unit-Testing 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 in der Produktion entdecken.

Phase 3 – Implementierungsaufgaben aufteilen

Die Aufgabenphase zerlegt den Plan in Slice, die klein genug sind, um unabhängig implementiert, überprüft und validiert zu werden. Das macht die agentenunterstützte Entwicklung überprüfbar. Anstatt eines enormen Diffs erhalten Sie eine Sequenz fokussierter Änderungen, die jeweils auf eine benannte Anforderung zurückverfolgt werden können.

Aufgaben-Größe und Abhängigkeiten

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

Dateien, Validierung und Review-Checkpoints

Jede Aufgabe sollte die wahrscheinlich zu ändernden Dateien, die erfüllten Akzeptanzkriterien und die Validierungsmethode auflisten. Validierung kann ein Testbefehl, ein Curl-Beispiel oder eine manuelle Prüfung in kopierbaren Schritten sein. Jede Aufgabe endet an einem menschlichen Review-Checkpoint. Der Reviewer bestätigt, dass der Diff der Aufgabenbeschreibung entspricht, bevor die nächste Aufgabe beginnt.

Ein minimales Eintrag für eine Aufgabe:

### Aufgabe 3 -- Rate-Limit-Middleware hinzufügen

**Abhängig von:** Aufgabe 1 (Schema), Aufgabe 2 (Repository)
**Dateien:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Erfüllt:** AC-2 (429 über Limit), AC-3 (Limit-Header in Antwort)
**Validieren:** `go test ./middleware/...` erfolgreich; Curl über Limit gibt 429 mit Retry-After zurück
**Review-Checkpoint:** Bestätigen, dass Middleware nach Auth und vor Handler läuft

Achten Sie auf explodierende generierte Aufgaben. KI-Agenten können in Sekunden Pläne mit fünfzig Aufgaben erstellen. Die meisten dieser Aufgaben werden redundant sein oder zu granular, 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 eng begrenzt. Wählen Sie eine Aufgabe, geben Sie dem Agent nur den Kontext, den er für diese Aufgabe benötigt, und stoppen Sie, wenn die Validierung erfolgreich ist. Kontext-Resets zwischen Aufgaben sind ein Feature, kein Bug. Sie verhindern, dass frühere Annahmen spätere Arbeit kontaminieren, und halten Diffs überprüfbar.

Beschränkungen aus dem Spezifikations-Stack anwenden

Der implementierende Agent sollte die Anforderungsspezifikation, den Designplan, die aktuelle Aufgabenbeschreibung und projektweite Beschränkungen lesen. Beschränkungen sind der Abschnitt mit dem höchsten ROI, den die meisten Teams überspringen. Sie sagen dem Agent, was er nicht tun soll – refaktoriere keine unverwandten Module, ändere keine öffentlichen API-Signaturen außerhalb dieser Funktion, führe keine neuen Abhängigkeiten ein, ohne den Plan zu aktualisieren.

Aktualisieren Sie den Plan, 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 Randfall fehlte in den Akzeptanzkriterien. Wenn das passiert, aktualisieren Sie die Spezifikation, bevor Sie fortfahren. Beheben Sie die Anforderungen oder den Plan, holen Sie eine schnelle Review ein und setzen Sie die Implementierung gegen das korrigierte Artefakt fort. Code, der stillschweigend von der Spezifikation abweicht, ist der Weg, wie Abweichung dauerhaft wird.

Phase 5 – Gegen die Spezifikation validieren

Validierung ist der Ort, an dem SDD seinen Wert beweist. Ohne sie ist die Spezifikation eine Planungsexerzierung. Mit ihr ist die Spezifikation ein Vertrag, den Sie gegen den ausgelieferten Code überprüfen können.

Automatisierte Checks

Führen Sie den vollständigen Testsuite, Lint- und Typ-Checks in CI aus. Verdrahten Sie diese in Ihre Pipeline unter Verwendung von Mustern aus dem GitHub Actions Cheatsheet, wenn Sie einen praktischen Ausgangspunkt benötigen. Automatisierte Checks fangen Regressionen. Sie fangen nicht falsch gebaute, aber korrekt implementierte Features, weshalb die Review der Akzeptanzkriterien weiterhin wichtig ist.

Akzeptanzkriterien und manuelle Review

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

Spec-to-Code Diff

Der letzte Validierungsschritt vergleicht die Implementierung mit dem Designplan. Entsprachen die geänderten Dateien den vom Plan vorhergesagten Dateien? 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 abgewandert. Beide verdienen Aufmerksamkeit vor dem Merge.

Wo KI-Agenten im Workflow passen

KI-Agenten sind Beschleuniger in jeder Phase, keine Ersatz für Review. Das produktive Muster ist Entwurf, Review, Verfeinerung und dann Fortsetzung. Bitten Sie einen Agent, die Anforderungsspezifikation aus einer Problembeschreibung zu entwerfen, und bearbeiten Sie die Absicht, bis Ziele, Nicht-Ziele und Akzeptanzkriterien stimmen. Bitten Sie einen Agent, den Designplan aus den genehmigten Anforderungen zu entwerfen, und überprüfen Sie Architektur-Entscheidungen, bevor Code existiert. Bitten Sie einen Agent, eine Aufgabe nach der anderen zu implementieren, wobei Sie jeden 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 falscher Ziele, unsicherer Architekturen und subtiler Umfangsschwund. 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 werkeunabhängig. Werkzeug-spezifische Ausführungsleitfäden – Editor-Einrichtung, Slash-Befehle, Agent-Konfiguration – gehören unter den Cluster AI Developer Tools. Der Prozess-Pfeiler lebt hier unter Dokumentationspraktiken, weil die Artefakte wichtiger sind als der Anbieter.

Häufige Fehler, 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 Ambiguität für die nächste Phase entfernt, und validieren Sie Annahmen früh. Nicht jede Funktion benötigt den vollständigen Fünf-Phasen-Loop – Spec-Driven Development vs Vibe Coding erklärt, wann leichtere Struktur ausreicht.

Vage Akzeptanzkriterien. Adjektive wie „schnell“, „sauber“ und „benutzerfreundlich“ 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, refaktorieren benachbarte Module und führen Abhängigkeiten ein, die Sie nicht angefordert haben. Nicht-Ziele sind der Weg, wie Sie im Voraus nein sagen.

Kein Testplan in der Designphase. Tests, die erst nach der Implementierung geschrieben werden, bestätigen tendenziell, was gebaut wurde, nicht was beabsichtigt war. Der Plan sollte benennen, welche Akzeptanzkriterien auf welche Testtypen abgebildet werden, bevor die erste Produktionsdatei geändert wird.

Review an Phasengrenzen überspringen. Die Spezifikation wurde vor dem Plan überprüft. Der Plan vor den Aufgaben. Aufgaben vor der Implementierung. Jedes Gate ist günstig. Das Beheben von Abweichungen nach einem großen Merge ist teuer.

Generierte Aufgaben explodieren lassen. Behandeln Sie eine fünfzig-Elemente-lange KI-generierte Aufgabenliste als ersten Entwurf, nicht als Zeitplan. Fügen Sie redundante Elemente zusammen, teilen Sie übergroße auf und löschen Sie Aufgaben, die nicht auf eine Anforderung abgebildet werden.

SDD funktioniert, wenn jede Phase die Ambiguität reduziert. Sie scheitert, wenn sie 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 Minderungsmaßnahmen

Aufgabenlisten-Vorlage

# Aufgaben -- [Feature-Name]

## Aufgabe 1 -- [Titel]
Abhängig von:
Dateien:
Erfüllt:
Validieren:
Review-Checkpoint:

## Aufgabe 2 -- [Titel]
...

Validierungs-Checkliste

# Validierung -- [Feature-Name]

## Automatisiert
- [ ] Alle Tests erfolgreich
- [ ] Lint sauber
- [ ] Typ-Check sauber

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

## Spec-to-Code
- [ ] Geänderte Dateien entsprechen Plan
- [ ] Keine undokumentierten Architektur-Änderungen
- [ ] Spezifikation aktualisiert, wenn Implementierung abwich

Fazit

Spec-getriebene Entwicklung geht nicht darum, mehr Dokumente zu schreiben. Es geht darum, durch Spezifizieren, Planen, Aufgaben, Implementieren und Validieren zu gehen, mit einem Review-Gate bei jedem Schritt. Jede Phase sollte den nächsten Akteur – ob Mensch oder Agent – mit weniger Ratearbeit zurücklassen als die Phase zuvor.

Beginnen Sie klein. Führen Sie den vollständigen Workflow auf einer mittelgroßen Funktion aus. 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 Absichtsaufzeichnung, die Session-Resets und Team-Übergaben überlebt.

Wenn die Kette zu Bürokratie wird, kürzen Sie den Umfang – nicht die Review. Eine validierte zweiseitige Spezifikation ist besser als eine dreißigseitige Spezifikation, die niemand gelesen hat.

Nützliche Links

• GitHub Spec Kit Dokumentation – Open-Source-Toolkit, das einen ähnlichen Spezifizieren-Planen-Aufgaben-Implementieren-Loop implementiert
• Martin Fowler über Spec-Driven Development Tools – Analyse von Kiro, Spec Kit und Tessl