Von PRD zu Produktion: Mein Spec-Driven Claude Code Workflow

Jedes Projekt, das ich mit Claude Code baue, folgt demselben Workflow. Er ist nicht fancy. Er ist nicht revolutionär. Aber er funktioniert konsistent, und Konsistenz ist das, was zählt, wenn man Software für Kunden liefert.

Hier ist der exakte Prozess, den ich verwende, von den initialen Anforderungen bis zum deployt Code.

Phase 1: Discovery

Bevor ich eine einzige Zeile Spec schreibe, muss ich verstehen, was wir bauen und warum.

Das Discovery-Gespräch

Jedes Projekt beginnt mit einer Unterhaltung. Ich frage:

• Welches Problem lösen Sie?
• Wer wird diese Software nutzen?
• Wie sieht Erfolg aus?
• Was sind Ihre Einschränkungen (Timeline, Budget, bestehende Systeme)?
• Was haben Sie vorher versucht?

Ich mache detaillierte Notizen. Nicht weil ich sie Claude Code wortwörtlich gebe, sondern weil ich Geschäftssprache in technische Anforderungen übersetzen muss.

Das Ergebnis

Am Ende der Discovery habe ich:

1. Ein klares Problem-Statement
2. Benutzer-Personas (wer nutzt das und wie)
3. Erfolgskriterien (messbare Ergebnisse)
4. Technische Einschränkungen (muss mit X integrieren, muss auf Y laufen)
5. Ausserhalb-des-Umfangs-Punkte (genauso wichtig wie innerhalb)

Phase 2: Spec-Schreiben

Hier passiert die echte Arbeit. Die Spec ist der Vertrag zwischen mir und der KI.

Mein Spec-Template

Jede Feature-Spec folgt dieser Struktur:

# Feature: [Name]

## Übersicht
[2-3 Sätze, die beschreiben, was dieses Feature macht und warum es wichtig ist]

## User Stories
- Als [Benutzertyp] möchte ich [Aktion], damit [Nutzen]
- Als [Benutzertyp] möchte ich [Aktion], damit [Nutzen]

## Anforderungen

### Funktionale Anforderungen
- [ ] FA-001: [Spezifische, testbare Anforderung]
- [ ] FA-002: [Spezifische, testbare Anforderung]
...

### Nicht-funktionale Anforderungen
- [ ] NFA-001: Antwortzeit < 200ms für alle API-Aufrufe
- [ ] NFA-002: Unterstütze 100 gleichzeitige Benutzer
...

## Datenmodell
[Schema-Definitionen, Beziehungen, Constraints]

## API Endpoints
### [METHOD] [Pfad]
**Beschreibung**: [Was dieser Endpoint macht]
**Request**: [Body-Schema]
**Response**: [Erfolgs- und Fehler-Schemas]
**Autorisierung**: [Wer darf das aufrufen]

## Geschäftsregeln
- GR-001: [Regel-Beschreibung]
- GR-002: [Regel-Beschreibung]

## Grenzfälle
- GF-001: [Was passiert wenn X]
- GF-002: [Was passiert wenn Y]

## Ausserhalb des Umfangs
- [Dinge, die explizit NICHT enthalten sind]

## Testplan
- Unit-Tests für: [Liste]
- Integrationstests für: [Liste]
- E2E-Tests für: [Liste]

Gute Anforderungen schreiben

Jede Anforderung muss sein:

Spezifisch: Nicht "Fehler behandeln" sondern "HTTP 400 mit Fehlermeldung zurückgeben, wenn E-Mail-Format ungültig ist"

Testbar: Ich sollte einen Test schreiben können, der besteht, wenn diese Anforderung erfüllt ist

Unabhängig: Wo möglich sollten Anforderungen nicht voneinander abhängen

Atomar: Eine Anforderung = eine Sache. Wenn sie "und" enthält, sind es wahrscheinlich zwei Anforderungen.

Beispiel: Authentifizierungs-Spec

Hier ist ein echtes Beispiel aus einem kürzlichen Projekt:

# Feature: Benutzer-Authentifizierung

## Übersicht
Benutzer können sich registrieren, einloggen und ihre Sessions verwalten. Authentifizierung verwendet JWT-Tokens mit Refresh-Token-Rotation.

## User Stories
- Als neuer Benutzer möchte ich mich mit E-Mail/Passwort registrieren, damit ich auf das System zugreifen kann
- Als registrierter Benutzer möchte ich mich einloggen, damit ich auf meine Daten zugreifen kann
- Als eingeloggter Benutzer möchte ich mich ausloggen, damit meine Session beendet wird

## Anforderungen

### Registrierung
- [ ] FA-001: Akzeptiere POST /api/auth/register mit {email, password, name}
- [ ] FA-002: Validiere E-Mail-Format (RFC 5322)
- [ ] FA-003: Fordere Passwort mindestens 8 Zeichen, 1 Grossbuchstabe, 1 Zahl
- [ ] FA-004: Hashe Passwort mit bcrypt (Kostenfaktor 12)
- [ ] FA-005: Prüfe E-Mail-Eindeutigkeit vor Benutzererstellung
- [ ] FA-006: Gib 201 mit {userId, email} bei Erfolg zurück
- [ ] FA-007: Gib 400 mit Validierungsfehlern bei ungültiger Eingabe zurück
- [ ] FA-008: Gib 409 zurück wenn E-Mail bereits existiert

### Login
- [ ] FA-009: Akzeptiere POST /api/auth/login mit {email, password}
- [ ] FA-010: Verifiziere Passwort gegen gespeicherten Hash
- [ ] FA-011: Generiere JWT Access Token (15min Ablauf)
- [ ] FA-012: Generiere Refresh Token (7 Tage Ablauf)
- [ ] FA-013: Speichere Refresh Token Hash in Datenbank
- [ ] FA-014: Gib 200 mit {accessToken, refreshToken, expiresAt} zurück
- [ ] FA-015: Gib 401 für ungültige Anmeldedaten zurück (gleiche Meldung für falsche E-Mail/Passwort)
- [ ] FA-016: Rate Limit: 5 Versuche pro E-Mail pro 15 Minuten

Diese Spec ist 3 Seiten lang für ein einfaches Auth-System. Das ist beabsichtigt. Jede Frage, die Claude Code haben könnte, ist in der Spec beantwortet.

Phase 3: Spec-Validierung

Bevor ich die Spec an Claude Code gebe, validiere ich sie:

Vollständigkeitsprüfung

• Hat jede Anforderung Akzeptanzkriterien?
• Sind alle Grenzfälle abgedeckt?
• Sind Fehlerbedingungen spezifiziert?
• Ist der Testplan ausreichend?

Konsistenzprüfung

• Widersprechen sich Anforderungen gegenseitig?
• Sind Datentypen über Endpoints hinweg konsistent?
• Stimmen Geschäftsregeln mit Anforderungen überein?

Technische Prüfung

• Ist das tatsächlich implementierbar?
• Fehlen Abhängigkeiten?
• Sind Performance-Anforderungen realistisch?

Kunden-Review

Bei Kundenprojekten teile ich die Spec vor der Implementierung. "Das ist, was ich verstehe, dass Sie brauchen. Ist das korrekt?"

Besser Missverständnisse jetzt auffangen als nachdem Code geschrieben ist.

Phase 4: Implementierung mit Claude Code

Jetzt der spassige Teil. Mit einer validierten Spec ist die Implementierung fast mechanisch.

Initiales Setup

Ich erstelle die Projektstruktur und konfiguriere Claude Code:

# Projekt erstellen
mkdir projekt-name && cd projekt-name
git init

# Claude Code mit der Spec einrichten
mkdir docs
cp ~/specs/feature-spec.md docs/spec.md

# CLAUDE.md mit Projektkontext erstellen
cat > CLAUDE.md << 'EOF'
# Projekt: [Name]

## Tech Stack
- Node.js 20
- TypeScript 5.x
- PostgreSQL 16
- Express.js

## Entwicklungs-Befehle
- npm run dev: Development-Server starten
- npm run test: Testsuite ausführen
- npm run lint: Code-Stil prüfen

## Konventionen
- async/await verwenden, keine Callbacks
- Alle Funktionen müssen JSDoc-Kommentare haben
- Fehler-Responses verwenden RFC 7807 Format
EOF

Der Implementierungs-Loop

Ich verwende einen modifizierten Ralph Loop für die Implementierung:

claude --print "
Lies docs/spec.md für die Feature-Spezifikation.

Finde die erste nicht angekreuzte Anforderung (- [ ]).

1. Verstehe, was diese Anforderung braucht
2. Prüfe, ob Abhängigkeiten zuerst implementiert werden müssen
3. Lies bestehenden Code in den relevanten Dateien
4. Implementiere die Anforderung
5. Schreibe Tests für die Anforderung
6. Führe Tests mit 'npm test' aus
7. Wenn Tests bestehen:
   - Markiere die Anforderung als erledigt (- [x])
   - Committe mit Nachricht, die die Anforderungs-ID referenziert
8. Wenn Tests fehlschlagen:
   - Behebe das Problem
   - Führe Tests erneut aus
   - Markiere nur als erledigt wenn Tests bestehen

Sei gründlich. Eine Anforderung nach der anderen.
"

Fortschritt überwachen

Ich schaue periodisch nach:

• Werden Anforderungen in sinnvoller Reihenfolge erledigt?
• Ist die Code-Qualität akzeptabel?
• Testen die Tests wirklich, was sie behaupten?
• Steckt die KI irgendwo fest?

Menschliche Interventionspunkte

Einige Dinge brauchen immer menschliche Aufmerksamkeit:

• Datenbank-Migrationen (ich prüfe vor dem Ausführen)
• Externe API-Integrationen (brauchen echte Credentials/Config)
• Sicherheitsrelevanter Code (Authentifizierung, Autorisierung)
• Performance-Optimierung (braucht echte Datenmuster)

Phase 5: Review und Verfeinerung

Sobald alle Anforderungen als erledigt markiert sind, ist die Arbeit nicht getan.

Code Review

Ich prüfe allen generierten Code auf:

• Sicherheitsprobleme (Injection, Auth-Bypass, etc.)
• Performance-Probleme (N+1 Queries, fehlende Indexes)
• Wartbarkeit (Benennung, Struktur, Dokumentation)
• Testabdeckung (werden Grenzfälle wirklich getestet?)

Integrationstests

Einzelne Anforderungen, die bestehen, bedeuten nicht, dass das System funktioniert. Ich führe aus:

• Vollständige Benutzer-Flow-Tests
• Lasttests (wenn Performance-Anforderungen existieren)
• Sicherheits-Scanning

Kunden-Demo

Bei Kundenprojekten demonstriere ich das Feature bevor ich es als erledigt markiere. "Hier ist, was wir gebaut haben. Entspricht es Ihren Erwartungen?"

Phase 6: Dokumentation und Übergabe

Die letzte Phase wird oft übersehen, ist aber kritisch.

Dokumentation aktualisieren

• API-Dokumentation (wo möglich aus Code auto-generiert)
• Benutzerhandbücher (falls zutreffend)
• Deployment-Anweisungen
• Bekannte Einschränkungen

Runbook erstellen

Für Operations-Teams:

• Wie deployen
• Wie überwachen
• Wie häufige Probleme beheben
• Wie Rollback durchführen

Die vollständige Timeline

Für ein mittelkomplexes Feature (wie das Auth-Beispiel):

Traditioneller Ansatz für dasselbe Feature? 40-80 Stunden.

Die Zeitersparnis kommt von:

1. Spec-Schreiben fängt Probleme vor dem Coding ab (kein Rework)
2. KI übernimmt Implementierung (schnell, konsistent)
3. Klare Anforderungen bedeuten weniger Iterationen

Häufige Fehler zu vermeiden

Discovery überspringen

"Bau einfach ein Login-System" → drei Iterationen Rework, weil Anforderungen nicht klar waren.

Vage Specs

"Fehler angemessen behandeln" → KI trifft vernünftig klingende Entscheidungen, die nicht dem entsprechen, was Sie wollten.

Review überspringen

Generierter Code, der "funktioniert", aber Sicherheitslücken, Performance-Probleme oder unwartbare Struktur hat.

Dokumentation unterschätzen

"Ich werde mich erinnern, wie das funktioniert" → werden Sie nicht, und die nächste Person auch nicht.

Warum das funktioniert

Dieser Workflow funktioniert, weil er KI-Stärken ausnutzt und gleichzeitig KI-Schwächen kompensiert.

KI-Stärken:

• Schnelle Implementierung gut definierter Anforderungen
• Konsistente Code-Qualität
• Gründliche Testabdeckung
• Wird bei repetitiven Aufgaben nicht müde

KI-Schwächen:

• Verstehen vager Anforderungen
• Geschäftliche Urteilsentscheidungen treffen
• Grenzfälle antizipieren, die Sie nicht erwähnt haben
• Wissen, wie "gut" aussieht ohne Beispiele

Die Spec überbrückt die Lücke. Sie übersetzt menschliche Absicht in KI-ausführbare Anweisungen.

---

Möchten Sie diesen Workflow in Aktion an Ihrem Projekt sehen? Buchen Sie ein kostenloses Gespräch und lassen Sie uns besprechen, wie Spec-Driven Development für Sie funktionieren kann.