Spec-Driven Development mit KI-Agenten: Praxisleitfaden

Spec-Driven Development ist eine Arbeitsweise mit KI-Coding-Agenten, bei der eine schriftliche Spec vor jedem Code steht. Du beschreibst, was gebaut wird, warum und woran du erkennst, dass es fertig ist. Der Agent macht aus der Spec einen technischen Plan, zerlegt den Plan in kleine Tasks, setzt sie nacheinander um, und das Ergebnis wird gegen die Akzeptanzkriterien der Spec geprüft. Spec, Plan und Tasks sind Dateien in deinem Repo statt Nachrichten in einem Chat. Sie überdauern die Sitzung und lassen sich reviewen wie Code.

Dieser Leitfaden erklärt den Ablauf, vergleicht die Tools, die ihn Stand Oktober 2026 unterstützen (GitHub Spec Kit, Kiro Specs, OpenSpec und die Plan Modes in Claude Code und Codex), geht ein kleines Beispiel mit echter Spec-Datei und Prompts durch und zählt die typischen Fallen auf. Die Angaben zu den Tools wurden im Oktober 2026 mit der offiziellen Dokumentation und dem Repository jedes Projekts abgeglichen.

Warum Specs bei Agenten wichtiger sind

Ein Entwickler, der ein vages Ticket bekommt, stellt Fragen. Ein Agent, der einen vagen Prompt bekommt, rät meistens, schreibt plausiblen Code und meldet, dass er fertig ist. Die Lücke zwischen „Code wurde geschrieben“ und „das Feature funktioniert so, wie du es gemeint hast“ ist die Quelle der meisten Nacharbeit.

Eine Spec schließt diese Lücke auf drei Wegen:

• Sie erzwingt die Entscheidungen vorab. Randfälle, Fehlerzustände und Nicht-Ziele stehen schwarz auf weiß, bevor der Agent für dich entscheidet.
• Sie gibt jedem Schritt dieselbe Quelle der Wahrheit. Plan, Tasks und Review verweisen auf eine Datei statt auf deine Erinnerung an eine Unterhaltung.
• Sie macht „fertig“ prüfbar. Akzeptanzkriterien machen aus „sieht gut aus“ ein „Kriterium 3 besteht, hier ist der Test“.

Neu ist nichts davon. Anforderungsdokumente und Abnahmetests sind alte Ideen. Neu ist, dass Agenten so schnell sind, dass das Schreiben der Spec jetzt der langsame, wertvolle Teil ist und der Code der billige.

Der Ablauf: Spec, Plan, Tasks, Umsetzung, Prüfung

Zwei Regeln halten den Ablauf zusammen. Erstens: Die Spec beschreibt Verhalten, der Plan die Umsetzung. „Nutzer können ihr Passwort per E-Mail zurücksetzen“ gehört in die Spec, „eine Tabelle reset_tokens anlegen“ in den Plan. Zweitens: Halte nach jedem Schritt an und reviewe. Alle Tools unten sind um diesen Halt herum gebaut. Lässt du ihn weg, wird aus Spec-Driven Development wieder ein langer Prompt.

Tools für Spec-Driven Development

GitHub Spec Kit

Spec Kit ist das Toolkit von GitHub für Spec-Driven Development. Es hat dieses Jahr 1.0 erreicht, die neueste Version ist Stand Oktober 2026 v1.2.4. Es ersetzt deinen Agenten nicht: Die specify-CLI installiert Vorlagen und Befehle ins Projekt, und du führst die Schritte im Chat deines Agenten aus. Voraussetzungen sind Python 3.11 oder neuer, uv und ein unterstützter Agent unter macOS, Linux oder Windows.

uv tool install specify-cli
specify init my-project --integration claude
# in einem bestehenden Repo:
specify integration install claude

Die Integrationsliste umfasst mehr als 40 Agenten, darunter Claude Code (claude), Codex CLI (codex), Gemini CLI (gemini), GitHub Copilot (copilot), Cursor (cursor-agent), Kiro CLI (kiro-cli), opencode, Qwen Code und Amp. Die Doku schreibt die Befehle als /speckit.specify usw.; wie du sie tippst, hängt vom Agenten ab. In Claude Code werden sie als Skills unter .claude/skills/ installiert und als /speckit-specify aufgerufen, in Codex heißen sie $speckit-specify.

Der kurze Weg ist specify → plan → tasks → implement → converge. Für Features, die in Produktion gehen, empfiehlt die Doku den vollen Weg:

1. /speckit-constitution einmal pro Projekt, für Grundsätze wie Testregeln.
2. /speckit-specify schreibt die Feature-Spec aus einer einfachen Beschreibung.
3. /speckit-clarify stellt bis zu fünf gezielte Fragen und trägt die Antworten in die Spec ein.
4. /speckit-plan schreibt den technischen Plan anhand deines Stacks und deiner Vorgaben.
5. /speckit-checklist erzeugt „Unit-Tests für deine Anforderungen“.
6. /speckit-tasks erstellt eine nach Abhängigkeiten geordnete tasks.md.
7. /speckit-analyze ist eine reine Lese-Konsistenzprüfung über Spec, Plan und Tasks.
8. /speckit-implement arbeitet die Tasks der Reihe nach ab.
9. /speckit-converge vergleicht den Code mit der Spec und hängt Vergessenes an tasks.md an.

Implement und Converge wiederholst du, bis Converge Converged meldet. Laut Doku solltest du jeden Befehl einzeln ausführen und das Ergebnis prüfen, bevor du den nächsten startest.

Kiro Specs

Kiro baut Specs direkt ins Produkt ein. Jede Spec besteht aus drei Dateien in .kiro/specs/<name>/: requirements.md (bei Bugs bugfix.md), design.md und tasks.md. Anforderungen werden in EARS-Notation geschrieben, nach dem Muster „WHEN [Bedingung] THE SYSTEM SHALL [Verhalten]“. Feature-Specs können mit den Anforderungen oder mit dem Design beginnen, und Quick Spec erzeugt alle drei Dateien in einem Durchgang ohne die Freigabestopps dazwischen.

In der Kiro CLI startest du mit /spec new <name> und führst die Tasks mit /spec run <name> aus. Lässt du alle Tasks laufen, baut Kiro aus tasks.md einen Abhängigkeitsgraphen und führt voneinander unabhängige Tasks in parallelen Wellen aus. Stand Oktober 2026 hat Kiro einen Free-Tarif mit 50 Credits und bezahlte Tarife ab 20 $ pro Nutzer und Monat.

Kiro ist die beste Wahl, wenn du den Spec-Workflow mit eingebauter Review-Oberfläche willst und es dir nichts ausmacht, in Kiro zu arbeiten. Willst du bei Claude Code oder Codex bleiben, passen Spec Kit oder OpenSpec besser.

OpenSpec

OpenSpec ist eine leichtere, MIT-lizenzierte Alternative, die sich um Änderungen dreht. /opsx:propose add-dark-mode legt openspec/changes/add-dark-mode/ an, mit proposal.md, einem Ordner specs/ mit Anforderungen und Szenarien, design.md und tasks.md. /opsx:apply arbeitet die Tasks ab, /opsx:archive verschiebt die Änderung ins Archiv und aktualisiert die Specs. /opsx:explore ist ein Nachdenk-Schritt, bevor du dich auf einen Vorschlag festlegst.

npm install -g @fission-ai/openspec@latest   # braucht Node.js 20.19.0+
cd your-project
openspec init

Es gibt außerdem ein eigenständiges Binary und eine Homebrew-Formel. Die Schreibweise der Befehle hängt vom Agenten ab, in Codex etwa $openspec-propose; openspec init zeigt die richtige Form für die gewählten Tools an. Die neueste Version ist Stand Oktober 2026 v1.15.0.

Plan Mode in Claude Code und Codex

Plan Modes decken einen Schritt des Ablaufs ab: den Plan. Im Plan Mode von Claude Code liest der Agent Dateien, erkundet den Code und schlägt dann einen Plan vor; Änderungen bleiben gesperrt, bis du zustimmst. Du aktivierst ihn mit Shift+Tab, mit /plan vor einem Prompt oder mit claude --permission-mode plan.

Die Codex CLI hat /plan. Der Befehl schaltet den Chat in den Plan Mode und kann die erste Anfrage direkt mitnehmen, zum Beispiel /plan Propose a migration plan for this service. Dazu kommt /goal, das ein dauerhaftes Ziel für eine größere Aufgabe setzt und sich pausieren, fortsetzen oder löschen lässt.

Plan Modes eignen sich gut für Spec-Driven Development ohne zusätzliche Tools. Was fehlt, ist Beständigkeit: Bitte den Agenten, den freigegebenen Plan und die Tasks in Dateien zu schreiben, damit die nächste Sitzung davon ausgeht statt bei null.

Ein Beispiel: eine Spec-Datei und vier Prompts

So sieht die Do-it-yourself-Variante aus, die mit Claude Code, Codex oder jedem Agenten funktioniert, der Dateien liest. Das Feature: fehlgeschlagene Logins in einer kleinen Web-App begrenzen.

1. Die Spec schreiben

Speichere das als specs/login-rate-limit/spec.md:

# Login rate limiting

## Goal
Slow down password guessing on POST /login without bothering normal users.

## Non-goals
- No CAPTCHA.
- No change to how passwords are stored.

## Acceptance criteria
1. WHEN an IP has 5 failed logins within 15 minutes,
   THE SYSTEM SHALL answer further attempts with HTTP 429 for 15 minutes.
2. WHEN a login succeeds, THE SYSTEM SHALL reset that IP's failure count.
3. The 429 response SHALL include a Retry-After header in seconds.
4. Limits SHALL be configurable through LOGIN_MAX_FAILS and LOGIN_WINDOW_MIN.
5. Existing login tests SHALL still pass, and new tests SHALL cover 1–4.

## Constraints
- Use the existing Redis connection; no new services.

## Open questions
- Should the limit be per IP, per account, or both?

Halte sie auf einer Bildschirmseite. Der Abschnitt mit offenen Fragen ist Absicht: Er gibt dem Agenten Raum, vor dem Planen nachzuhaken. Du kannst die Spec auch auf Deutsch schreiben; Agenten lesen beides.

2. Klären und planen

Starte im Plan Mode und verweise den Agenten auf die Datei:

Read specs/login-rate-limit/spec.md and the auth code.
First, ask me about anything ambiguous, starting with the open questions.
Then write a plan to specs/login-rate-limit/plan.md: files to change,
data stored in Redis and its expiry, how each acceptance criterion
will be tested, and risks. Don't edit any source files.

Beantworte die Fragen und lies dann den Plan. Widersprich bei allem, was eine Vorgabe ignoriert.

3. In Tasks zerlegen

Turn plan.md into specs/login-rate-limit/tasks.md: a numbered checklist
of tasks small enough to review in one diff. For each task, list the
files it touches and the test that proves it. Order them by dependency.

4. Einen Task nach dem anderen umsetzen

Do task 1 from specs/login-rate-limit/tasks.md only. Run the tests,
tick the task in tasks.md, and stop. Tell me if the spec or plan
turned out to be wrong.

Ein Task pro Prompt hält Diffs klein und gibt dir einen natürlichen Review-Punkt. Zeigt ein Task, dass die Spec falsch war, korrigierst du zuerst die Spec und machst dann weiter.

5. Gegen die Spec prüfen

Sind alle Tasks erledigt, prüfst du das Ergebnis gegen die Spec, am besten in einer frischen Sitzung oder mit einem anderen Agenten, damit der Reviewer den Code nicht selbst geschrieben hat:

Read specs/login-rate-limit/spec.md. For each acceptance criterion,
find the code and the test that cover it, run the tests, and report
PASS or FAIL with evidence. Don't change any code.

Das ist der ganze Ablauf. Committe den Ordner specs/ zusammen mit dem Code, damit die nächste Person oder der nächste Agent sieht, warum der Code so aussieht. Mehr zum Formulieren der Prompts selbst findest du unter Prompts für KI-Coding-Agenten.

Typische Fallen

• Specs, die eigentlich Pläne sind. Nennt die Spec Tabellen und Funktionen, kann der Agent kein besseres Design vorschlagen und der Reviewer Verhalten nicht von Umsetzung trennen. Das „Wie“ gehört in plan.md.
• Zu lange Specs. Eine zehnseitige Spec frisst Kontext, und niemand liest sie, auch der Agent nicht. Eine Bildschirmseite pro Feature ist eine gute Grenze; größere Features teilst du auf.
• Freigeben ohne zu lesen. Eine ungelesene Spec oder ein ungelesener Plan ist nur ein langsamerer Prompt. Der Review-Halt ist der eigentliche Sinn.
• Zu große Tasks. Erzeugt ein Task einen Diff, den du nicht in einem Rutsch reviewen kannst, teil ihn.
• Die Spec veralten lassen. Wenn dich der Code etwas lehrt, aktualisiere die Spec. Eine Spec, die dem Code widerspricht, ist schlimmer als gar keine.
• Den Autor prüfen lassen. Der Agent, der den Code geschrieben hat, bestätigt gern seine eigene Arbeit. Nimm für die Schlussprüfung eine frische Sitzung, ein zweites Modell oder einen Menschen.
• Es für alles nutzen. Ein Einzeiler braucht keine Spec. Heb dir den Prozess für Features mit Randfällen oder mehreren Dateien auf.
• Projektregeln in jede Spec packen. Dauerhafte Regeln wie Testbefehle und Codestil gehören in CLAUDE.md oder AGENTS.md oder in eine Spec-Kit-Constitution, nicht in jede Feature-Spec.

Spec-Driven Development in AgentVera

AgentVera ist eine Desktop-App für macOS, Windows und Linux, die Claude Code, Codex, Kiro und andere Coding-CLIs nebeneinander ausführt. Jedes Panel ist die echte CLI, also funktionieren Spec-Kit-Befehle, OpenSpec-Befehle, Kiros /spec und der Plan Mode dort genauso wie allein. Einige AgentVera-Funktionen folgen demselben Muster aus Spec, Plan, Bau und Prüfung:

• Task Line: eine feste Linie aus Analyse-, Plan-, Bau- und Review-Agenten. Jeder Task bekommt Akzeptanzkriterien, die Analyse schreibt 01-analiz.md, der Plan 02-plan.md, und der Reviewer markiert jedes Kriterium mit Beleg. Ein abgelehnter Task geht mit den Befunden zurück in den Bau.
• AgentVera Verify: entnimmt die Akzeptanzkriterien der Nachricht, die du einem Agenten schickst. Endet dessen Turn, liest ein separater Prüfer den Diff, führt freigegebene Testbefehle aus und markiert jedes Kriterium als bestanden oder nicht bestanden. Der Prüfer kann keine Dateien ändern.
• Paralleles Team: Ein Agent teilt eine große Aufgabe in bis zu 8 Teile, jeder mit eigenem Prompt, Akzeptanzkriterien, erwarteten Dateien und Abhängigkeiten, lässt sie in getrennten Worktrees laufen und führt sie in einem Branch und einem PR zusammen.
• Team-Kanban: Eine Karte lässt sich einem Coding-Agenten als Aufgabe schicken, und seine Antwort kommt als Kommentar zurück. Siehe Kanban für KI-Agenten.
• Automatisches Code-Review: Wenn ein Turn endet, prüft ein Claude-Modell deiner Wahl den Code und listet Befunde mit Datei:Zeile-Links auf.

Task Line, Verify, paralleles Team und Team-Kanban gehören zu den Tarifen Pro und Team. Wenn du nur die Spec-Dateien und Befehle brauchst: Spec Kit und OpenSpec sind kostenlos und laufen in jedem Terminal. AgentVera hilft, sobald mehrere Agenten gleichzeitig an Specs arbeiten.

Fazit

Spec-Driven Development heißt: Das „Was“ und das „Woran erkenne ich es“ aufschreiben, bevor der Agent Code schreibt, und jeden weiteren Schritt an dieser Datei messen. Fang mit einer einseitigen spec.md und dem Plan Mode an. Wechsle zu Spec Kit oder OpenSpec, wenn du Vorlagen und Konsistenzprüfungen willst, oder zu Kiro, wenn der Workflow im Editor stecken soll. Egal was du wählst: Reviewe nach jedem Schritt und prüfe gegen die Kriterien, nicht gegen die Zusammenfassung des Agenten.

Weiterlesen:

• Claude Code Plan Mode
• Prompts für KI-Coding-Agenten
• Task Line

Um AgentVera auszuprobieren, lade es herunter.