Spezifikationsgetriebene Entwicklung (SDD)

1. Konzeptüberblick und systemisches Problem

Der häufigste Fehler von Einsteigern im Vibe Coding ist der Ansatz „Prompt-and-Pray“ (einen vagen Prompt in den Chat schreiben und darauf hoffen, dass das Modell die Architektur errät). Wenn die Anfrage lautet: „Implementiere Stripe-Billing für Abonnenten“, wählt das Modell willkürliche Datenbankschemas aus, nutzt veraltete Bibliotheken, ignoriert Webhooks, vergisst die Idempotenz und berücksichtigt keine Edge Cases bei Zahlungsstornierungen. Wenn ein Ingenieur bittet, einen Bug zu beheben, beginnt das Modell hektisch Löcher zu stopfen und verwandelt die Codebasis endgültig in Spaghetti-Code (AI Slop).

Spec-Driven Development (SDD) ist eine ingenieursdisziplinierte Methode, die das Systemdesign vom Prozess der Codegenerierung trennt. Bevor die Codebasis angefasst wird, erstellt man ein formalisiertes Spezifikationsdokument (spec.md oder RFC.md). Dieses Dokument dient als Single Source of Truth und als Vertrag, gegen den der Agent jeden folgenden Schritt ausführt und verifiziert.

2. Architektonische Taxonomie und mentales Modell

Das architektonische Fundament von SDD basiert auf einer klaren Hierarchie von Design-Artefakten:

┌─────────────────────────────────────────────────────────────┐
│             SPEC-DRIVEN DEVELOPMENT ARTIFACT HIERARCHY      │
├─────────────────────────────────────────────────────────────┤
│ 1. Product Context: Проблема користувача та бізнес-мета     │
├─────────────────────────────────────────────────────────────┤
│ 2. Technical Contracts:                                     │
│    • Схеми даних (Drizzle / Prisma schemas, SQL DDL)        │
│    • API Contracts (Zod Schemas, OpenAPI, TypeScript types) │
│    • Invariants & Security Rules (Idempotency, RBAC, Auth)  │
├─────────────────────────────────────────────────────────────┤
│ 3. Atomic Task Checklist (DAG):                             │
│    • Step 1 ➔ Step 2 ➔ Step 3 (Строгий порядок залежностей) │
├─────────────────────────────────────────────────────────────┤
│ 4. Verification Predicates: Машинні критерії готовності     │
└─────────────────────────────────────────────────────────────┘

1. Technische Verträge (Interface-First):
   • Beschreibung der Systeminteraktionen vor der Implementierung der internen Logik. Definition von Request-/Response-Strukturen, Validierungsschemas und Fehlerzuständen.
2. Atomarer Aufgaben-Graph (Task Decomposition DAG):
   • Die Aufgabe wird in eine Sequenz kleiner, unabhängig verifizierbarer Unteraufgaben zerlegt. Jede Unteraufgabe darf maximal 1–3 Dateien modifizieren.
3. Maschinen-verifizierbare Kriterien (Acceptance Predicates):
   • Anstelle des subjektiven „Teste, ob alles funktioniert“, enthält die Spezifikation konkrete Prüfbefehle: „pnpm test auth.test.ts läuft erfolgreich durch, Branch-Coverage > 90%“.
4. Lifecycle-Status-Tracker:
   • Die Spezifikation enthält interaktive Checkboxen ([ ] ➔ [x]), die der Agent nach Ausführung und Verifizierung jedes Schrittes aktualisiert.

3. Technischer Pipeline-Prozess und interne Mechanik

Der Entwicklungszyklus gemäß der SDD-Methodologie:

1. Interview und Synthese der Spezifikation (Interview Phase): Der Ingenieur formuliert die Aufgabe. Das Modell stellt gezielte Fragen zu nicht-trivialen Details: Welches Verhalten ist bei Netzwerkabbruch erwartet? Wie werden Duplikate behandelt? Welche Rate-Limiting-Grenzen gelten?
2. Fixierung der Spezifikation im Repository: Es wird ein Artefakt erstellt (z. B. .specs/004-billing-integration.md), das in das Git-Versionskontrollsystem aufgenommen wird.
3. Menschliches Audit und Freigabe (Spec Approval): Der Ingenieur prüft die vorgeschlagenen Datenschemas und Verträge. Falls das architektonische Entscheidungsmuster Mängel aufweist, werden diese auf Textebene der Spezifikation innerhalb von 2 Minuten korrigiert, was stundenlanges Umschreiben von Code vermeidet.
4. Schrittweises Delegieren an den Agenten (Step-by-Step Execution): Der Agent wird zur Implementierung eines spezifischen Schritts aus der Spezifikation aufgerufen:
   • Der Agent liest den Kontext der Spezifikation.
   • Er schreibt Tests gemäß den Verträgen (TDD).
   • Er implementiert die Funktionalität.
   • Er führt die Tests aus und markiert die Unteraufgabe als erledigt.
5. Finale Verifizierung und Archivierung: Sobald alle Punkte der Spezifikation als erledigt gekennzeichnet sind, wird ein End-to-End-Audit durchgeführt. Die Spezifikation bleibt im Repository als lebende Dokumentation der Feature.

4. Praktische Engineering-Szenarien in Production

01. Entwicklung eines kritischen Zahlungsmoduls mit Idempotenz

Vor dem Schreiben des Codes für die Payment-Gateway-Integration erstellt der Ingenieur eine Spezifikation:

• Fixierung der Struktur der Tabelle idempotency_keys mit den Feldern key, response_payload, status, expires_at.
• Beschreibung des exakten Algorithmus für das Verhalten bei Erhalt eines doppelten Webhooks mit identischer transaction_id.
• Der Agent implementiert das Modul strikt nach Spezifikation; kein Edge Case geht verloren.

02. Parallele Arbeit von Backend- und Frontend-Agenten

Ein Team entwickelt ein neues Analytics-Dashboard:

• Zunächst werden in der Spezifikation Zod-Schemas und TypeScript-Interfaces für alle Charts und Metriken definiert.
• Der Frontend-Agent nutzt diese Schemas, um Komponenten mit Mock-Daten zu rendern.
• Der Backend-Agent implementiert gleichzeitig echte SQL-Queries und API-Routen unter demselben Vertrag.
• Die Integration erfolgt ohne Konflikte aufgrund von Typinkompatibilität.

03. Sichere großskalige Migration eines Legacy-Moduls

Ersetzung einer alten, selbstgeschriebenen Authentifizierung durch Better Auth:

• Die Spezifikation beschreibt die Wahrung der Rückwärtskompatibilität der Sessions in Redis sowie einen schrittweisen Migrationsplan für Passwort-Hashes von bcrypt zu Argon2id.
• Der Agent zerlegt die Migration in 7 isolierte Phasen, die jeweils separat getestet werden.

5. Fallstricke, typische Fehler und Sicherheit

• Paralyse durch Over-Engineering: Eine 20-seitige Spezifikation für eine kleine Einrückungskorrektur oder eine Button-Farbänderung zu schreiben, ist eine sinnlose Zeitverschwendung. Nutzen Sie SDD nur für Aufgaben, die mehr als 2 Module betreffen oder kritische Business-Logik enthalten.
• Desynchronisation von Code und Spezifikation (Spec Rot): Wenn während der Entwicklung Änderungen am Schema nötig sind, korrigieren Ingenieure oft direkt den Code und vergessen, die spec.md zu aktualisieren. Dies verwirrt nachfolgende Agenten, die dann wieder die veraltete Spezifikation lesen.
• Verwendung vager Formulierungen: Sätze wie „das System muss schnell laufen“ oder „Zuverlässigkeit sicherstellen“ sind katastrophal für KI. Die Spezifikation muss mit konkreten Werten operieren: „p99 Response Time < 150ms“, „HTTP 429 zurückgeben bei Überschreitung von 100 rpm“.
• Ignorieren der Versionskontrolle von Spezifikationen: Spezifikationsdateien müssen Teil des Git-Repositories sein, zusammen mit dem Code. Dies ermöglicht die Nachverfolgung der Evolution architektonischer Entscheidungen über die Commit-Historie.