AI-Serie Interview 16: Wie sollte ein gutes Spec Coding aussehen?

Ein gutes Spec Coding (Spezifikationsgetriebene Programmierung) besteht im Kern darin, „vage Ideen“ in „präzise, verifizierbare, ausführbare Verträge“ zu verwandeln. Es ist nicht nur ein Dokument, sondern ein eindeutiges Kommunikationsmittel zwischen Mensch und KI (oder zwischen Menschen). Im Folgenden werde ich aus den vier Dimensionen Inhaltsstruktur der Spezifikation, Schreibprinzipien, Kollaborationsprozess mit KI und Qualitätsverifikation aufzeigen, wie ein gutes Spec aussieht.

1. Standardstruktur eines Spezifikationsdokuments (am Beispiel eines Funktionsmoduls)

Kapitel	Pflichtinhalt	Beispiel
1. Ziel und Umfang	Ein Satz, der beschreibt, was gemacht wird, und klarstellt, was nicht gemacht wird	„Benutzerregistrierungs-API implementieren, ohne E-Mail-Verifikation“
2. Eingabe-/Ausgabe-Vertrag	Datenstruktur, Typ, Pflicht-/optionale Felder, Beispielwerte	`POST /register` Request-Body `{email: string, password: string}`, Antwort `201` oder `400` mit Fehlercode
3. Verhalten und Logik	Geschäftsregeln, Randbedingungen, Zustandsübergänge	„Passwortlänge 8-20 Zeichen, mindestens eine Ziffer; bei bereits vorhandener E-Mail Rückgabe `409`“
4. Fehlerbehandlung	Alle möglichen Ausnahmeszenarien und entsprechende Fehlercodes/-meldungen	„Datenbankverbindungsfehler → Rückgabe `503`, keinen Stacktrace preisgeben“
5. Nicht-funktionale Anforderungen	Leistung (Antwortzeit < 200ms), Sicherheit (parametrisierte Abfragen), Protokollierung, Beobachtbarkeit	„Alle SQL müssen vorkompiliert sein; `email` protokollieren, aber nicht `password`“
6. Testfälle (entscheidend)	Mindestens 3 typische Eingaben + 2 Grenz-/Ausnahmeeingaben, erwartete Ausgabe angeben	Siehe Tabelle unten
7. Abhängigkeiten und Einschränkungen	Welche Bibliotheken, Versionen, Umgebungsvariablen verwendet werden	„Python 3.10+, FastAPI, Umgebungsvariable `DB_URL`“

Testfallbeispiel (im Spec eingebettet)

Szenario	Eingabe	Erwartete Ausgabe
Normale Registrierung	email: `a@b.com`, pwd: `Pass1234`	`201`, Rückgabe `user_id`
Passwort zu kurz	pwd: `Ab1`	`400`, Fehlercode `WEAK_PASSWORD`
E-Mail bereits vorhanden	Gleiche E-Mail	`409`, Fehlercode `EMAIL_EXISTS`

Ein gutes Spec muss zuerst Testfälle schreiben, denn die KI kann daraus direkt Unit-Tests generieren und nach der Fertigstellung automatisch verifizieren.

2. Kernprinzipien beim Schreiben eines Specs (SMART-Variante)

Prinzip	Erklärung	Gegenbeispiel
Präzise	Verwende konkrete Zahlen, Typen, boolesche Bedingungen; vermeide „möglichst“, „normalerweise“	❌ „Passwort sollte sicher genug sein“ → ✅ „Passwort mindestens 8 Zeichen, mit Groß-, Kleinbuchstaben und Ziffer“
Verifizierbar	Jede Anforderung muss durch automatische Tests oder manuelle Prüfung als bestanden/nicht bestanden beurteilbar sein	❌ „Code soll elegant sein“ → ✅ „Zyklenkomplexität der Funktion ≤ 10, keine doppelten Codeblöcke“
Eindeutig	Gleicher Begriff im gesamten Text hat dieselbe Bedeutung; ggf. Glossar angeben	❌ „Wenn Benutzer nicht existiert, Fehler zurückgeben“ → ✅ „Benutzer nicht existiert → Rückgabe `404` mit `{code: 'USER_NOT_FOUND'}`“
Vollständig	Happy Path, alle Ausnahmepfade und nicht-funktionale Anforderungen abdecken	❌ Nur Erfolgsszenario geschrieben → ✅ Enthält Datenbank-Timeout, fehlende Berechtigungen usw.
Atomar	Ein Spec beschreibt nur eine unabhängig auslieferbare Funktionalität (damit KI es auf einmal erledigen kann)	❌ Ein Spec für „das ganze Zahlungssystem“ → ✅ Aufgeteilt in „Zahlungsanweisung erzeugen“, „Callback-Signatur prüfen“, „Rückerstattung“

3. Spec-Coding-Prozess bei der Zusammenarbeit mit KI

Mensch schreibt Spec (obige Struktur, insbesondere Testfälle und Funktionssignaturen).
Spec auf einmal an KI übergeben (keine dialogischen Nachforderungen, um Vibe-Verschmutzung zu vermeiden).
KI gibt Code + Unit-Tests aus (KI muss ausführbare Tests gemäß den Testfällen im Spec generieren).
Tests ausführen: Wenn alle bestanden, nächster Schritt; wenn nicht, Spec ändern oder Code direkt korrigieren (dann kann man in einen kleinen Zyklus gehen, aber Änderungen dokumentieren).
Menschliche Überprüfung: Prüfen, ob Funktionen außerhalb des Specs eingeführt wurden (Scope Creep), Sicherheit/Leistung prüfen.
Verfestigung: Spec-Dokument und endgültigen Code zusammen ins Repository einchecken, als permanentes Dokument.

Schlüsselpraxis: Spec-Codierung – Verwende spec.md + test_spec.py, wobei die Testdatei direkt aus den Beispielen im Spec stammt, sodass bei späteren Codeänderungen nur die Tests ausgeführt werden müssen, um zu prüfen, ob das Spec verletzt wurde.

4. Auswirkungen eines guten Specs (kann als Abnahmekriterium dienen)

Determinismus: Das gleiche Spec führt bei verschiedenen KIs (oder verschiedenen Personen) zu ähnlichen Implementierungen.
Testbarkeit: Nach dem Schreiben des Codes können sofort 90% der Korrektheit automatisch verifiziert werden.
Wartbarkeit: Nach einem halben Jahr kann jeder, der das Spec liest, die ursprüngliche Designabsicht verstehen.
Niedrige Kommunikationskosten: Im Team diskutiert man nur das Spec, nicht einzelne Codezeilen.
Integrierte Sicherheit/Qualität: Sicherheitsanforderungen (z.B. parametrisierte Abfragen) und Randbedingungen sind im Spec festgelegt, die KI muss sie einhalten.

5. Ein Beispiel für ein gutes Spec (Minimalversion)

# Spec: Benutzerregistrierungs-API

## Umfang
- Empfängt email, password
- Sendet keine Verifizierungs-E-Mail, prüft nicht die Echtheit der E-Mail

## Vertrag
POST /register
Content-Type: application/json
Request: { "email": string, "password": string }
Response 201: { "user_id": string }
Response 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Response 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Verhalten
- email muss dem grundlegenden RFC-5322-Format entsprechen (a@b.c)
- password: Länge 8-20, mindestens eine Ziffer und ein Großbuchstabe
- Mit bcrypt verschlüsselt speichern, Salt-Kosten 10
- Wenn vor dem Speichern in der Datenbank festgestellt wird, dass die E-Mail bereits existiert → 409

## Testfälle (Eingabe -> Erwarteter Statuscode+Antwortfeld)
| Eingabe email | password | Erwartung |
|------------|----------|------|
| test@x.com | Pass1234  | 201, user_id vorhanden |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (bereits vorhandene E-Mail) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Nicht-funktionale Anforderungen
- SQL muss parametrisierte Abfragen verwenden (gegen Injection)
- Protokollierung der Registrierungsquell-IP, keine Passwortprotokollierung
- Antwortzeit bei 95% der Anfragen < 100ms (ohne bcrypt)

## Abhängigkeiten
- Python 3.10+, FastAPI, bcrypt, asyncpg

Gutes Spec Coding = Die ‚Designentscheidungen‘ des Menschen in ‚Testfälle + Typsignaturen + Verhaltensbeschränkungen‘ für die Maschine schreiben, sodass die KI nur noch die Implementierung ausfüllt, während der Mensch stets die Qualität und Richtung kontrolliert.