Agentic Coding mit Spec-Driven Development: Warum Ihr KI-Agent Struktur braucht, bevor er Code schreibt

Die meisten Entwickler optimieren bei KI-Coding-Tools das Falsche. Sie wollen schnellere Code-Generierung. Also schreiben sie längere Prompts, fügen mehr Kontext hinzu und hoffen, dass der Output näher an dem liegt, was sie brauchen. Wenn nicht, korrigieren sie manuell und versuchen es erneut. Das Problem ist nicht das Modell — es ist die fehlende Struktur um das Modell herum.

Nach 20+ Jahren Backend-Entwicklung, von Legacy-PHP-Monolithen bis zu cloud-nativen Go-Microservices, ist das Muster bekannt: undisziplinierter Prozess produziert unvorhersehbaren Output. Das gilt für menschliche Entwickler genauso wie für KI-Agenten. Dieser Artikel handelt von einem Claude Code Plugin namens Superpowers und davon, wie man es mit einem spec-driven Workflow kombiniert, um zuverlässigen, architekturkonformen Output vom KI-Agenten zu bekommen — konsequent und wiederholbar.

Der Failure Mode, über den niemand spricht

Hier ist, was tatsächlich passiert, wenn man Struktur überspringt und direkt zur Generierung übergeht: Claude produziert funktionierenden Code, die Tests laufen durch, der Linter ist sauber. Sie mergen. Drei Wochen später importiert ein Domain-Objekt direkt aus dem Infrastructure Layer. Ein Payment-Handler macht Datenbankaufrufe, die er nicht kennen sollte. Eine Modulgrenze, an der Ihr Team sechs Monate gearbeitet hat, hat ein stilles Loch. Kein einzelner Commit war offensichtlich falsch — der kumulative Drift ist das Problem.

Das ist der Failure Mode, den bessere Prompts nicht beheben. Die KI hat keine Erinnerung an die Architekturentscheidungen vom letzten Quartal. Sie hat keine Möglichkeit zu wissen, dass "sauberer Code" in Ihrer Codebase etwas Spezifisches bedeutet: hexagonale Architektur, strikte Domain-Isolation, keine Nullable Types. Sie optimiert für die unmittelbare Aufgabe, nicht für das langfristige System. Die Lösung ist kein besserer Prompt — es ist ein besserer Workflow.

Was Superpowers eigentlich ist

Superpowers ist ein Open-Source Claude Code Plugin, entwickelt von Jesse Vincent und dem Team bei Prime Radiant, seit Januar 2026 im offiziellen Anthropic Plugin Marketplace verfügbar. Die Installation dauert einen Befehl:

/plugin install superpowers@claude-plugins-official

Nach einem Neustart von Claude Code sieht man den Session-Start-Hook:

<session-start-hook>
You have Superpowers. RIGHT NOW, go read:
@~/.claude/plugins/cache/Superpowers/skills/getting-started/SKILL.md
</session-start-hook>

Ab diesem Punkt verfügt Claude über eine Reihe von Skills: strukturierte Markdown-Dateien, die definieren, wie bestimmte Aufgaben angegangen werden sollen. Das sind keine Vorschläge — wenn ein Skill für das existiert, was man tut, muss Claude ihn verwenden. Skills werden in das Context Window geladen, wenn sie relevant werden: ein TDD-Skill wird injiziert, wenn die Implementierung beginnt, ein Code-Review-Skill feuert zwischen Tasks, ein Debugging-Skill aktiviert sich, wenn ein Fehler auftritt. Jeder Skill trägt nicht nur Anweisungen, sondern auch Pre- und Post-Conditions, die erfüllt sein müssen, bevor der Agent weitermachen kann. Der Kernworkflow, den sie erzwingen, lautet: Brainstorm → Plan → Implement — und Spec-Driven Development ist das, was diese Reihenfolge stabil hält.

Die Spec-Schicht: Drei Typen, drei Templates

Nicht jede Aufgabe ist gleich. Ein neues Feature, eine Bug-Untersuchung und ein Dependency-Upgrade sind grundlegend verschiedene Arten von Arbeit mit unterschiedlichen Unbekannten, unterschiedlichen Risiken und unterschiedlichen Definitionen von "fertig". Sie gleich zu behandeln ist ein Fehler, den die meisten Teams machen — die Lösung liegt darin, auf der Spec-Ebene zu differenzieren. Ein sauberes Setup sieht so aus:

docs/
└── specs/
    ├── README.md          <- Workflow-Dokumentation
    ├── _templates/
    │   ├── feature.md
    │   ├── bugfix.md
    │   └── chore.md
    ├── features/
    ├── bugfixes/
    └── chores/

Die README.md dokumentiert, was wohin gehört und wie der Workflow läuft. Diese Datei wird in CLAUDE.md referenziert, was bedeutet, dass Claude sie zu Beginn jeder Session liest. Der Agent kennt die Struktur, bevor er irgendetwas anfasst.

Feature Specs

Features sind neues Verhalten. Das primäre Risiko ist, das Falsche zu bauen oder zu viel zu bauen. Das Spec-Template spiegelt das wider:

# Feature: [Name]

## Problem
Was gelöst wird, für wen und warum jetzt.

## In Scope
- Konkrete Liste dessen, was dieses Feature liefert

## Out of Scope
- Explizite Liste dessen, was dieses Feature NICHT liefert

## Architecture Constraints
- Welche Module betroffen sind
- Welche Grenzen nicht überschritten werden dürfen
- Performance-Schwellenwerte
- Sicherheitsanforderungen

## Success Criteria
- Messbare Ergebnisse, die bestätigen, dass das Feature funktioniert

## Open Questions
- Entscheidungen, die vor dem Implementierungsstart geklärt werden müssen

## Milestones / Tasks
- Werden aufgeschlüsselt, sobald Open Questions gelöst sind

Der "Out of Scope"-Abschnitt ist nicht optional. Ein KI-Agent wird gerne in angrenzende Funktionalität abdriften, wenn man nicht explizit angibt, was nicht enthalten ist. Das Aufschreiben erzwingt dieses Gespräch während des Brainstormings, bevor Code existiert.

Bugfix Specs

Bugs sind anders. Das primäre Risiko ist nicht der Scope: es ist, das Symptom zu beheben ohne die Ursache zu verstehen, oder eine Regression einzuführen während man das ursprüngliche Problem behebt. Das Template spiegelt das wider:

# Bugfix: [Name]

## Problem Description
Was kaputt ist, was das beobachtete Verhalten ist, was das erwartete Verhalten ist.

## Root Cause
Bekannte Ursache oder Hypothese, die verifiziert werden muss.

## Affected Components
Welche Module, Services oder Layer betroffen sind.

## Reproduction Steps
Genaue Schritte, um das Problem konsistent zu reproduzieren.

## Fix Approach
Wie der Fix implementiert wird und warum dieser Ansatz gegenüber Alternativen.

## Regression Tests
Welche Tests hinzugefügt oder aktualisiert werden müssen.

## Verification
Wie bestätigt wird, dass der Fix in der Zielumgebung funktioniert.

Das Root-Cause-Feld ist das wichtigste. Ein Agent ohne Hypothese wird Änderungen vornehmen und schauen, ob das Symptom verschwindet. Das ist kein Debugging, das ist Raten. Eine Root-Cause-Hypothese vor der Implementierung zu fordern erzwingt echte Analyse zuerst. Diese eine Einschränkung eliminiert eine große Klasse von "behoben, aber dafür etwas anderes kaputt gemacht" Ergebnissen.

Chore Specs

Chores sind Wartungsarbeiten: Dependency-Upgrades, Refactoring, CI-Änderungen, Tooling-Verbesserungen. Das Risiko ist Scope Creep in die andere Richtung, wo "diese Library aktualisieren" zu "und ich habe nebenbei drei Module refaktoriert" wird.

# Chore: [Name]

## Motivation
Warum das jetzt passieren muss und nicht später.

## Scope
Was genau geändert wird.

## Out of Scope
Was nicht geändert wird, auch wenn es verwandt erscheint.

## Approach
Wie die Arbeit durchgeführt wird.

## Definition of Done
Spezifische, verifizierbare Kriterien. Nicht "fühlt sich sauber an": tatsächlich prüfbare Bedingungen.

Das Definition-of-Done-Feld ist das, was eine Chore von einer offenen Refactoring-Session unterscheidet. Der Agent weiß, wann er aufhören soll, und wichtiger: er weiß, dass Aufhören das korrekte Verhalten ist.

Specs und Superpowers verbinden

Die Spec-Dateien leben nicht nur in docs/specs/ — sie sind der Input für den Superpowers-Workflow. Wenn eine neue Claude Code Session startet, teilt CLAUDE.md dem Agenten mit, wo Specs liegen, wie sie strukturiert sind und was jeder Typ bedeutet. Die specs/README.md trägt die Workflow-Dokumentation. Dieser Kontext wird geladen, bevor eine Aufgabe beginnt. Für ein neues Feature öffnet Claude _templates/feature.md, arbeitet die Fragen durch, die das Template fordert, und füllt die Spec gemeinsam mit Ihnen aus — nichts geht weiter, bis die Spec vollständig ist und die Open Questions geklärt sind. Bei einem Bug-Report ist die dokumentierte Root-Cause-Hypothese das Gate. Bei einer Chore wird die Definition of Done von Anfang an festgelegt.

Sobald die Spec fertig ist, erstellt der Agent einen Branch bevor irgendetwas anderes passiert. Der Branch-Name leitet sich vom Spec-Typ ab: feature/, bugfix/ oder chore/ als Prefix, gefolgt von einer normalisierten Version des Spec-Titels — automatisch, bevor der Plan existiert, damit Arbeit nie auf dem falschen Branch beginnt. Der Planning-Skill unterteilt die Spec dann in Tasks von zwei bis fünf Minuten mit genauen Dateipfaden und Verifikationsschritten, der fertige Plan wird sofort committed. Von dort bekommt jeder abgeschlossene Implementierungs-Task seinen eigenen Commit, mit einer Nachricht die den Task referenziert — das Ergebnis ist eine Git-Historie, die als Erzählung lesbar ist. Der Review-Skill prüft jeden Task nicht gegen allgemeine Best Practices, sondern gegen diese spezifische Spec: macht dieser Code was die Feature-Spec sagt, behebt dieser Fix die dokumentierte Root Cause, bleibt diese Chore innerhalb des definierten Scopes?

TDD-Enforcement: Keine Präferenz, eine Einschränkung

Der Superpowers TDD-Skill erzwingt den Red/Green/Refactor-Zyklus als harte Einschränkung.

RED: Ein fehlschlagender Test existiert. Der Agent implementiert nur das, was die Fehlermeldung fordert: den minimalen Code, um genau diesen Test zum Laufen zu bringen. Nicht die saubere Version, nicht die erweiterbare Version — das Minimum. Wenn der Agent Implementierungscode schreibt bevor ein Test existiert, weist der Skill ihn an, diesen Code zu löschen und neu anzufangen. Keine Ausnahmen.

GREEN: Der Test läuft durch, Lint ist sauber und Types sind valide. Alle drei. Der Agent kann GREEN nicht deklarieren, bis er den tatsächlichen Test-Runner-Output als Beweis vorlegt. Eine Behauptung reicht nicht: der wörtliche Output muss vorhanden sein.

REFACTOR: Code wird verbessert, Verhalten bleibt unverändert. Tests müssen durchgehend grün bleiben.

Für Backend-Systeme mit echter Business-Logik hat das konkrete Bedeutung. Eine Payment-Berechnung, die meistens stimmt, stimmt nicht. Eine Sicherheitsgrenze, die wahrscheinlich durchgesetzt wird, wird nicht durchgesetzt. Das TDD-Enforcement behandelt Korrektheit als binär, weil sie in Produktion binär ist.

Die Spec-Verbindung macht TDD präziser als üblich: Tests werden gegen die Acceptance Criteria in der Spec geschrieben, nicht gegen die Implementierung. Ein Test, der durchläuft, aber nicht verifiziert, was die Spec fordert, ist ein Test, der das Falsche prüft.

Architecture Constraints gehören in die Spec, nicht in den Prompt

Eines der hartnäckigen Probleme bei KI-generiertem Code ist Architektur-Drift. Der Agent kennt die Modulgrenzen nicht, wenn man sie ihm nicht mitteilt — und sie im Prompt mitzuteilen bedeutet, sie in der nächsten Session erneut mitzuteilen.

Der Architecture-Constraints-Abschnitt der Feature-Spec ändert das. Wenn Constraints in der Spec dokumentiert und als Teil des Workflows geladen werden, sind sie für die gesamte Implementierung aktiv. Der Review-Skill prüft gegen sie. Der Plan respektiert sie. Sie driften nicht, weil die Spec Drift verhindert.

Für eine PHP-Codebase mit strikter Domain- und Infrastructure-Trennung kommen die Constraints in die Spec:

## Architecture Constraints
- PaymentGateway Interface muss für alle externen Provider-Aufrufe verwendet werden
- Keine provider-spezifischen Types dürfen außerhalb des Payment-Moduls exponiert werden
- Retry-Logik gehört in den Gateway Layer, nicht in den Application Layer
- Alle Währungswerte sind Integers (Cent), niemals Floats

Claude liest das, bevor es den ersten Test schreibt. Das Review prüft nach Verletzungen nach jedem Task.

Bei Legacy-Modernisierungsarbeit, wo Architektur-Intent oft undokumentiert ist, ist das Aufschreiben dieser Constraints während der Brainstorming-Phase unabhängig vom KI-Workflow wertvoll. Es zwingt dazu zu artikulieren, was man schützen will, bevor man anfängt, Dinge zu ändern.

Die Grenzen, die man kennen sollte

Superpowers ist kein universeller Fix. Environment-Debugging liegt außerhalb seines Scopes — plattformspezifische Probleme, Unterschiede zwischen CI- und lokaler Umgebung, Infrastrukturprobleme erfordern ein Verlassen des Workflows, weil der strukturierte Ansatz nicht hilft, wenn das Problem kein Coding-Problem ist. Schlechte Specs produzieren schlechte Implementierungen: die Brainstorming-Phase ist der Ort mit dem größten Hebel, eine gehetzte Spec mit vagen Success Criteria wird eine Implementierung produzieren, die technisch korrekt relativ zur Spec ist, aber falsch relativ zu dem, was man eigentlich brauchte — der Workflow macht das Problem organisierter, er macht die falsche Entscheidung nicht richtig. Custom-Architekturregeln müssen kodiert werden: spezifische Modulgrenzen, Namenskonventionen und Error-Handling-Contracts gehören in persönliche Skills unter ~/.config/superpowers/skills/ oder in die Architecture-Constraints-Abschnitte der Specs. Superpowers enthält einen Skill-Authoring-Skill, der dabei hilft.

Getting Started

Plugin installieren:

/plugin install superpowers@claude-plugins-official

Spec-Struktur im Repository anlegen:

docs/specs/_templates/feature.md
docs/specs/_templates/bugfix.md
docs/specs/_templates/chore.md
docs/specs/README.md

Workflow-Dokumentation in specs/README.md schreiben — welche Art von Arbeit wohin gehört, was jedes Template erfordert, wie der Review-Prozess aussieht — und diese Datei in CLAUDE.md referenzieren, damit sie zu Beginn jeder Session geladen wird. Dann eine neue Claude Code Session starten, beschreiben was gebaut werden soll, und der Brainstorming-Skill aktiviert sich automatisch. Claude öffnet das passende Template und arbeitet die Fragen durch, bevor eine einzige Zeile Code geschrieben wird. Die vollständige Sequenz von dort ist vorhersehbar und wiederholbar:

1. Spec wird fertiggestellt und im richtigen Unterverzeichnis gespeichert
2. Branch wird mit dem korrekten Prefix (feature/, bugfix/, chore/) aus dem Spec-Namen erstellt
3. Plan wird geschrieben und committed
4. Jeder Implementierungs-Task wird einzeln ausgeführt und committed

Die Disziplin, die erfahrene Entwickler natürlich anwenden — Grenzen kennen, Tests zuerst schreiben, in kohärenten Schritten committen, gegen Anforderungen statt gegen Konventionen reviewen — wird zum Standardverhalten des Agenten. Nicht weil man es geprompted hat, sondern weil der Workflow es erfordert.