Spec-Driven Development mit Claude Code: Ein praxisorientierter Leitfaden
(Wenn Sie Videoinhalte bevorzugen, sehen Sie sich bitte die kurze Videozusammenfassung dieses Artikels unten an.)
Das Wichtigste auf einen Blick
- Spec-driven development mit Claude Code verankert Anforderungen, Architektur und Akzeptanzkriterien in einer versionierten Spezifikationsdatei, bevor Claude Code mit der Implementierung beginnt.
- Im Unterschied zu Vibe Coding bleibt die Spezifikation über mehrere Sitzungen hinweg bestehen und dient als gemeinsame Referenz für das gesamte Team.
- Der Plan Mode von Claude Code unterstützt die Exploration innerhalb einer einzelnen Sitzung, ersetzt aber keine dauerhaften, versionierten Spezifikationsdokumente.
- Eine CLAUDE.md-Datei im Repository vermittelt Claude Code projektspezifisches Wissen zu Konventionen, Architektur sowie Build- und Testbefehlen.
- Tests, Hooks und Subagenten sichern ab, dass die tatsächliche Implementierung mit der Spezifikation übereinstimmt, und liefern damit eine belastbare Grundlage für Governance und Compliance.
- Frameworks wie Superpowers, GitHub Spec Kit und die BMAD Method erweitern Claude Code um zusätzliche Rollen, Vorlagen und Workflows.
- Enterprise-Teams zahlen laut Anthropic im Schnitt rund 13 US-Dollar pro Entwickler und aktivem Tag beziehungsweise 150 bis 250 US-Dollar pro Entwickler und Monat für Claude Code.
Claude Code kombiniert agentenbasierte Codegenerierung mit einem strukturierten Vorgehen, bei dem Anforderungen zunächst in einer Spezifikation festgehalten werden, bevor Code entsteht. SaM Solutions zeigt in diesem Beitrag, wie sich Spec-driven Development mit Claude Code von spontanem Prompting unterscheidet, welche Rolle CLAUDE.md, Tests und Hooks dabei spielen und wie Teams den Workflow schrittweise einführen.
Was ist Spec-Driven Development mit Claude Code?
Claude Code Spec-Driven Development bezeichnet ein Vorgehen, bei dem eine schriftliche Spezifikation der Codegenerierung vorausgeht und während der gesamten Implementierung als verbindliche Referenz dient. Die Spezifikation legt Geschäftsziele, funktionale Anforderungen, technische Rahmenbedingungen und Akzeptanzkriterien fest, bevor Claude Code Dateien anlegt oder verändert. Ein menschlicher Prüfer kontrolliert die Spezifikation und später den erzeugten Code gegen diese Referenz, wodurch Abweichungen früh sichtbar werden. Dieses Vorgehen unterscheidet sich damit grundlegend vom freien Prompting, bei dem Anforderungen nur im Gesprächsverlauf existieren.
Die Spezifikation als zentrale Referenz
Die Spezifikation dient als verbindliche Referenz für alle Beteiligten und wird im Repository versioniert. Dadurch bleibt der Kontext über Sitzungen und wechselnde Entwickler hinweg erhalten. Das sorgt für eine konsistente Grundlage bei:
- neuen Claude-Code-Sitzungen,
- Übergaben zwischen Entwicklern,
- späteren Änderungen am Feature.
Die Rolle der menschlichen Überprüfung
Die menschliche Prüfung ist an zwei zentralen Stellen vorgesehen:
- Freigabe der Spezifikation vor der technischen Planung,
- Freigabe des Plans vor der Implementierung.
So lassen sich Fehlinterpretationen früh erkennen und Entscheidungen nachvollziehbar dokumentieren.
Nutzen Sie das Potenzial von KI und beschleunigen Sie Ihr Business mit maßgeschneiderten Lösungen
Warum scheitert Vibe Coding bei komplexen Projekten?
Vibe Coding stößt bei umfangreichen Projekten an Grenzen, weil mehrdeutige Anforderungen, eine schleichend abweichende Architektur und inkonsistente Implementierungsentscheidungen ohne dokumentierte Referenz kaum zu korrigieren sind. Ohne Spezifikation interpretiert Claude Code jede neue Anweisung isoliert, wodurch frühere Entscheidungen in Vergessenheit geraten. Je mehr Dateien und Funktionen ein Projekt umfasst, desto stärker wirken sich diese drei Schwachstellen auf die Codequalität aus.
Mehrdeutige Anforderungen
- Chat-Anforderungen lassen häufig mehrere technische Interpretationen zu.
- Claude Code kann plausible, aber nicht beabsichtigte Annahmen treffen.
- Unklare Punkte wie 2FA, Social-Login oder Login per E-Mail und Passwort bleiben offen.
- Fehler werden ohne Spezifikation oft erst nach der Implementierung sichtbar.
Schleichende Abweichungen von der Architektur
- Architekturentscheidungen gehen ohne Dokumentation mit dem Sitzungsende verloren.
- Neue Module können dadurch von bestehenden Mustern abweichen.
- Beispiele: unterschiedliche Datenbank-Zugriffslayer, mehrere State-Management-Konzepte.
- Eine dokumentierte Spezifikation mit Architekturvorgaben verhindert solche Inkonsistenzen.
Inkonsistente Implementierung
- Gleichartige Funktionen können unterschiedlich umgesetzt werden.
- Betroffen sind etwa Fehlerbehandlung, Namenskonventionen, Validierungslogik.
- Dadurch steigt der Aufwand für Code-Reviews und Wartung.
- Klare Spezifikationen sorgen für einheitliche Vorgaben bei jeder neuen Aufgabe.
Wie unterscheidet sich Spec-Driven Development vom Plan Mode?
Der Plan Mode von Claude Code verfolgt ein ähnliches Ziel, unterscheidet sich jedoch in Umfang, Lebensdauer und Reproduzierbarkeit. Plan Mode ist eine Berechtigungsstufe innerhalb einer laufenden Sitzung, in der Claude Code den Workflow analysiert und einen Plan vorschlägt, ohne Dateien zu verändern. Eine Spezifikation dagegen ist ein eigenständiges, versioniertes Artefakt, das über einzelne Sitzungen hinaus Bestand hat und von mehreren Teammitgliedern genutzt werden kann.
Umfang und dauerhafte Verfügbarkeit
Plan Mode liest das Repository, erstellt einen Plan und blockiert Änderungen bis zur Freigabe. Der Plan bleibt an die Sitzung gebunden, während eine Spezifikation als Datei im Projekt dauerhaft verfügbar und für spätere Änderungen wiederverwendbar ist.
Nachverfolgbarkeit über mehrere Sitzungen hinweg
Eine im Repository gespeicherte Spezifikation ermöglicht Nachverfolgbarkeit über mehrere Sitzungen hinweg:
- Änderungen an Anforderungen lassen sich in der Versionshistorie verfolgen.
- Codeänderungen können den jeweiligen Anforderungen zugeordnet werden.
- Die Dokumentation dient als belastbare Grundlage für Audits und Fehleranalysen.
Ein Plan aus dem Plan Mode bietet diese langfristige Nachverfolgbarkeit ohne zusätzliche Dokumentation kaum.
Reproduzierbarkeit für Teams
Eine Spezifikationsdatei kann im Repository geteilt, per Pull Request kommentiert und von anderen Entwicklern weiterverwendet werden. Ein Plan aus dem Plan Mode bleibt dagegen meist an eine Sitzung und die erstellende Person gebunden. Dadurch schafft die Spezifikation eine gemeinsame und reproduzierbare Ausgangsbasis für das Team.
Wie erstellt man eine effektive Spezifikation?
Eine effektive Spezifikation für Spec-Driven Development mit Claude Code benennt Geschäftsziele und Anwendungsszenarien, beschreibt funktionale Anforderungen im Detail, dokumentiert technische Rahmenbedingungen und listet Grenzfälle mit prüfbaren Akzeptanzkriterien auf. Fehlt einer dieser vier Bausteine, muss Claude Code an dieser Stelle eine eigene Annahme treffen, die nicht zwingend der Absicht des Auftraggebers entspricht. Je präziser diese vier Elemente formuliert sind, desto geringer fällt der Korrekturaufwand nach der ersten Implementierung aus.
Wie unterstützt CLAUDE.md das Spec-Driven Development?
Eine CLAUDE.md-Datei im Repository ergänzt die Spezifikation um projektweites Hintergrundwissen, das Claude Code bei jeder Sitzung automatisch lädt. Sie enthält Projektanweisungen und Konventionen, eine Beschreibung der Repository-Architektur, die relevanten Befehle für Build und Tests sowie Hinweise zum Geltungsbereich der jeweiligen Datei. Während die Spezifikation eine einzelne Aufgabe beschreibt, liefert CLAUDE.md den dauerhaften Kontext, der für alle Aufgaben in diesem Projekt gilt.
Projektanweisungen und Konventionen
CLAUDE.md dokumentiert zentrale Coding-Konventionen, Namensregeln und stilistische Vorgaben, damit Claude Code sie nicht in jeder Sitzung neu erfragen muss. Dazu gehören etwa:
- verwendeter Formatierer,
- Regeln für API-Fehler,
- Namenskonventionen.
Anthropic empfiehlt eine schlanke Datei mit etwa 200 Zeilen. Umfangreichere Anweisungen können in separate Skills ausgelagert werden.
Repository-Architektur
Ein Abschnitt zur Repository-Architektur beschreibt die Struktur des Projekts und die Beziehungen zwischen den Modulen. So findet Claude Code den richtigen Ablageort für neue Funktionalität und berücksichtigt bestehende Muster. In großen Monorepositories können verzeichnisspezifische CLAUDE.md-Dateien verwendet werden, die nur die relevante Architektur beschreiben.
Befehle für Build und Tests
CLAUDE.md enthält die konkreten Befehle für Build, Tests und lokale Ausführung. Dadurch kann Claude Code sie im weiteren Workflow direkt ausführen und nach der Implementierung die Änderungen prüfen. Fehlen diese Angaben, besteht das Risiko, dass Änderungen trotz vermeintlicher Tests ungeprüft bleiben.
Geltungsbereich und Pflege der Anweisungen
CLAUDE.md kann auf mehreren Ebenen liegen:
- Benutzerverzeichnis für persönliche Einstellungen,
- Projektverzeichnis für teamweite Vorgaben,
- Unterverzeichnisse für modulspezifische Regeln.
Die Ebenen ergänzen sich, wobei spezifische Vorgaben allgemeine Regeln überschreiben können. Veraltete oder widersprüchliche Einträge sollten regelmäßig entfernt werden; bei vielen Repositories bietet sich eine zentrale CLAUDE.md-Vorlage an.
Wie führt der Workflow von der Spezifikation zur Implementierung?
Der Workflow von der Spezifikation zur fertigen Implementierung gliedert sich in sechs aufeinander aufbauende Schritte: Repository-Analyse, Präzisierung der Anforderungen, Erstellung der Spezifikation, Ausarbeitung des technischen Plans, Implementierung mit Tests sowie abschließende Prüfung des Diffs. Jeder Schritt liefert ein überprüfbares Zwischenergebnis, bevor der nächste beginnt, sodass Fehlannahmen frühzeitig auffallen.
Wie gewährleisten Tests, Hooks und Agents die Einhaltung der Spezifikation?
Tests, Hooks und spezialisierte Agents sichern gemeinsam ab, dass die tatsächliche Implementierung der Spezifikation entspricht, indem sie Anforderungen auf konkrete Testfälle abbilden, Regeln automatisiert durchsetzen, Aufgaben in überschaubare Einheiten aufteilen und eine unabhängige Überprüfung ermöglichen. Diese vier Mechanismen wirken zusammen wie ein Kontrollsystem, das menschliche Reviews entlastet, ohne sie vollständig zu ersetzen. Für Unternehmen mit Compliance-Anforderungen entsteht dadurch eine nachvollziehbare, technisch durchsetzbare Grundlage für Governance.
Zuordnung von Anforderungen zu Tests
Jede Anforderung sollte sich mindestens einem automatisierten Test zuordnen lassen. So wird sichtbar, welche Anforderungen bereits abgedeckt sind und wo Testlücken bestehen. Claude Code kann diese Zuordnung direkt aus präzise formulierten Akzeptanzkriterien ableiten.
Automatisierte Validierung
Hooks ermöglichen feste Prüfungen an definierten Punkten einer Claude-Code-Sitzung und sorgen für Automatisierung und Validierung. Beispiele:
- PostToolUse-Hook: führt nach Codeänderungen automatisch Formatter oder Linter aus.
- Stop-Hook: startet vor Sitzungsende die vollständige Testsuite.
So laufen wichtige Qualitätsprüfungen unabhängig vom Verhalten des Modells ab.
Aufteilung in einzelne Aufgaben
Große Spezifikationen lassen sich in kleinere, unabhängig prüfbare Aufgaben aufteilen und über spezialisierte Subagenten bearbeiten. Dabei kann beispielsweise ein Agent Tests schreiben und ein anderer die Geschäftslogik implementieren. Kleinere Kontexte reduzieren Informationsverluste und ermöglichen bei großen Projekten parallele Bearbeitung.
Unabhängige Überprüfung
Ein separater Agent oder Prozess kann Abweichungen erkennen, die während der Implementierung übersehen wurden. Besonders sinnvoll sind:
- unabhängige Sicherheitsprüfungen durch einen Review-Agenten,
- menschliche Freigaben bei sicherheitskritischen Änderungen.
So lassen sich die blinden Flecken des ursprünglichen Implementierungsprozesses besser erkennen.
Welche Frameworks können Claude Code erweitern?
Mehrere quelloffene Frameworks erweitern Claude-Code-Spec-Driven-Development um zusätzliche Rollen, Vorlagen und feste Prozessschritte: Superpowers, GitHub Spec Kit und die BMAD Method. Alle drei setzen auf dieselbe Grundidee, unterscheiden sich jedoch in Umfang, Struktur und Zielgruppe. Welches Framework zu einem Projekt passt, hängt von der Teamgröße, der Projektkomplexität und dem gewünschten Grad an Formalisierung ab.
Superpowers
Superpowers ist ein quelloffenes Skills-Framework von Jesse Vincent, das einen festen Entwicklungsprozess in Claude Code integriert. Der Prozess umfasst:
- Brainstorming und Designfreigabe,
- Planerstellung und testgetriebene Entwicklung nach Red-Green-Refactor,
- isolierte Arbeitsbereiche über Git Worktrees,
- systematisches Debugging.
Das Framework eignet sich besonders für Teams, die einen durchgängigen Entwicklungsprozess unabhängig vom eingesetzten KI-Werkzeug etablieren möchten.
GitHub Spec Kit
GitHub Spec Kit ist ein Toolkit von GitHub, das Slash-Befehle für Claude Code und andere Coding-Agents bereitstellt. Der Ablauf umfasst:
- eine Konstitution mit grundlegenden Architekturprinzipien,
- Erstellung von Spezifikationen, Plänen und Aufgaben,
- anschließende Implementierung.
Jede Phase dient als Kontrollpunkt, sodass Entwickler gezielte Änderungen statt umfangreicher Codeausgaben prüfen. Das Toolkit ist werkzeugunabhängig einsetzbar.
BMAD Method
Die BMAD Method (Breakthrough Method for Agile AI-Driven Development) bildet ein agiles Rollenmodell mit spezialisierten Agenten für Analyse, Produktmanagement, Architektur, Entwicklung und Qualitätssicherung ab. Die Agenten arbeiten aufeinander abgestimmt und tauschen unter anderem Product Requirements Documents und Architekturdokumente aus.
Für kleinere Änderungen bietet das Framework vereinfachte technische Spezifikationen, während umfangreiche Projekte vollständige PRDs und formale Qualitäts-Gates durchlaufen. BMAD ist quelloffen und mit Claude Code sowie anderen KI-Entwicklungsumgebungen kompatibel.
Auswahl des passenden Frameworks
Die Wahl hängt davon ab, wie stark der Entwicklungsprozess formalisiert werden soll:
- Superpowers: für eine disziplinierte Entwicklungsroutine mit Tests und Reviews.
- GitHub Spec Kit: für einen strukturierten, werkzeugunabhängigen Ablauf von der Spezifikation bis zur Implementierung.
- BMAD Method: für ein vollständiges agiles Rollenmodell mit spezialisierten Agenten und dokumentierten Übergaben.
Welche Vorteile und Einschränkungen gibt es?
Spec-Driven Development mit Claude Code verbessert Vorhersagbarkeit, Nachverfolgbarkeit und Review-Geschwindigkeit, bringt jedoch auch das Risiko von Spezifikationsabweichungen, ein wachsendes Kontextfenster und zusätzlichen Pflegeaufwand mit sich. Diese Vor- und Nachteile stehen in direktem Zusammenhang, da der zusätzliche Aufwand für die Spezifikationserstellung durch geringere Nacharbeit im späteren Verlauf ausgeglichen werden soll. Für eine realistische Einschätzung sollten Unternehmen beide Seiten gegeneinander abwägen, statt nur die Vorteile zu betrachten.
Wie können Teams den Workflow einführen und skalieren?
Teams führen Spec-Driven Development mit Claude Code am erfolgreichsten über ein begrenztes Pilotprojekt ein, entwickeln daraus gemeinsame Vorlagen, legen verbindliche Regeln und Verantwortlichkeiten fest, messen anschließend die Qualität der Softwarebereitstellung und stimmen Spezifikationen kontinuierlich mit der tatsächlichen Implementierung ab. Dieser stufenweise Ansatz vermeidet, dass ein neuer Prozess ganzen Entwicklungsteams gleichzeitig übergestülpt wird, ohne dass sich seine Wirkung vorher zeigen konnte. Jede der fünf Phasen liefert dabei konkrete Erkenntnisse für die jeweils nächste.
Mit einem Pilotprojekt beginnen
- Ein überschaubares Feature auswählen, um den neuen Workflow risikoarm zu testen.
- Ein Projekt mit klaren, aber nicht trivialen Anforderungen wählen.
- Erkenntnisse zur Detailtiefe der Spezifikationen und zur CLAUDE.md-Struktur sammeln.
- Erst nach erfolgreichem Piloten auf weitere Teams ausweiten.
Gemeinsame Vorlagen erstellen
- Wiederverwendbare Vorlagen für Spezifikationen, technische Pläne und CLAUDE.md-Dateien entwickeln.
- Wichtige Abschnitte wie Geschäftsziele, Anforderungen und Akzeptanzkriterien vorgeben.
- Einheitliche Strukturen erleichtern die Einarbeitung neuer Teammitglieder.
- Vorlagen über ein zentrales Skill- oder Plugin-Repository bereitstellen.
Verbindliche Regeln und Verantwortlichkeiten festlegen
- Zuständigkeiten für Freigaben, Plan-Reviews und die Pflege der CLAUDE.md-Dateien definieren.
- Einheitliche Prozessregeln für alle Teams festlegen, um die Governance zu stärken.
- Regeln technisch über Versionsverwaltung oder zentrale Claude-Code-Konfigurationen absichern.
- Verantwortlichkeiten konkreten Rollen zuweisen.
Die Qualität der Softwarebereitstellung messen
- Kennzahlen wie Review-Runden, Zeit von Spezifikation bis Merge und nachträgliche Abweichungen erfassen.
- Vor der Einführung Ausgangswerte ermitteln und regelmäßig vergleichen.
- Rework nach der ersten Implementierung als wichtigen Erfolgsindikator beobachten.
- So den tatsächlichen Nutzen des Prozesses messbar machen.
Spezifikationen und Implementierungen aufeinander abstimmen
- Regelmäßig prüfen, ob Spezifikation und Code noch übereinstimmen.
- Abgleich beispielsweise in Sprint-Reviews durchführen.
- Hooks nutzen, um Codeänderungen ohne entsprechende Spezifikationsänderung zu erkennen.
- Die kontinuierliche Abstimmung auch bei wachsender Teamzahl sicherstellen.
Fazit
Spec-Driven Development mit Claude Code verankert Anforderungen, Architektur und Akzeptanzkriterien in einer versionierten Spezifikation und macht damit die Zusammenarbeit zwischen Mensch und KI-Agent über einzelne Sitzungen hinweg nachvollziehbar. Für B2B-Unternehmen bedeutet dieser strukturierte Workflow vorhersagbarere Ergebnisse, kürzere Review-Zyklen und eine belastbare Grundlage für Compliance-Anforderungen, sofern Spezifikationen und CLAUDE.md-Dateien kontinuierlich gepflegt werden. Wer den Ansatz mit einem Pilotprojekt beginnt und sich schrittweise auf weitere Teams ausweitet, gewinnt einen realistischen Eindruck davon, wie sich Claude Code produktiv in bestehende Entwicklungsprozesse integrieren lässt.
FAQ
