Spec-driven Development: KI belebt die Spec neu

Warum die Spec wieder auf den Tisch kommt

Ein Code-Assistent ist ein Eingabefeld und nicht viel mehr. Keine Menüs, keine vorgegebene Struktur. Wie stellt man sicher, dass der produzierte Code dem Bedarf entspricht? Die Antwort, die sich seit 2025 durchgesetzt hat: eine Spec schreiben, bevor man den Agenten coden lässt.

Diese Bewegung hat einen Namen: Spec-driven Development (SDD). Birgitta Böckeler, Distinguished Engineer bei Thoughtworks, gibt eine operative Definition: eine Spec schreiben, bevor man Code mit KI schreibt, wobei die Spec zur Quelle der Wahrheit für Mensch und Agent wird (martinfowler.com).

GitHub, AWS mit Kiro, Tessl oder auch die BMad-Methode bieten alle Werkzeuge dafür an. Das Prinzip ist einfach: ein initialer Prompt, einige Anweisungen, und das LLM generiert Produkt-Specs, einen Implementierungsplan und eine Aufgabenliste. Jedes Dokument hängt vom vorherigen ab. Der Mensch bearbeitet, der Agent codet.

Drei SDD-Ebenen, die nicht zu verwechseln sind

Nicht alle Werkzeuge, die sich auf SDD berufen, verfolgen dasselbe Ziel. Böckeler unterscheidet drei Ebenen (martinfowler.com):

• Spec-first: Eine sorgfältige Spec wird vor der Aufgabe geschrieben und dann im KI-gestützten Entwicklungsfluss verwendet.
• Spec-anchored: Die Spec wird nach der Aufgabe aufbewahrt, um die Funktionalität weiterzuentwickeln und zu warten.
• Spec-as-source: Die Spec ist die Hauptdatei über die Zeit; der Mensch berührt den Code nie.

Alle Werkzeuge sind mindestens spec-first. Wenige übernehmen spec-anchored, noch weniger spec-as-source. Das ist ein Punkt, der vor der Einführung eines Werkzeugs zu prüfen ist: Was wird aus der Spec in sechs Monaten, wenn sich der Code bewegt hat?

Eine weitere nützliche Unterscheidung: Die Spec ist nicht die Memory Bank. Die Memory Bank sind die Kontextdateien, die für alle Sitzungen gelten (Regeln, Produktbeschreibung, Architektur). Die Spec hingegen betrifft nur die Funktionalität, die gerade erstellt oder geändert wird.

Die Falle: Markdown, das die Agilität begräbt

François Zaninotto von Marmelab hat SDD getestet, und sein Urteil ist scharf: « Spec-Driven Development (SDD) revives the old idea of heavy documentation before coding — an echo of the Waterfall era » (marmelab.com).

Sein Beispiel ist bezeichnend. Mit GitHub spec-kit hat eine einfache Funktionalität — das Anzeigen des heutigen Datums in einer Zeiterfassungs-App — 8 Dateien und 1.300 Zeilen Text produziert. Mit Kiro hat das Hinzufügen eines Feldes « referred by » zu Kontakten drei Dokumente generiert: Requirements, Design, Tasks.

Die Probleme, die er auflistet:

• Context blindness: Der Agent entdeckt den Kontext durch Textsuche und verpasst existierende Funktionen, die aktualisiert werden müssten.
• Markdown madness: zu viel Text, besonders in der Designphase; man liest, statt zu denken.
• Systematische Bürokratie: Wiederholungen, imaginäre Randfälle, unnötige Verfeinerungen.
• Falsche Agilität: Die generierten « User Stories » sind keine. « As a system administrator, I want the referred by relationship to be stored in the database » ist keine User Story.
• Doppeltes Code-Review: Die technische Spec enthält bereits Code, der vor der Überprüfung der finalen Implementierung gelesen werden muss.
• Abnehmende Erträge: SDD glänzt bei einem neuen Projekt, springt aber ab, sobald die Codebasis wächst.

Zaninotto fasst zusammen: « spending 80% of your time reading instead of thinking ». SDD in seiner schweren Version wiederholt den Fehler des Big Design Up Front.

Wie eine Spec aussieht, die standhält

Eine nützliche Spec ist kein 40-seitiges Dokument. Sie ist ein strukturiertes, verhaltensorientiertes Artefakt, in natürlicher Sprache geschrieben, das eine Funktionalität ausdrückt und den Agenten führt (martinfowler.com). Drei Elemente genügen.

Der Verhaltensvertrag

Was das Modul, die Funktion oder der Endpoint tun soll. Vorbedingungen, Nachbedingungen, Invarianten. Eingabe-, Ausgabe- und Fehlertypen. Keine Mehrdeutigkeit.

Der Katalog der Randfälle

Was passiert, wenn die Eingabe null ist? Leer? Von maximaler Größe? Negativ? Unicode? Nebenläufig? Die VSDD-Methode schlägt vor, diese Fragen dem Agenten explizit zu stellen, damit er erschöpfend ist (gist.github.com).

Die Akzeptanzkriterien

Im Format GIVEN… WHEN… THEN…. Das ist es, was Kiro in seinem Requirements-Dokument produziert, wobei jede Anforderung eine User Story mit ihren Kriterien ist (martinfowler.com). Diese Kriterien dienen zweimal: dem Agenten zum Generieren des Codes, dem Team zur Überprüfung, dass der Code das tut, was verlangt wurde.

Der entscheidende Punkt: Die Spec muss überprüfbar sein. Wenn Sie keinen Test oder kein Akzeptanzkriterium schreiben können, das sie validiert, ist sie zu vage.

Spec, User Stories und Backlog verknüpfen

Eine Spec, die in einer isolierten Datei lebt, nützt nichts. Sie muss im Backlog verankert sein, am selben Ort wie die User Stories und ihre Akzeptanzkriterien.

Das Framework AI SDLC Scaffold schlägt eine Ordnerstruktur vor, die diese Verknüpfung materialisiert: einen Ordner 1-spec/ mit Unterordnern goals/, user-stories/, requirements/, assumptions/, constraints/, jeweils mit ihrem Template (github.com). Jedes Artefakt hat eine Kennung (US-, REQ-, ASM-, CON-) und lebt im Repository, versioniert mit dem Code.

Konkret, in einem agilen Projektmanagement-Werkzeug:

1. Eine User Story im Backlog mit ihrer Priorität und ihren Punkten.
2. Ihre Akzeptanzkriterien im GIVEN/WHEN/THEN-Format, in der Beschreibung oder als Checkliste.
3. Die kurze Spec, der Story zugeordnet: Vertrag, Randfälle, nicht-funktionale Anforderungen.
4. Der Link zum generierten Code, um die Rückverfolgbarkeit zu wahren.

Diese Arbeitsweise integriert sich natürlich in ein Kanban-Board mit anpassbaren Spalten, Checklisten und Aktivitätsprotokoll. Zum Beispiel kann in Ever Earlier eine User Story ihre Akzeptanzkriterien als Checkliste und ihre Spec als Anhang oder angepinnter Kommentar tragen, was vermeidet, einen separaten Markdown-Ordner zu pflegen, der sich vom Backlog entkoppelt.

Das Wichtige ist nicht das Werkzeug. Es ist, dass die Spec lebendig bleibt: aktualisiert, wenn sich die Story weiterentwickelt, archiviert, wenn sie geliefert ist, nie in einer Ecke verrotten gelassen.

Eine Methode in fünf Schritten

Hier eine konkrete Methode für kurze Specs, die korrekten Code generieren.

1. Von der Absicht ausgehen, nicht vom Code. Beschreiben Sie die Funktionalität in drei Sätzen. Wenn Sie das nicht können, ist der Bedarf nicht klar.
2. Die User Story und ihre Akzeptanzkriterien schreiben. Format « Als… möchte ich… damit… » für die Story, GIVEN/WHEN/THEN für die Kriterien. Drei bis fünf Kriterien maximal.
3. Den Verhaltensvertrag und die Randfälle hinzufügen. Eine halbe Seite genügt. Listen Sie explizit die degenerierten Eingaben auf.
4. Den Code vom Agenten generieren lassen, dann gegenlesen. Die Spec führt, sie garantiert nichts. Böckeler zitiert GitHub: « Crucially, your role isn't just to steer. It's to verify. » (martinfowler.com)
5. Die Spec nach der Lieferung aktualisieren. Wenn der Code abgewichen ist, muss die Spec das widerspiegeln. Sonst wird sie zu einer dokumentierten Lüge.

Ein Wachsamkeitspunkt: Agenten befolgen nicht immer die Spec. Zaninotto erzählt, dass ein Agent die Aufgabe « verify implementation » als erledigt markierte, ohne einen einzigen Unit-Test zu schreiben, und stattdessen Anweisungen für manuelle Tests verfasste (marmelab.com). Die menschliche Überprüfung bleibt nicht verhandelbar.

Was SDD nicht löst

SDD ist kein Zauberstab. Drei Grenzen sind im Kopf zu behalten.

Die Qualität der Trainingsdaten. Eine Studie der Penn State und Oregon State University, veröffentlicht in Media Psychology, zeigt, dass die meisten Nutzer eine systematische Verzerrung in den Trainingsdaten eines KI-Systems nicht erkennen, selbst wenn sie sichtbar ist (psu.edu). Von 769 Teilnehmern in drei Experimenten bemerkte die Mehrheit nicht, dass die glücklichen Gesichter überwiegend weiß und die traurigen Gesichter überwiegend schwarz waren. Mit anderen Worten: Eine gut geschriebene Spec schützt nicht vor einem voreingenommenen Modell.

Der bestehende Kontext. SDD glänzt bei einem neuen Projekt. Auf einer ausgereiften Codebasis verfehlen die Specs den Kontext und verlangsamen die Entwicklung. Zaninotto sagt es ohne Umschweife: « For large existing codebases, SDD is mostly unusable. »

Die Wartung der Spec. Wer aktualisiert die Spec, wenn sich der Code weiterentwickelt? Wenn die Antwort « niemand » lautet, wird SDD zu einer toten Dokumentationsschicht. Böckeler merkt an, dass die Wartungsstrategie von den Werkzeugen oft vage gelassen wird (martinfowler.com).

Die vernünftige Schlussfolgerung: das Beste aus SDD behalten — die Spec als überprüfbarer Vertrag — ohne die dokumentarische Schwere zu übernehmen. Kurze Specs, im Backlog verankert, verknüpft mit User Stories und ihren Akzeptanzkriterien. Der Rest ist Markdown, das niemandem dient.