Spec-gesteuerte Entwicklung mit Claude Code: Ein geführtes Tutorial

Was ist spec-gesteuerte Entwicklung?

Spec-gesteuerte Entwicklung ist ein Workflow, der auf drei Dokumenten in Reihenfolge basiert: eine Spezifikation, die sagt, was sich ändern soll, ein Plan mit den konkreten Schritten, und der Code, der diesen Plan umsetzt — mit einem menschlichen Review zwischen jedem Paar.

Die drei Prüfstellen, die ein Feature in der spec-gesteuerten Entwicklung durchläuft.

Eine Spec ist ein kurzes, in Alltagssprache geschriebenes Dokument, das vor jedem Code festlegt, was eine Änderung leisten soll. Nimm ein Feature wie „Nutzende können ihre Daten exportieren“. Eine Spec dafür fixiert Antworten, die ein Agent sonst raten würde. Sie listet auf 

• Unterstützte Dateiformate
• Die Auslieferungsart
• Das Verhalten bei einem halb fertigen Export
• Die Teile des Features, die bewusst ausgeklammert bleiben

Hier ist der echte Anfang einer Spec, die Claude Code für eine workout-shape-verification-Änderung in einer meiner Telegram-basierten Accountability-Apps geschrieben hat. Die Änderung ersetzt einen fragilen Puls-Schwellenwert durch eine Prüfung der Form der Herzfrequenzkurve über die Zeit:

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

Der Plan ist das nächste Dokument. Er bricht die Spec in nummerierte Aufgaben herunter, die der Agent nacheinander abarbeitet — jede Aufgabe mit Datei, Änderung, Reihenfolge und Test. Wo die Spec das „Was“ beantwortet, beantwortet der Plan das „In welchen Schritten“.

Der Code kommt zuletzt, entlang des Plans Aufgabe für Aufgabe geschrieben.

Drei Dokumente. Zwischen jedem Paar sitzt ein menschlicher Review. Du prüfst die Spec, bevor sie zum Plan wird. Du prüfst den Plan, bevor Code geschrieben wird. Du prüfst den Code, bevor er gemergt wird.

Worin sich spec-gesteuerte Entwicklung vom Planmodus unterscheidet

Vielleicht hast du den eingebauten Planmodus von Claude Code genutzt (zweimal Umschalt+Tab) und fragst dich, was hier anders ist. Der Planmodus erzeugt einen Plan in einem einzelnen Chat-Turn. Der Plan lebt im Speicher, ohne persistierte Spec und ohne Review-Schritt zwischen den Phasen.

Spec-gesteuerte Entwicklung persistiert Spec und Plan als Dateien auf der Platte. Beide durchlaufen einen menschlichen Review, bevor die nächste Phase startet, und die Artefakte überdauern Sessions. Der Planmodus verdichtet zwei Phasen der Softwareentwicklung in einen Chat-Turn. Das funktioniert bei kleinen Aufgaben und bricht, sobald der Code größer wird und echte Nutzende bedient.

Warum Vibe-Coding an Grenzen stößt

Vibe-Coding funktioniert für Prototypen, einzelne Dateien und Wegwerfskripte. In realen Anwendungen mit Nutzenden und in großen Codebasen wird es problematisch. Die sinnvolle Grenze liegt bei etwa vier Dateien. Jede Änderung, die so viele Dateien berührt, braucht eine Spec — ebenso Refactorings mit klarem Zielzustand oder Aufgaben, bei denen „Was genau soll das tun?“ der schwierige Teil ist.

Die Ursache ist klar: Ein vager Prompt wie „Füge meiner App Fotosharing hinzu“ zwingt das Modell, tausende unausgesprochene Anforderungen zu raten.

Nimm nur eine davon: Benachrichtigungseinstellungen. Die Produktperson erwartet kanalweise Schalter. Das Backend baut einen An/Aus-Schalter. Das Frontend erwartet OS-Integration. Vier plausible Lesarten von drei Wörtern, vier verschiedene Produkte.

Jeder Review-Schritt in der spec-gesteuerten Entwicklung fängt eine andere Fehlerklasse ab, bevor es teuer wird. Der Spec-Review stoppt Scope Creep und falsche Problemrahmungen. Der Plan-Review fängt halbfertige Implementierungen und widersprüchliche Muster. Der Code-Review deckt Pläne auf, die gut klingen, aber am ersten fehlgeschlagenen Test scheitern.

Der Nutzen ist echt — und baut sich langsam auf. Die Spec-Phase kostet Stunden Schreibzeit, bevor Code läuft, und die ersten Features fühlen sich langsamer an als Vibe-Coding. Mein persönlicher Break-even kam beim vierten oder fünften Feature. Ab da fingen die Specs Designfehler ab, die ich sonst ausgeliefert und eine Woche später umgeschrieben hätte.

Die nächsten drei Abschnitte führen durch drei Open-Source-Ansätze, die diesen Workflow in Claude Code abbilden. Sie sind nach der Strenge der Struktur vom leichtesten zum schwersten sortiert.

Superpowers

Superpowers ist der leichteste der drei Ansätze. Ich nutze ihn täglich — und wir gehen hier am ausführlichsten darauf ein.

Was ist Superpowers?

Superpowers ist ein Claude-Code-Plugin von Jesse Vincent (obra/superpowers, MIT-Lizenz) mit rund 194k Sternen auf GitHub.

Es liefert einen Satz an Skills aus. Eine Claude-Skill ist in Claude Code eine benannte Anleitungsdatei, die der Agent bei Bedarf lädt, um einem spezifischen Workflow zu folgen. Superpowers liefert Skills, die Claude Code in die spec-gesteuerte Schleife zwingen, statt es direkt in den Code springen zu lassen.

Die Projektseite von Superpowers auf GitHub.

So installierst du Superpowers

Installiere es über den offiziellen Plugin-Marktplatz von Claude Code:

/plugin install superpowers@claude-plugins-official

Ein SessionStart-Hook lädt die using-superpowers-Skill automatisch, sodass der Workflow aktiv ist, sobald du zu tippen beginnst. (Claude-Code-Hooks sind Skripte, die der Agent zu bestimmten Lebenszyklusereignissen ausführt.) Es ist nichts pro Projekt zu verkabeln.

Der Superpowers-Workflow

Anschließend steuern vier Skills deine tägliche Arbeit:

Ein Subagent ist eine separate Claude-Code-Instanz, die der Parent für fokussierte Arbeit in einem eigenen Kontextfenster startet. Die Reviewer in der Tabelle laufen als Subagenten — sie lesen den Code unvoreingenommen, ohne das Framing des Parents.

So nutzt du Superpowers

Du rufst die vier Skills auf, indem du in Alltagssprache beschreibst, was du willst. Die Brainstorming-Skill erkennt „Lass uns dieses neue Feature besprechen“ und startet die Spec-Unterhaltung automatisch. Die anderen triggern auf die gleiche Weise.

Die vier Superpowers-Skills in Reihenfolge, mit den beiden menschlichen Review-Punkten zwischen brainstorming und writing-plans.

Die folgende Schritt-für-Schritt-Anleitung nutzt dasselbe workout-shape-verification-Feature aus dem Spec-Auszug oben.

Phase 1: Vom Brainstorm zur Spec

Ich öffne Claude Code und tippe:

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

Die brainstorming-Skill übernimmt und stellt etwa zehn Rückfragen, unter anderem:

• Was als die richtige „Form“ gilt
• Welche Datenströme kombiniert werden
• Was mit Sessions passiert, die von der Form her passen, aber an einer alten Schwelle scheitern
• Ob die Änderung auch für Run und Ride gelten soll

Hier gibt es zwei menschliche Review-Punkte. Der erste ist das Design-Review: Ich bestätige, dass meine Antworten wirklich das widerspiegeln, was ich will. Der zweite ist der Spec-Review: Ich lese die von Claude geschriebene Datei und gebe sie frei, bevor Planarbeit beginnt.

Phase 2: Von der Spec zum Plan

Ich starte die writing-plans-Skill. Sie liest die freigegebene Spec und schreibt eine Plan-Datei mit vier Teilen:

• Eine Definition von „Done“
• Eine Dateikarte der betroffenen Dateien
• Eine User Journey durch den Demo-Pfad
• Eine nummerierte Aufgabenliste mit Checkbox-Teilschritten

Ich prüfe den Plan, verschiebe Schritte, die unlogisch wirken oder zu grob sind, und gebe frei.

Phase 3: Vom Plan zum Code

Ich starte subagent-driven-development. Ab hier läuft die Schleife ohne mich. Für jede Aufgabe im Plan:

1. Schreibt sie einen fehlschlagenden Test
2. Schreibt den Code, um ihn zu bestehen
3. Refaktoriert
4. Startet einen Code-Review-Subagenten, der den Diff kalt liest

Wenn der Reviewer etwas bemängelt, behebt die Schleife das Problem, bevor sie zur nächsten Aufgabe übergeht. In dieser Phase gibt es keinen menschlichen Review-Punkt. Die relevanten Reviews liegen in den beiden Phasen davor.

Phase 4: Review des Gesamtdiffs

Sobald der Plan abgearbeitet ist, starte ich requesting-code-review. Ein frischer Subagent liest den gesamten Diff gegen Spec und Plan und postet ein Review. Ich übernehme die Vorschläge vor dem Merge.

Wenn sich in einer Plan-Aufgabe ein Widerspruch zur Spec zeigt, hält die Schleife an und fragt nach. Ich kann die Spec bearbeiten (oder Claude lassen) und die betroffenen Aufgaben neu generieren. Alternativ korrigiere ich den Einzelfall in der Aufgabe. Superpowers arbeitet Spec-Fehler nicht stillschweigend um.

Echte Specs und Pläne auf der Platte

Hier ist die Spec für das Feature workout-shape-verification, geöffnet im Editor:

Die Spec-Datei, wie sie nach dem Schreiben durch die Brainstorming-Skill auf der Platte landet.

Der Header enthält die Felder Created, Status und Supersedes, die die Brainstorming-Skill standardmäßig schreibt. Es folgt der Abschnitt Problem. Nichts davon ist Code. Die Datei geht über den Screenshot hinaus mit Abschnitten zur vorgeschlagenen Lösung und zu den Grenzen dessen, was die Änderung berührt bzw. nicht berührt.

Der passende Plan beginnt mit seiner User Journey:

Die Plan-Datei, die die writing-plans-Skill aus der freigegebenen Spec erzeugt.

Die Journey führt den Demo-Pfad in Fünferschritten entlang, mit den genauen Kommandos, Dateien und Argumenten in jedem Schritt. Die anschließenden nummerierten Aufgaben übersetzen jeden Schritt in Checkbox-Teilschritte, die die Skill subagent-driven-development abarbeiten kann.

Die beiden Dokumente greifen so ineinander:

Spec und Plan Seite an Seite. Die Spec beantwortet, was sich ändert und warum. Der Plan beantwortet, in welchen Schritten.

Für größere Specs und Pläne ergänze ich einen Schritt, den die offizielle Schleife nicht vorsieht: einen Red-Team-Check. Bevor ich freigebe, lasse ich ein oder mehrere Opus-Subagenten die Spec unvoreingenommen lesen und aus verschiedenen Blickwinkeln nach Lücken suchen. Das ist persönliche Praxis, kein Superpowers-Feature — hat aber genug Annahmefehler gefunden, dass ich es beibehalte.

Wann Superpowers nicht passt

Superpowers passt für Solo-Arbeit an einem einzelnen Repo. Es spielt seine Stärken aus, wenn die gesamte Codebasis in eine Claude-Code-Session passt und du eine 2-seitige Spec wirklich liest. Den detaillierten Vergleich findest du weiter unten in So wählst du zwischen den Ansätzen. Kurzfassung: Superpowers tut sich schwer mit Multi-Repo-Features und Arbeit, die klare Rollentrennung verlangt.

Ein Entwickler benannte öffentlich noch einen vierten Fehlermodus des Plugins: „Selbst die kleinsten Aufgaben dauern ewig, weil Claude Subagenten startet und völlig überdimensionierte Pläne schreibt. Ein bisschen CSS ändern dauert jetzt ewig.“

Die Lösung: Superpowers bei Mini-Änderungen weglassen. Die Skills triggern nur beim Brainstorming-Auslöser. Eine Einzeilen-CSS-Änderung kann durch Claude Code laufen, ohne je die Spec-Schleife zu aktivieren. Das eigentliche Problem ist hier die Überanwendung des Workflows auf Arbeit, die keine Spec braucht.

GitHub Spec Kit

Spec Kit ist die richtige Wahl, wenn die Spec länger leben muss als eine einzelne Claude-Code-Session. Ebenso, wenn Menschen die Spec lesen sollen, die Claude Code nie öffnen.

Was ist das GitHub spec-kit?

Spec Kit ist ein GitHub-Projekt (github/spec-kit, MIT-Lizenz) — von GitHub selbst gepflegt, mit über 100k Sternen. Es liefert eine CLI plus einen Workflow, der mit allen großen KI-Coding-Agenten gleich läuft. Claude Code, Cursor, Aider, Cline und Roo Code werden unterstützt. Diese Agenten-Neutralität erlaubt es, die Spec außerhalb von Claude Code zu leben.

Die Projektseite des Spec Kit auf GitHub.

So installierst du das GitHub spec-kit

Es gibt noch kein offizielles PyPI-Paket, daher installierst du die CLI per Git-Tag mit uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Ersetze vX.Y.Z durch den aktuellen Release-Tag. Das Paket heißt specify-cli, und der registrierte Befehl ist specify.

Der GitHub-spec-kit-Workflow

Der Workflow läuft über neun Slash-Befehle, die die CLI in die Slash-Command-Liste deines Agents einträgt. Sechs sind Kern des Loops, drei optional für Fälle außerhalb des Kerns.

Der Trenner zwischen Befehlsgruppe und Verb ist ein Punkt, kein Doppelpunkt: /speckit.specify, nicht /speckit:specify.

Die neun Spec-Kit-Slash-Befehle: sechs Kernbefehle auf der Pipeline, drei optionale hängend darunter.

Die erzeugten Artefakte sind die gleichen Spec- und Plan-Dateien wie im Superpowers-Abschnitt — ebenfalls auf der Platte, von Git verfolgt. Der Unterschied ist die Portabilität: Spec Kit ist für jeden KI-Coding-Agenten gedacht, nicht nur Claude Code, und der Workflow zielt auf Stakeholder-Reviews via GitHub-Pull-Requests statt als Nebenprodukt eines einzelnen Tools.

Wann du das GitHub spec-kit nutzen solltest

Im Solo-Projekt brauchst du Spec Kit meist nicht. Greif dazu, wenn:

• Das Projekt über eine Person hinauswächst
• Deine Spec von Menschen gelesen werden muss, die Claude Code nie öffnen
• Du für Teile der Arbeit einen Nicht-Claude-Code-Agenten nutzt
• Du ein Spec-Format willst, das unabhängig von Tools lebt und in Monaten noch lesbar ist

Die BMAD-Methode

Während Spec Kit Artefakte organisiert, organisiert BMAD Menschen. Es teilt den Spec-zu-Code-Workflow in vier Phasen, die jeweils von einem benannten Rollen-Agenten geführt werden.

Was ist BMAD?

BMAD-METHOD (bmad-code-org/BMAD-METHOD, MIT-Lizenz, etwa 47k Sterne) ist in Version 6. Das Akronym steht in den Projektunterlagen für „Breakthrough Method for Agile AI-Driven Development“. Es läuft auf Claude Code und anderen Agenten und installiert sich als Modulsystem. Die Standardinstallation bringt ein Kernmodul mit sechs Rollen-Agenten, vier Workflow-Phasen und 34+ benannten Workflows.

Die Projektseite von BMAD-METHOD auf GitHub.

So installierst du BMAD

Installiere BMAD mit Node:

npx bmad-method install

Die sechs Rollen-Agenten sind Prompt-Personas, die du im Host-Agenten per Namen aktivierst. In Claude Code bedeutet das, den von BMAD installierten Aktivierungsbefehl zu tippen. Die genaue Syntax steht im README und ändert sich zwischen Releases.

Die BMAD-Teamagenten und Artefakte

Einmal aktiviert, übernimmt der Agent die Anweisungen, Stimme und Outputs dieser Rolle, bis du wechselst. Die sechs sind:

• Mary, die Analystin
• Paige, die Technische Redakteurin
• John, der Product Manager
• Sally, die UX-Designerin
• Winston, der Architekt
• Amelia, die Entwicklerin

Zwei erwartbare Rollen fehlen in v6: Es gibt keinen Scrum-Master-Agenten und keinen separaten QA-Agenten. Sprint-Planung und Story-Vorbereitung fallen an den Developer-Agenten, und QA-Testgenerierung ist ein Workflow, den der Developer auslöst.

Der Artefakt-Satz ist umfangreicher als eine einzelne Spec. Du bekommst:

• ein Product Brief
• ein PRD (Product Requirements Document)
• eine UX-Spec
• ein Architektur-Dokument
• Epics, heruntergebrochen in User Stories (was Nutzende nach dem Release tun können)

PRD und Architektur-Dokument übernehmen gemeinsam die Rolle der Superpowers-Spec. Die Aufteilung verteilt sie auf zwei Rollen-Agenten und in ein formaleres Format. Der gesamte Artefakt-Satz deckt den kompletten Software-Lifecycle ab, jede Funktion erbt Kontext von der Ebene darüber.

Der BMAD-Workflow

Der v6-Workflow läuft in vier Phasen.

Die vier BMAD-Phasen und die jeweils zuständigen Rollen-Agenten. Der Quick-Flow-Track überspringt für kleine Aufgaben die ersten drei Phasen.

Phase 1, Analysis, ist optional. Mary (Analystin) und Paige (Tech Writer) recherchieren und erstellen ein Product Brief. Überspringe die Phase, wenn klar ist, was gebaut wird.

Phase 2, Planning, ist Pflicht. John (PM) schreibt das PRD. Sally (UX) ergänzt eine UX-Spec, wenn das Feature eine UI hat.

Phase 3, Solutioning, gehört Winston. Der Architekt entwirft zuerst die Architektur, dann bricht John Anforderungen in Epics und Stories herunter. Stories nach der Architektur zu schneiden ist eine v6-Entscheidung, um sie an realen Implementierungsgrenzen auszurichten. Winston führt anschließend einen Implementierungs-Readiness-Check mit PASS, CONCERNS oder FAIL durch.

Phase 4, Implementation, ist Amelias Spielfeld. Sie arbeitet Story für Story: Story anlegen, bauen, Code reviewen. Ist ein ganzes Epic fertig, stößt sie einen QA-Testgenerierungs-Workflow über das gesamte Epic an. Hier schreibt Claude Code den eigentlichen Code — als Amelia.

Für kleine, klar umrissene Arbeiten bringt BMAD einen „Quick Flow“, der Amelia direkt aktiviert und die ersten drei Phasen überspringt. Der Befehl steht im README (Syntax ändert sich zwischen Releases). Quick Flow erzeugt kein PRD und kein Architektur-Dokument — nur eine kurze Story und den Code, der sie erfüllt. Das ist die Antwort auf „Für eine Button-Änderung ist das Overkill.“

Stellt sich die Spec während der Implementierung als falsch heraus, springt BMAD über Winstons Phase‑3‑Urteil zurück. Ein FAIL schickt dich in Phase 2, um das PRD neu zu schreiben. Ein CONCERNS macht weiter — mit Winstons Risiken an der Story. So kommst du bei kleinen Inkonsistenzen voran und stoppst hart bei großen.

Wann sich die Komplexität lohnt

BMAD zahlt sich bei langfristigen Projekten mit echten Nutzenden aus. Es passt auch für Teams mit mehreren Entwickelnden und klaren Übergaben. Die Trennung nach Phasen und Rollen muss mehr Zeit sparen, als sie kostet.

Für ein Ein-Personen-Side-Project ist es die falsche Wahl. Bei Solo-Arbeit ist die Aufteilung in vier Phasen und sechs Agenten vor allem Overhead. Es gibt keine zweite Person, für die Rollentrennung zählt.

So wählst du zwischen den Frameworks

Drei Regeln entscheiden die Wahl.

• Nutze Spec Kit, wenn die Spec von Menschen gelesen werden muss, die Claude Code nie öffnen, oder wenn sie als Langzeit-Artefakt in Git leben soll.
• Wenn mehrere Personen in klar getrennten Rollen arbeiten oder ein echter PM-ähnlicher Stakeholder eingebunden ist, nutze BMAD.
• Sonst: Nutze Superpowers.

Drei Fragen zu deinem Projekt, vier passende Framework-Optionen.

Es gibt eine vierte Option, die der Entscheidungsbaum nennt: Spec Kit mit Superpowers kombinieren. Nutze Spec Kit für die Spec-Phase, damit die Artefakte in Git für teamübergreifende Reviews leben. Dann verknüpfe die Superpowers-Skill subagent-driven-development per einer Zeile Konfiguration mit der Spec-Kit-Plan-Datei. Du bekommst die dauerhafte Spec von Spec Kit und die enge Umsetzungsschleife von Superpowers.

Fazit

Spec-gesteuerte Entwicklung besteht aus drei Dokumenten in Reihenfolge. Die Spec sagt, was gebaut wird, der Plan sagt, in welchen Schritten, und der Code folgt dem Plan. Zwischen jedem Paar liegt ein menschlicher Review.

Geh den Entscheidungsbaum oben durch, um ein Framework zu wählen — für die meisten führt er zu Superpowers. Installier es und nimm ein Feature, das du sonst „vibe-coden“ würdest, etwas, das 3 bis 5 Dateien berührt. Fahr es Ende-zu-Ende durch Brainstorm, Spec, Plan und Ausführung. Ein echter Durchlauf lehrt den Workflow besser als jede Beschreibung.

Wenn du Claude-Code-Grundlagen auffrischen willst, hat DataCamp ein praktisches Claude-Code-Tutorial, einen Best-Practices-Guide zu Planmodus, CLAUDE.md und TDD und einen Deep Dive zum Planmodus selbst.