Spec-getriebener Entwicklungsworkflow: Von den Anforderungen zum Code

Spec-Driven Development funktioniert, wenn die Spezifikation ein Arbeitsablauf ist und nicht nur ein Dokument, das nach dem Start archiviert wird. Das Ziel ist nicht die Erstellung eines umfangreichen Produktanforderungsdokuments.

Das Ziel ist es, eine Sequenz überprüfbarer Artefakte durchlaufen zu lassen, von denen jedes die Ambiguität reduziert, bevor jemand – ob Mensch oder KI-Agent – den Produktionscode ändert.

Wenn Sie konzeptionell nicht wissen, was SDD (Spec-Driven Development) ist, beginnen Sie mit Was ist Spec-Driven Development?, um Definitionen, Vergleiche mit TDD und BDD sowie die Argumentation für die Behandlung der Spezifikation als Single Source of Truth zu erhalten. Dieser Artikel im App-Architektur-Dokumentationscluster ist der operative Leitfaden. Er führt durch die fünf Phasen, zeigt, welche Inhalte jedes Artefakt enthalten sollte, erklärt, wo KI-Agenten zum Einsatz kommen, und bietet wiederverwendbare Vorlagen, die Sie sofort in Ihr Repository kopieren können.

SDD ist ein Arbeitsablauf, kein Dokument

Der häufigste Fehler bei der Spec-Driven Development 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 dokumentarischer Schein, und es ist schlimmer als keine Spezifikation, da es falsches Vertrauen schafft.

Ein funktionierender SDD-Arbeitsablauf erzeugt eine Kette von Artefakten, von denen jedes vor Beginn der nächsten Phase überprüft wird. 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 erst nachdem dreitausend Zeilen Abweichung in den Hauptzweig gelangt sind.

Der Arbeitsablauf ist tool-neutral. Sie können ihn mit Markdown-Dateien in Git durchführen, mit GitHub Spec Kit, mit Cursor-Plänen oder mit einem einfachen Texteditor und einem disziplinierten Rezensenten. Entscheidend ist die Sequenz und die Überprüfungspunkte, nicht die Marke der Tools.

Phase 1 – Anforderungen spezifizieren

Die Spezifizierungsphase beantwortet die Frage, welches Problem gelöst wird und wie „fertig“ aussieht. Sie vermeidet bewusst die Frage, wie es gebaut werden soll. In dem Moment, in dem Ihre Anforderungsspezifikation sagt „verwende Redis-Sorted-Sets“, haben Sie aufgehört zu spezifizieren und mit dem Designen im falschen Dokument begonnen. Halten Sie Implementierungsdetails aus den Anforderungen heraus. Legen 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 Rezensenten, der nicht am Planungstreffen teilgenommen hat, zu entscheiden, ob eine vorgeschlagene Lösung tatsächlich den Schmerz adressiert.

Beispiel für eine API-Ratenbegrenzungs-Funktion:

API-Konsumenten in der Free-Tier-Ebene können unbegrenzte Anfragen senden, was zu Kostensteigerungen und „noisy-neighbor“-Auswirkungen auf bezahlte Mandanten 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 verführerische angrenzende Arbeiten, die Sie explizit nicht ausführen werden. Gemeinsam begrenzen sie die Kreativität des Agenten, was essenziell ist, da KI-Tools sonst „helferlich“ den Umfang erweitern.

Akzeptanzkriterien sollten präzise genug sein, sodass jedes auf mindestens einen Test abgebildet werden kann. „Der Endpunkt ist sicher“ ist kein Akzeptanzkriterium. „Nicht authentifizierte Anfragen erhalten HTTP 401“ ist es. 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 Scheiterns. Sie sind das Zeichen dafür, dass die Spezifizierungsphase ihre Arbeit tut. Klären Sie sie, bevor Sie den Designplan schreiben, oder Sie werden die Ambiguität in Form von Implementierungs-Neuarbeit bezahlen.

Eine minimale Anforderungsvorlage:

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

## 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 die 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 aus der Anforderungsspezifikation plus 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. Agenten halluzinieren APIs, wenn Verträge implizit sind. Ihr explizites Festhalten im Plan 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-Schemata und Liefersemantik. Schließen Sie Migrationsschritte und Hinweise zum Rollback 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, Grenzen der Eingabevalidierung 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 verbindet sich mit den Akzeptanzkriterien. Identifizieren Sie, welche Kriterien Unit-Tests benötigen, welche Integrationstests und welche manuelle Verifizierung. Wenn Sie Unit-Testing in Go oder Unit-Testing in Python verwenden, nennen Sie die Pakete und Testdateien, die Sie hinzuzufügen erwarten. Ein Plan ohne Teststrategie ist ein Plan, der mit Lücken ausgeliefert wird, die Sie in der Produktion entdecken.

Phase 3 – Implementierungsaufgaben aufschlüsseln

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. Anstelle eines riesigen Diffs erhalten Sie eine Sequenz fokussierter Änderungen, von denen jede auf eine benannte Anforderung zurückverfolgt werden kann.

Aufgabengröße und Abhängigkeiten

Eine gute Aufgabe betrifft eine begrenzte Menge von Dateien, wird in einer Agent-Session abgeschlossen und endet mit einem Verifikationsschritt. Aufgaben sollten Abhängigkeiten explizit deklarieren. Migrationstasks laufen vor Code, der das neue Schema liest. Änderungen an gemeinsam genutzten Bibliotheken laufen vor den 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 des Abschlusses auflisten. Validierung kann ein Testbefehl, ein Curl-Beispiel oder ein manueller Check sein, der in kopierbaren Schritten beschrieben ist. Jede Aufgabe endet an einem menschlichen Überprüfungspunkt. Der Rezensent bestätigt, dass der Diff der Aufgabenbeschreibung entspricht, bevor die nächste Aufgabe beginnt.

Ein minimaler 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
**Überprüfungspunkt:** Bestätigen, dass Middleware nach Auth, aber vor Handler läuft

Achten Sie auf generierte Aufgabenexplosionen. KI-Agenten können in Sekunden Pläne mit fünfzig Aufgaben erzeugen. 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 Elemente, nicht fünfzig.

Phase 4 – Eine Aufgabe nach der anderen implementieren

Die Implementierung ist bewusst eng gefasst. 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 erfolgreich ist. Kontext-Resets zwischen Aufgaben sind ein Feature, kein Bug. Sie verhindern, dass frühere Annahmen spätere Arbeiten verschmutzen, und halten Diffs überprüfbar.

Beschränkungen aus dem Spezifikationsstapel anwenden

Der implementierende Agent sollte die Anforderungsspezifikation, den Designplan, die aktuelle Aufgabenbeschreibung und projektweite Beschränkungen lesen. Beschränkungen sind der Abschnitt mit der höchsten Rendite, den die meisten Teams überspringen. Sie sagen dem Agenten, was er nicht tun soll – keine Refaktorisierung unverwandter Module, keine Änderung öffentlicher API-Signaturen außerhalb dieser Funktion, keine Einführung neuer Abhängigkeiten ohne Aktualisierung des Plans.

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 Randfall fehlte in den Akzeptanzkriterien. Wenn das passiert, aktualisieren Sie die Spezifikation, bevor Sie fortfahren. Beheben Sie die Anforderungen oder den Plan, lassen Sie eine schnelle Überprüfung durchführen 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 Planungsübung. Mit ihr ist die Spezifikation ein Vertrag, den Sie gegen den ausgelieferten Code überprüfen können.

Automatisierte Prüfungen

Führen Sie die vollständige Testsuite, Linting und Typchecks in der CI (Continuous Integration) aus. Binden Sie diese in Ihre Pipeline ein, indem Sie Muster aus der GitHub Actions Cheatsheet verwenden, wenn Sie einen praktischen Startpunkt benötigen. Automatisierte Checks fangen Regressionen ein. Sie fangen nicht falsch gebaute, aber korrekt implementierte Features ein – daher bleibt die Überprüfung der Akzeptanzkriterien wichtig.

Akzeptanzkriterien und manuelle Überprüfung

Gehen Sie jedes Akzeptanzkriterium aus der Anforderungsspezifikation durch. Markieren Sie jedes als erfüllt, gescheitert oder aufgeschoben mit Begründung. Manuelle Überprüfung fängt UX-Probleme, Sicherheitslücken und falsches Verhalten ein, das Tests verpasst haben, weil die Tests so geschrieben wurden, dass sie einer fehlerhaften Spezifikation entsprechen.

Spezifikations-zu-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 abgewichen. Beides verdient Aufmerksamkeit vor dem Merge. Spezifikationen, Tests und Code in der KI-Entwicklung synchron halten verwandelt diese einmalige Diff-Überprüfung in eine wiederholbare Nachverfolgungstabelle und eine Reihe von CI-Checks, sodass Abweichungen bei jedem PR erkannt werden, nicht nur wenn jemand daran denkt, nachzusehen.

Wo KI-Agenten im Arbeitsablauf zum Einsatz kommen

KI-Agenten sind Beschleuniger in jeder Phase, keine Ersatz für die Überprüfung. Das produktive Muster ist Entwurf, Überprüfung, Verfeinerung und dann Fortsetzung. 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 Architektur-Entscheidungen, bevor überhaupt Code existiert. Bitten Sie einen Agenten, eine Aufgabenscheibe 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 bei der Erkennung falscher Ziele, unsicherer Architektur und subtiler Umfangswachstums. Der Arbeitsablauf scheitert, wenn eine Seite übersprungen wird – wenn Agenten ohne Spezifikationen implementieren oder wenn Menschen Spezifikationen schreiben, ohne sie jemals gegen den Code zu validieren.

Dieser Arbeitsablauf-Artikel bleibt absichtlich tool-neutral. Tool-spezifische Ausführungsleitfäden – Editor-Einrichtung, Slash-Befehle, Agentenkonfiguration – gehören unter den Cluster KI-Entwickler-Tools. Die Prozess-Säule lebt hier unter Dokumentationspraktiken, weil die Artefakte wichtiger sind als der Anbieter.

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

Riesige Spezifikationen vor jeglicher Validierung. Ein dreißigseitiges Anforderungsdokument, das vor einem Prototyp oder Spike geschrieben wird, ist Wasserfall-Bürokratie, kein 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 Strukturen ausreichen.

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 nicht 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 die Art, 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.

Überspringen der Überprüfung an Phasengrenzen. Die Spezifikation wird vor dem Plan überprüft. Der Plan vor den Aufgaben. Aufgaben vor der Implementierung. Jede Grenze ist günstig. Das Beheben von Abweichungen nach einem großen Merge ist teuer.

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

SDD funktioniert, wenn jede Phase die Ambiguität reduziert. Es scheitert, wenn es Bürokratie schafft.

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 unter Versionskontrolle, sodass 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:
Überprüfungspunkt:

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

Validierungscheckliste

# Validierung -- [Feature-Name]

## Automatisiert
- [ ] Alle Tests erfolgreich
- [ ] Lint sauber
- [ ] Typcheck sauber

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

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

Fazit

Spec-Driven Development geht nicht darum, mehr Dokumente zu schreiben. Es geht darum, die Phasen Spezifizieren, Planen, Aufgaben, Implementieren und Validieren mit einem Überprüfungspunkt an jedem Schritt durchlaufen zu lassen. Jede Phase sollte den nächsten Akteur – ob Mensch oder Agent – mit weniger Raterei zurücklassen als die Phase zuvor.

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

Wenn die Kette zu Bürokratie wird, kürzen Sie den Umfang – nicht die Überprüfung. Eine zweiseitige Spezifikation, die validiert wurde, 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 zu Spec-Driven Development Tools – Analyse von Kiro, Spec Kit und Tessl