Spezifikationsgetriebene Entwicklung: Vom Anforderungsdokument zum Code

Spezifikationsgetriebene Entwicklung funktioniert, wenn die Spezifikation ein Workflow ist und kein Dokument, das man nach dem Start beiseitelegt. Es geht nicht darum, ein umfangreiches Dokument mit den Produktanforderungen zu erstellen.

Es geht darum, eine Folge von überprüfbaren Artefakten durchlaufen, von denen jedes die Unschärfe reduziert, bevor jemand – ob Mensch oder KI-Agent – den Produktionscode ändert.

Wenn Sie nicht wissen, was SDD konzeptionell ist, beginnen Sie mit Was ist spezifikationsgetriebene Entwicklung? für Definitionen, Vergleiche mit TDD und BDD sowie die Argumente dafür, die Spezifikation als Quelle der Wahrheit zu behandeln. Dieser Artikel im App-Architektur-Dokumentationscluster ist der operative Leitfaden. Er geht die fünf Phasen durch, 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 Versagensmuster in der spezifikationsgetriebenen Entwicklung ist es, die Spezifikation als bürokratischen Aufwand zu behandeln. Ein Team schreibt ein langes Anforderungsdokument, speichert es in einem Wiki und codet dann aus dem Gedächtnis und aus Chat-Threads. Die Spezifikation existiert, treibt aber nichts an. Das ist Dokumentations-Theater und ist schlimmer als gar keine Spezifikation, weil es ein falsches Sicherheitsgefühl erzeugt.

Ein funktionsfähiger SDD-Workflow erzeugt eine Kette von Artefakten, von denen jedes überprüft wird, bevor die nächste Phase beginnt. Anforderungen reduzieren die Produktunschärfe. Design reduziert die technische Unschärfe. Aufgaben reduzieren die Ausführungsunschärfe. Die Implementierung produziert Code anhand eines bekannten Ziels. Die Validierung beweist, dass die Kette gehalten hat. Wenn eine Phase einen Fehler aufdeckt, korrigieren Sie das Artefakt und startenen Sie von diesem Punkt aus neu – nicht nachdem dreitausend Zeilen Drift im Hauptzweig gelandet sind.

Der Workflow ist werkzeugneutral. Sie können ihn mit Markdown-Dateien in Git ausführen, mit GitHub Spec Kit, mit einer leichteren, change-zentrischen CLI wie OpenSpec, mit Cursor-Plänen, mit einem erzwungenen Skills-Paket wie Superpowers oder mit einem einfachen Texteditor und einem disziplinierten Reviewer. Was zählt, ist die Reihenfolge und die Review-Gates, nicht die Marke der Werkzeuge.

Phase 1 – Die Anforderungen spezifizieren

Die Spezifizierungsphase beantwortet, welches Problem Sie lösen und wie „erledigt“ aussieht. Sie vermeidet bewusst, wie es gebaut wird. Sobald Ihre Anforderungsspezifikation sagt „Redis sortierte Mengen verwenden“, haben Sie aufgehört zu spezifizieren und beginnen, im falschen Dokument zu designen. 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 am Planungstreffen teilgenommen hat, zu entscheiden, ob eine vorgeschlagene Lösung das Problem tatsächlich adressiert.

Beispiel für eine API-Rate-Limiting-Funktion:

API-Kunden im Free-Tier können unbegrenzte Anfragen senden, was zu Kostenspitzen und „Lärmender-Nachbar“-Effekten auf bezahlten Tenant-Systemen führt. Plattformbetreiber benötigen ein durchsetzbares Limit pro Schlüssel ohne manuelles Eingreifen.

Ziele, Nicht-Ziele und Akzeptanzkriterien

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

Akzeptanzkriterien sollten so präzise sein, dass jedes auf mindestens einen Test abbildbar ist. „Der Endpunkt ist sicher“ ist kein Akzeptanzkriterium. „Nicht authentizierte Anfragen erhalten HTTP 401“ ist eines. Wenn Sie kein konkretes Kriterium formulieren können, ist die Anforderung immer noch zu vage für die Implementierung.

Offene Fragen

Listen Sie jede Entscheidung auf, die noch nicht feststeht. Unklare Fragen sind kein Zeichen des Scheiterns. Sie sind die Spezifizierungsphase, die ihren Job erledigt. Lösen Sie sie, bevor Sie den Designplan schreiben, oder Sie bezahlen für die Unschärfe in Form von Umarbeit bei der Implementierung.

Eine minimale Anforderungsvorlage:

## Problem
[Ein Absatz: Wer hat Schmerzen, 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 die Planung blockiert]

Phase 2 – Das Design planen

Die Planungsphase übersetzt Absicht in technische Entscheidungen. Hier gehören Redis sortierte Mengen hin, zusammen mit Modulgrenzen, Schema-Änderungen, API-Verträgen, Migrationsstufen, Sicherheitsbeschränkungen und der Teststrategie. Der Plan leitet sich von der Anforderungsspezifikation und den vorhandenen Beschränkungen Ihres Projekts ab – Stack-Wahlen, 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 im Plan explizit zu machen, verhindert erfundene Endpunkte und falsche Antwortformate.

Datenmodell, API-Verträge und Migrationen

Dokumentieren Sie Schema-Änderungen, neue Tabellen oder Felder, Index-Anforderungen und Rückwärtskompatibilitätsregeln. Für HTTP-APIs schreiben Sie Methode, Pfad, Anfrageformat, Antwortformat und Fehlercodes. Für Events schreiben Sie Thema-Namen, Payload-Schemata und Auslieferungssemantik. Fügen Sie Migrationsstufen und Rollback-Hinweise hinzu, 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 im Produktionsbetrieb funktioniert.

Die Teststrategie verbindet sich mit den Akzeptanzkriterien. Identifizieren Sie, welche Kriterien Unit-Tests benötigen, welche Integrations-Tests und welche manuelle Überprüfung. Wenn Sie Unit-Testing in Go oder Unit-Testing in Python verwenden, nennen Sie die Pakete und Testdateien, die Sie hinzufügen werden. Ein Plan ohne Teststrategie ist ein Plan, der mit Lücken ausgeliefert wird, die Sie in der Produktion entdecken.

Phase 3 – Implementierungsaufgaben herunterbrechen

Die Aufgabenphase zerlegt den Plan in Schnitte, die klein genug sind, um unabhängig implementiert, überprüft und validiert zu werden. Das macht agenten-gestützte Entwicklung überprüfbar. Anstelle eines riesigen Diffs erhalten Sie eine Folge von fokussierten Änderungen, die jeweils auf eine benannte Anforderung zurückverwiesen werden können.

Aufgabengrößengrenzen und Abhängigkeiten

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

Dateien, Validierung und Review-Checkpoints

Jede Aufgabe sollte die wahrscheinlich geänderten Dateien auflisten, die Akzeptanzkriterien, die sie erfüllt, und wie die Fertigstellung validiert wird. Die Validierung kann ein Testbefehl, ein curl-Beispiel oder eine manuelle Überprüfung sein, die in kopier- und einfügbaren Schritten beschrieben wird. Jede Aufgabe endet an einem menschlichen Review-Checkpoint. Der Reviewer 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 erzeugen. 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 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 besteht. Kontext-Resets zwischen Aufgaben sind ein Feature, kein Bug. Sie verhindern, dass frühere Annahmen spätere Arbeit verschmutzen, und halten Diffs überprüfbar.

Beschränkungen aus dem Spek-Stack anwenden

Der implementierende Agent sollte die Anforderungsspezifikation, den Designplan, die aktuelle Aufgabbeschreibung 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 – nicht unbeteiligte Module refaktorisieren, keine öffentlichen API-Signaturen außerhalb dieser Funktion ändern, keine neuen Abhängigkeiten einführen, ohne den Plan zu aktualisieren.

Den Plan aktualisieren, wenn die Realität abweicht

Die Implementierung wird Überraschungen zutage fördern. 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 weitermachen. Korrigieren Sie die Anforderungen oder den Plan, holen Sie eine kurze Prüfung ein und setzen Sie die Implementierung dann gegen das korrigierte Artefakt fort. Code, der sich stillschweigend von der Spezifikation entfernt, ist der Weg, wie Drift dauerhaft wird.

Phase 5 – Gegen die Spezifikation validieren

Die Validierung ist der Punkt, an dem SDD seinen Wert beweist. 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.

Automatische Prüfungen

Führen Sie den vollständigen Testsatz, Linting und Typprüfungen in CI aus. Verdrahten Sie diese in Ihre Pipeline unter Verwendung von Mustern aus dem GitHub-Actions-Spickzettel, falls Sie einen praktischen Ausgangspunkt benötigen. Automatische Prüfungen fangen Regressionen. Sie fangen aber nicht falsch korrekt gebaute Funktionen, weshalb die Überprüfung der Akzeptanzkriterien immer noch wichtig ist.

Akzeptanzkriterien und manuelle Überprüfung

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

Diff von Spezifikation zu Code

Der letzte Validierungsschritt vergleicht die Implementierung mit dem Designplan. Passten die geänderten Dateien zu den Dateien, die der Plan vorhersagte? Passten die Architekturentscheidungen im Code zu den protokollierten Entscheidungen? Unerwartete Dateien im Diff sind ein Signal – entweder war der Plan unvollständig, oder der Agent ist abgedriftet. Beide verdienen Aufmerksamkeit vor dem Merge. Spezifikationen, Tests und Code synchron halten in der KI-Entwicklung wandelt diese einmalige Diff-Überprüfung in eine wiederholbare Trace-Tabelle und einen Satz von CI-Checks um, sodass Drift bei jedem PR gefangen wird, nicht nur, wenn sich jemand daran erinnert, hinzuschauen.

Wo KI-Agenten im Workflow zum Einsatz kommen

KI-Agenten sind Beschleuniger in jeder Phase, kein Ersatz für die Überprüfung. Das produktive Muster ist: Entwurf, Überprüfung, Verfeinerung, dann Fortfahren. 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 prüfen Sie die Architekturentscheidungen, 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.

Agents sind besonders nützlich bei der Erstellung von ersten Entwürfen und Boilerplate-Tests. Menschen sind besonders nützlich beim Auffangen falscher Ziele, unsicherer Architektur und subtilen Scope Creeps. Der Workflow scheitert, wenn eine Seite ausgelassen wird – wenn Agents ohne Spezifikationen implementieren, oder wenn Menschen Spezifikationen schreiben, ohne sie je gegen den Code zu validieren.

Dieser Workflow-Artikel bleibt bewusst werkzeugneutral. Werkzeug-spezifische Ausführungsguides – Editor-Setup, Slash-Befehle, Agenten-Konfiguration – gehören unter den KI-Entwickler-Tools-Cluster. Die Prozess-Säule lebt hier unter Dokumentationspraktiken, weil die Artefakte wichtiger sind als der Anbieter.

Häufige Fehler, die die spezifikationsgetriebene Entwicklung töten

Riesige Spezifikationen vor jeder 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 Unschärfe für die nächste Phase beseitigt, und validieren Sie Annahmen früh. Nicht jede Funktion benötigt den vollständigen Fünf-Phasen-Loop – Spezifikationsgetriebene Entwicklung 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 Agents den Umfang standardmäßig. Sie fügen Caching-Schichten hinzu, refaktorisierte benachbarte Module und führen Abhängigkeiten ein, um die Sie nicht gebeten haben. Nicht-Ziele sind, wie Sie im Voraus „Nein“ sagen.

Kein Testplan in der Designphase. Tests, die erst nach der Implementierung geschrieben werden, neigen dazu, zu bestätigen, was gebaut wurde, nicht was beabsichtigt war. Der Plan sollte benennen, welche Akzeptanzkriterien zu welchen Testtypen gehören, 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 Gate ist billig. Drift nach einem großen Merge zu korrigieren ist teuer.

Generierte Aufgaben explodieren lassen. Betrachten Sie eine AI-generierte Aufgabenliste mit fünfzig Einträgen als ersten Entwurf, nicht als Zeitplan. Fassen Sie redundante Einträge zusammen, teilen Sie übermäßige und löschen Sie Aufgaben, die nicht zu einer Anforderung gehören.

Abgelehnte Untersuchungen löschen statt aufzuzeichnen, warum. Wenn die Review-Phase 2 zu dem Schluss kommt, dass eine Richtung nicht gebaut werden sollte, ist der Reflex, die Spezifikation zu löschen und weiterzumachen. Das löscht die Begründung, und dieselbe Idee taucht nächstes Quartal wieder auf, von demjenigen – Mensch oder Agent – von Null untersucht, der gerade wieder darüber stolpert. Die Ablehnung mit derselben Strenge aufzuzeichnen wie eine angenommene Entscheidung, ist dagegen billig; OpenSpec Abgelehnte Vorschläge: Eine Konvention für Entscheidungsgedächtnis arbeitet einen konkreten Weg dafür durch, einschließlich der Anweisung, die einen Agenten dazu bringt, nach früheren Entscheidungen zu suchen, bevor er erneut vorschlägt.

SDD funktioniert, wenn jede Phase die Unschärfe 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 Funktionszweig, überprüfen Sie sie in Pull Requests und halten Sie sie unter Versionskontrolle, damit Agents und Menschen dieselbe Quelle lesen.

Anforderungsvorlage

# Feature -- [name]

## Problem
## Users
## Goals
## Non-goals
## Acceptance criteria
## Open questions

Designvorlage

# Design -- [feature name]

## Summary
## Affected modules
## Data model changes
## API contracts
## Migrations
## Security
## Observability
## Test strategy
## Risks and mitigations

Aufgabenlisten-Vorlage

# Tasks -- [feature name]

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

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

Validierungscheckliste

# Validation -- [feature name]

## Automated
- [ ] All tests pass
- [ ] Lint clean
- [ ] Type check clean

## Acceptance criteria
- [ ] AC-1 --
- [ ] AC-2 --

## Spec-to-code
- [ ] Changed files match plan
- [ ] No undocumented architectural changes
- [ ] Spec updated if implementation differed

Schlussfolgerung

Spezifikationsgetriebene Entwicklung geht nicht darum, mehr Dokumente zu schreiben. Es geht darum, durch Spezifizieren, Planen, Aufgaben, Implementierung und Validierung mit einem Review-Gate an jedem Schritt zu gehen. Jede Phase sollte dem nächsten Akteur – Mensch oder Agent – weniger Vermutungen hinterlassen als die Phase zuvor.

Beginnen Sie klein. Führen Sie den vollständigen Workflow für eine mittelgroße 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 Drift, kleinere überprüfbare Diffs und eine dauerhafte Aufzeichnung der Absicht, die Session-Resets und Team-Übergaben übersteht.

Wenn die Kette zur 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

• Dokumentation zu GitHub Spec Kit – Open-Source-Toolkit, das einen ähnlichen specify-plan-tasks-implement-Loop implementiert
• OpenSpec Quickstart: Install, Workflow, and Common Pitfalls – eine leichtere, change-zentrische CLI, die denselben Loop als explore-propose-apply-archive ausführt
• OpenSpec Rejected Proposals: A Decision Memory Convention – Aufzeichnen einer abgelehnten Phase-2-Entscheidung, damit sie nicht von Grund auf neu untersucht wird
• Superpowers Quickstart: Install, Workflow, and Tryout – ein installierbares Skills-Paket, das denselben Fünf-Phasen-Loop mit verpflichtenden Review-Gates automatisiert
• Martin Fowler über Spezifikationsgetriebene Entwicklungs-Tools – Analyse von Kiro, Spec Kit und Tessl