Spec-Driven Development mit Claude Code

Problem: Claude Codes First-Attempt-Erfolgsrate bei kleinen bis mittelgroßen PRs ohne detaillierte Vorgaben liegt laut Anthropics eigenem RL Engineering-Team bei etwa einem Drittel. In zwei Dritteln der Fälle verfehlt es entweder Anforderungen, interpretiert den Scope zu breit oder wählt den falschen Implementierungsweg. Der Fix ist kein weiteres Prompting mitten in der Session. Er ist das Schreiben einer Spec, bevor die Session beginnt.

Die Mathematik ist brutal. Angenommen, Claude trifft bei jeder einzelnen Entscheidung zu 80 % die richtige Wahl. Ein typisches Feature umfasst 20 Entscheidungen. Wahrscheinlichkeit, alle 20 ohne Vorgaben richtig zu treffen: 0,8^20, was ungefähr 1 % ist. Eine überprüfte Spec bringt jede Entscheidung nahe an Sicherheit, weil du sie bereits getroffen hast. Die Spec führt Claude nicht. Sie entfernt die Entscheidungen, die Claude gar nicht treffen sollte.

Das Vier-Phasen-Muster

Spec-Driven Development (SDD) läuft in vier Phasen: Requirements, Design, Tasks und Execute. Die ersten drei finden in einer Session statt. Die vierte in einer neuen.

Requirements hält fest, was das Feature aus Nutzersicht leisten muss. User Stories, Akzeptanzkriterien, Edge Cases. Nicht wie. Was.

Design hält die Architektur fest: Datenmodelle, API-Contracts, welche Dateien sich ändern, welche bleiben, was die Tech-Stack-Entscheidung für dieses Feature ist.

Tasks ist der geordnete Implementierungsplan mit expliziten Abhängigkeiten. Schritt 3 kann erst starten, wenn Schritt 2 fertig ist. Diese Reihenfolge spielt eine Rolle, wenn Claude tief in einer Tool-Call-Kette steckt.

Execute läuft in einer komplett separaten Session. Das ist nicht optional.

Warum die neue Session wichtig ist

Claude hängt innerhalb derselben Session an seinem eigenen Plan. Es hat bereits über Requirements und Design nachgedacht, also trägt es diese Annahmen implizit weiter, anstatt die Spec so zu lesen, wie sie geschrieben steht. Eine neue Session zwingt Claude, die Spec so zu lesen, wie es ein neuer Entwickler täte: von oben, wörtlich.

Der Community-Konsens dazu ist einhellig. Pimzino, dessen claude-code-spec-workflow-Paket (3.700+ Sterne, 258 Forks) diesen Ansatz nach dem Studium von Amazon Kiros spec-getriebenem IDE formalisierte, bezeichnet die geteilte Session als nicht verhandelbar. Die Spec-Session nutzt Claude Opus für tiefes Nachdenken über Requirements. Die Implementierungs-Session nutzt Claude Sonnet für die Ausführung eines klaren Plans. Verschiedene Jobs, verschiedene Modelle, verschiedene Sessions.

Der von Anthropic empfohlene Interview-Workflow

Anthropics offizielle Dokumentation beschreibt den schnellsten Weg zu einer guten Spec: Interview-Modus. Starte eine neue Session und führe Folgendes aus:

I want to build [brief description]. Interview me in detail using 
the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, 
and tradeoffs. Don't ask obvious questions, dig into the hard parts 
I might not have considered.

Keep interviewing until we've covered everything, then write a 
complete spec to SPEC.md.

Claude stellt Fragen, bis Implementierung, UX, Edge Cases und Trade-offs abgedeckt sind. Wenn es zufrieden ist, schreibt es die Spec in SPEC.md. Dann schließt du die Session. Die nächste Session öffnet die Spec und baut.

Dieser Übergabe ist der Ort, an dem der größte Teil des Werts liegt.

Die Ordnerstruktur

Für kleine Features oder Solo-Projekte reicht eine einzige SPEC.md. Für größere Features mit mehreren beweglichen Teilen hat sich die Community auf drei Dateien in einem benannten Ordner geeinigt:

.claude/
├── commands/       # 14 slash commands
├── steering/       # product.md, tech.md, structure.md
├── specs/
│   └── {feature-name}/
│       ├── requirements.md
│       ├── design.md
│       └── tasks.md
├── bugs/           # bug fix workflows
└── agents/

Der steering/-Ordner fungiert als Projektgedächtnis über Sessions hinweg. product.md hält die Vision. tech.md hält Stack-Entscheidungen. structure.md hält Datei-Konventionen. Jede Session, die diese drei Dateien öffnet, startet mit Kontext, dessen Etablierung sonst Dutzende von Hin-und-Her-Nachrichten erfordern würde.

Du kannst Pimzinos vollständiges Scaffold mit einem Befehl installieren:

npx @pimzino/claude-code-spec-workflow

Die Fix-the-Test-Regel

Ohne eine Spec hat Claude zwei Wege zu einer grünen Test-Suite: den defekten Code reparieren oder den fehlschlagenden Test so modifizieren, dass er falsches Verhalten erwartet. Manchmal nimmt es den einfacheren Weg. Das ist kein Bug. Es ist eine rationale lokale Optimierung ohne Einschränkung dagegen.

Die Einschränkung kommt in SPEC.md oder CLAUDE.md:

## During Testing

**IMPORTANT!** When you find a failure during testing, **NEVER** ignore or remove 
the test to bypass the failure.

**ALWAYS** identify the root cause first.

If the root cause is in the *application's implementation*, then fix the application.
If the root cause is because the *test* was incorrectly made, then fix the test.

Das ist eine kleine Ergänzung. Sie schließt einen der häufigsten Fehlermodi in ungeleiteten Sessions.

Der Self-Consistency-Blinde-Fleck

Wenn Claude Opus eine Spec schreibt, kann es seine eigenen Lücken nicht sehen. Das Denken, das die Requirements erzeugt hat, ist noch aktiv, sodass Auslassungen, die nie berücksichtigt wurden, auch bei der Überprüfung unberücksichtigt bleiben.

Ein anderes Modell (GPT oder Codex) zu verwenden, um eine Claude-generierte Spec adversarial zu überprüfen, bringt in nahezu jedem Dokument größere Probleme ans Licht. Das Muster, das funktioniert: zwei separate Agents, jeder explizit mit dem Finden von Lücken, fehlenden Edge Cases und Annahmen-Konflikten beauftragt. Einer sucht nach fehlenden Requirements. Einer sucht nach Implementierungsannahmen, die im Design stecken, aber dem Nutzer gegenüber nie thematisiert wurden. Beide laufen, bevor die Implementierung beginnt.

Das Living-Document-Problem

In dem Moment, in dem deine Spec aus dem Sync mit dem Code gerät, verschwindet ein Großteil des Nutzens. Nachfolgende Sessions können undokumentierte Änderungen stillschweigend rückgängig machen oder Scope basierend auf einem veralteten Design interpretieren.

Der Fix kommt von Sevak Avakians und entspricht dem, was Anthropics interne Teams praktizieren: Der letzte Schritt jedes Aufgabenplans sollte Dokumentations-Updates sein. Bitte Claude am Ende jeder Session, abgeschlossene Arbeit zusammenzufassen und CLAUDE.md-Verbesserungen vorzuschlagen. Anthropics Data Science-Team berichtet von 2-4-fachen Zeitersparnissen bei routinemäßigem Refactoring. Das Security Engineering-Team senkte das Infrastructure-Debugging von 10-15 Minuten auf 5 Minuten. Das Product Dev-Team sah 70 % einer Vim-Mode-Implementierung autonom abgeschlossen. In jedem Fall war guter Kontext beim Session-Start die Variable.

Dokumentation am Session-Ende ist kein Overhead. Es ist, wie die Spec nach dem ersten Build nützlich bleibt.

Fehlermodi

Sechs Muster brechen SDD in der Praxis:

Zu breiter Scope. "Bau ein User-Management-System" ohne Definition, welche Nutzer, welche Aktionen oder welche Berechtigungen bedeutet, dass Claude maximal interpretiert. Das Kontextfenster füllt sich mit Arbeit, die du nicht verlangt hast.

Veraltete Spec. Jemand promptet eine Änderung direkt, ohne die Spec zu aktualisieren. Die nächste Session liest die Spec und macht die Änderung stillschweigend rückgängig.

Kitchen Sink. Zwei unzusammenhängende Features in einer Spec. Claude führt Kreuzkontamination zwischen ihnen ein. Halte Specs auf eine kohärente Arbeitseinheit.

Context Drift. Eine Spec im Kontextfenster wird effektiv "verloren", wenn das Gespräch über 15-20 Tool-Calls hinauswächst. Neue Sessions für die Implementierung verhindern das.

LLM-generierte Spec als Ersatz fürs Denken. Eine ETH-Zürich-Studie fand, dass LLM-generierte Agent-Dateien die Performance verschlechtern und 20 % mehr Token kosten. Vom Menschen geschriebene Specs halfen zu 4 %. Die Spec funktioniert nur, wenn ein Mensch sie überprüft und echte Entscheidungen getroffen hat. Eine abgestempelte Spec ist Rauschen.

Session Bleed. Spec-Erstellung und Implementierung in derselben Session ausführen. Das Attachement-Problem setzt sich durch. Die Spec wird zu einem Vorschlag, nicht zu einer Einschränkung.

Welches Muster wann

Drei Optionen decken das gesamte Spektrum der Projektgrößen ab:

Architecture Decision Records kommen in docs/adr/ mit einem sequenziellen Nummernpräfix. Eine Datei pro Entscheidung. Sie halten fest, was entschieden wurde, welche Alternativen in Betracht gezogen wurden und warum diese Option gewann. Sie sind keine Spec-Dateien. Sie sind permanente Aufzeichnungen von Entscheidungen, die sonst in der Chat-Historie verschwinden würden.

Für die meisten Features in einem Solo-Projekt reicht SPEC.md im Repo-Root. Greife zur Drei-Datei-Struktur, wenn ein Feature die Datenbankschicht, einen API-Contract und eine UI-Komponente im selben Build berührt. Greife zu ADRs, wenn eine Entscheidung architektonisch und folgenreich ist: Auswahl der Event-Queue, Authentifizierungsstrategie, Caching-Layer, API-Versionierungsschema.

Was sich ändert

Die 33 %-First-Attempt-Rate ohne Vorgaben ist keine Modellbeschränkung. Sie spiegelt die Größe des Entscheidungsraums wider, den Claude ohne Einschränkungen navigiert. Eine Spec macht Claude nicht schlauer. Sie macht das Problem kleiner. Du triffst die 20 Entscheidungen im Voraus. Claude führt gegen einen Plan aus, bei dem die Entscheidungen bereits gefallen sind.

Spec zuerst. Neue Session. Living Document. Das ist das Muster.

Häufige Fragen

Was ist Spec-Driven Development mit Claude Code?

Spec-Driven Development ist ein Vier-Phasen-Workflow, bei dem du Requirements, Design und eine geordnete Aufgabenliste schreibst, bevor Claude eine einzige Codezeile schreibt. Die Spec entfernt die ca. 20 Entscheidungen, die Claude sonst selbst treffen würde. Du triffst sie im Voraus. Claude führt gegen einen Plan aus, der bereits abgestimmt ist.

Wie schreibe ich eine Spec für Claude Code?

Öffne eine neue Session und bitte Claude, dich mit dem AskUserQuestion-Tool zu interviewen, bis Implementierung, UX, Edge Cases und Trade-offs abgedeckt sind. Wenn das Interview fertig ist, bitte es, das Ergebnis in SPEC.md zu schreiben. Schließe diese Session. Die nächste Session öffnet die Spec und baut. Der Übergabe zwischen Sessions ist der Ort, an dem der größte Teil des Werts liegt.

Warum sollte ich nach dem Schreiben einer Spec eine neue Session starten?

Claude trägt das Denken aus der Spec-Schreibsession als implizite Annahmen weiter. Es hört auf, die Spec wörtlich zu lesen, und beginnt, Lücken aus dem Gedächtnis zu füllen. Eine neue Session zwingt es, die Spec so zu lesen, wie es ein neuer Entwickler täte: von oben, Wort für Wort, ohne geerbten Kontext aus dem vorherigen Gespräch.

Was kommt in eine Claude Code Spec-Datei?

Eine minimale Spec hat drei Teile: Requirements (was das Feature leisten muss, als User Stories und Akzeptanzkriterien geschrieben), Design (Datenmodelle, API-Contracts, welche Dateien sich ändern) und Tasks (ein geordneter Implementierungsplan, bei dem jeder Schritt seine Abhängigkeiten auflistet). Für kleine Features reicht eine einzige SPEC.md. Größere Features verwenden drei separate Dateien in einem benannten Ordner unter .claude/specs/.

Was ist der Unterschied zwischen Spec-Driven Development und Vibe Coding?

Vibe Coding bedeutet, Claude iterativ zu prompten und zu akzeptieren, wohin das Gespräch führt. Es ist schnell für die Exploration, aber unvorhersehbar in größerem Maßstab. Spec-Driven Development lagert die Entscheidungsfindung in ein schriftliches Dokument aus, bevor Code läuft. Die Spec tauscht eine kleine Menge Vorlaufzeit gegen eine große Reduzierung von Nacharbeit, Scope Drift und Context-Loss zwischen Sessions.

Was ist die Fix-the-Test-Regel im Spec-Driven Development?

Ohne eine schriftliche Einschränkung bringt Claude manchmal einen fehlschlagenden Test zum Bestehen, indem es den Test ändert statt den defekten Code zu reparieren. Die Fix-the-Test-Regel kommt in SPEC.md oder CLAUDE.md: Finde immer zuerst die Ursache, repariere die Anwendung, wenn die Anwendung falsch ist, repariere den Test nur, wenn der Test selbst falsch geschrieben wurde. Diese eine Regel schließt einen der häufigsten Fehlermodi in ungeleiteten Sessions.