Spec-Driven Development: Warum Ihre KI-Agenten einen Vertrag brauchen

Hier ist ein Muster, das ich ständig sehe: Jemand startet Claude Code, tippt "baue mir ein Authentifizierungssystem" und bekommt... irgendetwas. Vielleicht funktioniert es. Vielleicht nicht. So oder so ist es wahrscheinlich nicht das, was sie tatsächlich brauchten.

Das Problem ist nicht die KI. Das Problem ist, dass niemand definiert hat, was "Authentifizierungssystem" bedeutet.

Hier kommt Spec-Driven Development (SDD): die Praxis, Spezifikationen vor dem Code zu schreiben. Es ist keine neue Idee—formale Specs existieren seit Jahrzehnten. Aber mit KI-Agenten sind Specs nicht nur Dokumentation. Sie sind der Vertrag, der der KI genau sagt, was sie bauen soll.

Das Halluzinations-Problem

KI-Modelle halluzinieren. Nicht manchmal. Immer, in gewissem Masse. Sie füllen Lücken mit plausibel klingenden Details, die korrekt sein können oder auch nicht.

Wenn Sie Claude Code bitten, "Benutzerauthentifizierung hinzuzufügen", muss es Hunderte von Entscheidungen treffen:

Welche Felder hat ein Benutzer? E-Mail? Benutzername? Beides?
Wie werden Passwörter gespeichert? bcrypt? argon2? scrypt?
Was ist der Session-Mechanismus? JWT? Server-seitige Sessions?
Wie lange dauern Sessions? 1 Stunde? 24 Stunden? Für immer?
Was passiert, wenn eine Session abläuft?
Gibt es Rollen? Berechtigungen? Admin-Benutzer?

Ohne eine Spec rät die KI. Manchmal rät sie gut. Manchmal nicht. Und Sie werden nicht wissen welches, bis Sie durch den generierten Code gegraben haben.

Was ist Spec-Driven Development?

SDD dreht den traditionellen Ablauf um. Anstatt:

Code zuerst → Debuggen → Dokumentieren (vielleicht) → Ausliefern

Machen Sie:

Spec zuerst → Spec validieren → Code generieren → Gegen Spec verifizieren

Eine Spec ist eine detaillierte Beschreibung dessen, was die Software tun soll. Nicht wie—das ist Implementierung. Eine Spec definiert:

Eingaben: Welche Daten kommen rein, in welchem Format
Ausgaben: Welche Daten kommen raus, in welchem Format
Verhalten: Welche Transformationen passieren
Grenzfälle: Was passiert, wenn etwas schief geht
Einschränkungen: Performance-Anforderungen, Sicherheitsregeln, etc.

Warum Specs für KI-Agenten wichtig sind

Specs lösen das Halluzinations-Problem, indem sie der KI eine Ground Truth zum Abgleichen geben.

Klare Anweisungen

Vergleichen Sie diese Prompts:

Vage: "Füge einen Login-Endpoint hinzu"

Spec-gesteuert:

## POST /api/auth/login

### Request
- Body: { email: string, password: string }
- Beide Felder erforderlich
- E-Mail muss gültiges Format haben

### Response (Erfolg - 200)
- Body: { token: string, expiresAt: ISO8601 }
- Token ist JWT mit Benutzer-ID und Rollen
- Läuft nach 24 Stunden ab

### Response (Fehler - 401)
- Body: { error: "Invalid credentials" }
- Gleiche Antwort für falsche E-Mail oder falsches Passwort (Sicherheit)

### Verhalten
- Rate Limit: 5 Versuche pro E-Mail pro 15 Minuten
- Konto nach 10 fehlgeschlagenen Versuchen sperren
- Alle Versuche (Erfolg und Fehler) für Audit loggen

Die Spec lässt nichts zur Interpretation. Die KI weiss genau, was sie bauen soll.

Testbare Kriterien

Specs definieren, wann etwas "fertig" ist. Jede Anforderung in der Spec wird zu einem Test:

Akzeptiert der Endpoint POST-Requests?
Erfordert er sowohl E-Mail als auch Passwort?
Gibt er bei Erfolg ein JWT zurück?
Begrenzt er die Rate nach 5 Versuchen?

Die KI kann diese Tests ausführen und ihre eigene Arbeit verifizieren. Kein "sieht richtig aus, denke ich?" mehr.

Iterations-Anker

Wenn die erste Implementierung nicht funktioniert, sagt Ihnen die Spec warum. Sie debuggen nicht "ist das, was ich wollte?" Sie debuggen "entspricht das der Spec?"

Das ist besonders mächtig mit Ralph Loops. Jede Iteration startet frisch, liest die Spec und versucht es erneut. Die Spec ist die Konstante; die Implementierung ist die Variable.

Wie man Specs schreibt, die KI-Agenten ausführen können

Nicht alle Specs sind gleich. Hier ist, was eine Spec KI-freundlich macht.

Seien Sie explizit bei Datenstrukturen

Schlecht:

Der Endpoint gibt Benutzerinformationen zurück.

Gut:

### Response Body
{
  "user": {
    "id": "uuid",
    "email": "string",
    "displayName": "string | null",
    "createdAt": "ISO8601",
    "roles": ["admin" | "user"]
  }
}

Definieren Sie Grenzfälle

Schlecht:

Behandle Fehler angemessen.

Gut:

### Fehler-Responses
- 400 Bad Request: Fehlende Pflichtfelder, ungültiges E-Mail-Format
- 401 Unauthorized: Ungültige Anmeldedaten
- 403 Forbidden: Konto gesperrt
- 429 Too Many Requests: Rate Limit überschritten
- 500 Internal Server Error: Datenbankverbindung fehlgeschlagen

Jede Fehler-Response enthält: { "error": "message", "code": "ERROR_CODE" }

Fügen Sie Beispiele hinzu

### Beispiel: Erfolgreicher Login

Request:
POST /api/auth/login
Content-Type: application/json
{
  "email": "user@example.com",
  "password": "richtiges-passwort"
}

Response: 200 OK
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": "2026-01-19T12:00:00Z"
}

### Beispiel: Fehlgeschlagener Login

Request:
POST /api/auth/login
Content-Type: application/json
{
  "email": "user@example.com",
  "password": "falsches-passwort"
}

Response: 401 Unauthorized
{
  "error": "Invalid credentials",
  "code": "AUTH_INVALID_CREDENTIALS"
}

Trennen Sie Interface von Implementierung

Ihre Spec sollte das Was definieren, nicht das Wie. Schreiben Sie nicht:

Verwende bcrypt mit 12 Runden zum Hashen von Passwörtern.
Speichere Sessions in Redis.

Schreiben Sie stattdessen:

- Passwörter müssen sicher gehasht werden (nicht Klartext, nicht MD5)
- Sessions müssen Server-Neustarts überleben

Lassen Sie die KI die Implementierung wählen. Sie können immer überschreiben, wenn Sie Präferenzen haben, aber die Spec fokussiert auf Anforderungen.

Tools für Spec-Driven Development

GitHub Spec Kit

GitHub hat spec-kit als Open-Source-Toolkit für SDD veröffentlicht. Es bietet:

Templates für gängige Spec-Typen (APIs, Komponenten, Features)
Validierungs-Tools zur Prüfung der Spec-Vollständigkeit
Integration mit CI/CD-Pipelines

cc-sdd

cc-sdd bringt Kiro-artige Spec-Befehle zu Claude Code. Sie können Specs in einem strukturierten Format definieren und Claude Code parsen und ausführen lassen.

claude-code-spec-workflow

claude-code-spec-workflow automatisiert den Spec → Implementieren → Verifizieren-Zyklus. Es ist speziell für iterative Entwicklung mit Claude Code konzipiert.

SDD in der Praxis: Ein echter Workflow

So verwende ich SDD mit Claude Code.

Schritt 1: Discovery

Bevor Sie irgendeine Spec schreiben, verstehen Sie das Problem. Sprechen Sie mit Stakeholdern, Benutzern, wer auch immer weiss, was gebaut werden muss. Machen Sie Notizen.

Schritt 2: Spec entwerfen

Schreiben Sie die Spec in Markdown. Ich verwende ein Template:

# Feature: [Name]

## Übersicht
[2-3 Sätze, die das Feature beschreiben]

## Anforderungen
- [ ] [Anforderung 1]
- [ ] [Anforderung 2]
...

## API Endpoints (falls zutreffend)
### [METHOD] [Pfad]
...

## Datenmodelle (falls zutreffend)
...

## Geschäftsregeln
...

## Grenzfälle
...

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

Schritt 3: Spec validieren

Bevor Sie es Claude Code geben, prüfen Sie:

Ist jede Anforderung testbar?
Gibt es Mehrdeutigkeiten, die eine KI falsch interpretieren könnte?
Sind Grenzfälle abgedeckt?
Ist irgendetwas unmöglich oder widersprüchlich?

Schritt 4: Mit Claude Code ausführen

claude --print "
Lies die Spec unter docs/specs/auth-feature.md.

Implementiere das Feature genau wie spezifiziert.
Schreibe nach jeder Anforderung einen Test, der sie verifiziert.
Markiere die Anforderung als erledigt in der Spec, wenn der Test besteht.
"

Schritt 5: Verifizieren und iterieren

Führen Sie die Tests aus. Wenn etwas fehlschlägt, prüfen Sie:

Ist die Spec klar? Wenn nicht, klären Sie sie.
Ist die Implementierung falsch? Wenn ja, lassen Sie Claude Code sie reparieren.
Ist der Test falsch? Wenn ja, reparieren Sie den Test.

Wiederholen Sie, bis alle Anforderungen bestehen.

Wenn Specs scheitern

Specs sind keine Magie. Sie können auf mehrere Arten scheitern:

Unvollständige Specs

Sie haben eine Anforderung vergessen. Die KI hat genau gebaut, was Sie verlangt haben—es ist nur nicht das, was Sie brauchten. Lösung: bessere Discovery, mehr Grenzfall-Denken.

Widersprüchliche Specs

Anforderung A steht im Konflikt mit Anforderung B. Die KI wählt eine (oder schlimmer, versucht beide). Lösung: Specs auf Konsistenz prüfen, bevor Sie implementieren.

Zu starre Specs

Sie haben Implementierungsdetails spezifiziert, die die KI unnötig einschränken. Lösung: auf Ergebnisse fokussieren, nicht auf Mechanismen.

Sich ändernde Anforderungen

Die Spec war richtig, als Sie sie geschrieben haben, aber jetzt haben sich die Anforderungen geändert. Lösung: zuerst die Spec aktualisieren, dann regenerieren.

Das Spec-First-Mindset

SDD ist nicht nur eine Technik. Es ist eine Denkweise.

Altes Denken: "Ich werde es erkennen, wenn ich es sehe" Spec-First-Denken: "Ich werde es definieren, bevor ich es baue"

Diese Disziplin zahlt sich auch jenseits von KI aus. Specs zwingen Sie, klar über das nachzudenken, was Sie bauen. Sie fangen Design-Fehler früh ab. Sie erstellen Dokumentation automatisch. Sie machen Testen unkompliziert.

KI verstärkt nur die Vorteile. Ein menschlicher Entwickler könnte eine vage Anforderung erfolgreich interpretieren. Eine KI definitiv nicht—oder besser gesagt, sie wird es interpretieren, nur nicht so, wie Sie es wollten.

Heute starten

Sie brauchen keine ausgefallenen Tools, um mit SDD zu beginnen. Schnappen Sie sich eine Markdown-Datei und schreiben Sie:

Was macht dieses Feature?
Was sind die Eingaben und Ausgaben?
Was passiert, wenn etwas schief geht?
Wie werde ich wissen, dass es funktioniert?

Das ist eine Spec. Geben Sie sie Claude Code. Sehen Sie, was passiert.

Ich garantiere Ihnen, dass Sie bessere Ergebnisse bekommen als "baue mir ein Authentifizierungssystem."

Bereit, Spec-Driven Development in Ihren Projekten zu implementieren? Buchen Sie ein kostenloses Gespräch und lassen Sie uns besprechen, wie KI-gestützte Entwicklung für Ihr Team strukturiert werden kann.