Rezept: Fehlerbehebung mit SDD

Dieses Rezept zeigt, wie SpecForge verwendet wird, um einen Fehler so zu dokumentieren, einzugrenzen und zu beheben, dass eine dauerhafte Spec entsteht — damit dieselbe Fehlerklasse nie wieder ausgeliefert wird.

Warum Fehler als Specs dokumentieren?

Die meisten Fehler wiederholen sich, weil das korrekte Verhalten nie formal spezifiziert wurde. Einen Fehler ohne eine Spec zu beheben bedeutet:

• Die Behebung hat keine Abnahmekriterien (woher weiß man, dass er behoben ist?)
• Der Regressionstest hat keine Rückverfolgbarkeit
• Dasselbe Muster kann in verwandtem Code wieder auftauchen

SDD behandelt Fehler als fehlende oder falsche Specs. Den Fehler zu beheben bedeutet, die Spec zu schreiben, die hätte existieren sollen, und dann entsprechend zu implementieren.

---

Szenario

Benutzer melden, dass das gleichzeitige Aufgeben von zwei Bestellungen manchmal zu doppelten Belastungen führt. Dies ist ein Parallelitätsfehler im Bestellaufgabe-Ablauf.

---

Schritt 1 — Den Fehler klären

Prompt:

Use specforge to clarify requirements for a bug fix:
duplicate charges when placing simultaneous orders in project proj_abc123

SpecForge wird fragen:

• Wo tritt die Verdoppelung auf — API-Schicht, Zahlungsabwickler oder DB?
• Ist dies unter bestimmten Bedingungen reproduzierbar (Last, Netzwerkverzögerung)?
• Was ist das erwartete Verhalten — genau eine Belastung pro Bestellung, immer?
• Gibt es bestehende Tests, die dies hätten auffangen sollen?

---

Schritt 2 — Eine Fehlerbehebungs-Spec erstellen

Prompt:

Create a spec for fixing duplicate charge bug in order placement for project proj_abc123.
Root cause: race condition in OrderService.placeOrder — no idempotency key on Stripe call.
Expected: exactly one charge per order regardless of concurrent requests.

Was die Spec enthalten wird:

## Acceptance Criteria

1. Placing the same order twice concurrently results in exactly one Stripe charge
2. The second concurrent request receives a 409 Conflict response with order ID
3. Idempotency key is derived from orderId and stored in orders table
4. Existing orders cannot be modified after payment is initiated
5. Integration test covers concurrent order placement with 10 simultaneous requests
6. Unit test covers idempotency key generation edge cases (UUID v4, collision resistance)

---

Schritt 3 — Das Behebungsdesign belasten

Prompt:

Challenge spec SPEC-BUG-001 for project proj_abc123

SpecForge wird folgendes prüfen:

• Was, wenn die Idempotenz-Schlüssel-Generierung selbst eine Race Condition hat?
• Was, wenn die erste Anfrage mitten im Flug fehlschlägt — gelingt die zweite?
• Was ist die Ablaufrichtlinie für Idempotenz-Schlüssel?
• Behandelt die Behebung den Fall, in dem die Zahlung erfolgreich ist, aber der DB-Write fehlschlägt?

---

Schritt 4 — Sicherheitsprüfung

Prompt:

Run a security check on spec SPEC-BUG-001 for project proj_abc123

Parallelitäts-Zahlungsfehler haben oft Sicherheitsimplikationen — sicherstellen, dass die Behebung keine TOCTOU-Schwachstelle einführt.

---

Schritt 5 — Bestehenden Code rückwärts analysieren

Dokumentieren, was der aktuelle (defekte) Code tatsächlich tut:

Prompt:

Reverse engineer the code at /Users/me/my-app/src/orders/OrderService.ts for project proj_abc123

Dies erstellt eine Spec des aktuellen Verhaltens — nützlich zum Verstehen, wo genau Spec und Implementierung auseinandergegangen sind.

---

Schritt 6 — Tests zuerst generieren (TDD-Ansatz)

Prompt:

Generate tests for spec SPEC-BUG-001 in project proj_abc123

Die Regressionstests vor dem Ändern der Implementierung schreiben. Dies stellt sicher:

• Der Fehler ist mit einem Test reproduzierbar (rot)
• Die Behebung lässt den Test bestehen (grün)
• Der Test bleibt für immer in der Suite (Regressionsschutz)

---

Schritt 7 — Ausführungsplan generieren

Prompt:

Generate an execution plan for spec SPEC-BUG-001 in project proj_abc123

Für eine Fehlerbehebung sieht der Plan typischerweise so aus:

## Phase 1: Reproduce
- [ ] Write failing integration test that triggers duplicate charge (RED)
- [ ] Confirm test fails against current implementation

## Phase 2: Fix
- [ ] Add idempotency_key column to orders table (migration)
- [ ] Generate idempotency key in OrderService before Stripe call
- [ ] Store key atomically with order creation (transaction)
- [ ] Handle 409 from Stripe idempotency endpoint

## Phase 3: Verify
- [ ] Run integration test (GREEN)
- [ ] Run full test suite
- [ ] Manual test with Stripe test mode concurrent requests

---

Schritt 8 — Implementieren und validieren

Nach der Implementierung der Behebung:

Prompt:

Validate spec SPEC-BUG-001 against the code at /Users/me/my-app/src for project proj_abc123

Sicherstellen, dass alle 6 Abnahmekriterien durch Implementierung und Tests abgedeckt sind.

---

Schritt 9 — Abweichung von der ursprünglichen Spec erkennen

Wenn es eine bestehende SPEC für den Bestellaufgabe-Ablauf gibt, prüfen, ob die Fehlerbehebung Abweichungen eingeführt hat:

Prompt:

Detect drift in spec SPEC-002 (order placement) for project proj_abc123

Die Behebung muss möglicherweise in der ursprünglichen Spec als neues Kriterium reflektiert werden: "Das System muss Idempotenz-Schlüssel für alle Stripe-API-Aufrufe verwenden."

---

Schritt 10 — Die Erkenntnis festhalten

Prompt:

Capture learning: payment provider API calls must always include idempotency keys derived from the business entity ID, never from request-generated UUIDs

Dieses Muster wird nun gespeichert und zukünftige Specs, die Zahlungs-API-Aufrufe beinhalten, beeinflussen.

---

Ergebnis dieses Rezepts

Am Ende:

• Eine Fehlerbehebungs-Spec (SPEC-BUG-001) mit vollständigen Abnahmekriterien
• Regressionstests mit Rückverfolgbarkeit zu jedem Kriterium
• Die ursprüngliche Spec aktualisiert, um das korrekte Verhalten widerzuspiegeln
• Eine festgehaltene Erkenntnis, die verhindert, dass das Muster wiederkehrt
• Ein Audit-Trail: wann der Fehler gefunden wurde, was die Behebung war, warum es die richtige Behebung war