Rezept: Neue Funktion hinzufügen

Dieses Rezept führt durch den vollständigen SDD-Arbeitsablauf für das Hinzufügen einer neuen Funktion zu einem bestehenden Projekt. Wir verwenden "Stripe-Zahlungsintegration hinzufügen" als durchgehendes Beispiel.

Voraussetzungen

• SpecForge installiert und konfiguriert (Erste Schritte)
• Projekt initialisiert (init_project bereits ausgeführt, du hast eine projectId)

---

Schritt 1 — Anforderungen klären

Bevor irgendetwas geschrieben wird, Unklarheiten aufdecken.

Prompt:

Use specforge to clarify requirements for adding Stripe payment integration to project proj_abc123

Was zu erwarten ist: Eine Liste von 5–10 gezielten Fragen wie:

• Sollen Einmalzahlungen, Abonnements oder beides unterstützt werden?
• Welche Währungen müssen unterstützt werden?
• Wird Rechnungsgenerierung benötigt?
• Wie sollen fehlgeschlagene Zahlungen behandelt werden — Wiederholungslogik? Benachrichtigungen?
• Was ist die Rückerstattungsrichtlinie und wer kann Rückerstattungen einleiten?

Diese Fragen in der Konversation beantworten. SpecForge wird die Antworten in die Spec einarbeiten.

---

Schritt 2 — Die Spec erstellen

Prompt:

Create a spec for Stripe payment integration in project proj_abc123.
Requirements: one-time payments only, USD and EUR, email receipt on success,
webhook for payment events, admin refund capability.

Was zu erwarten ist: Eine vollständige HU.md, die im Spec-Speicher des Projekts gespeichert wird mit:

• 8–15 Abnahmekriterien, die den Happy Path, Fehlerfälle und Randfälle abdecken
• Datenbankschema für payments- und payment_events-Tabellen
• UI-Vertrag für die Checkout-Formular-Komponente
• ADR-Hinweis über Idempotenz-Schlüssel für Stripe-API-Aufrufe
• PLAN.md mit Implementierungsschritten

SpecForge weist dieser Spec eine ID wie SPEC-004 zu. Diese notieren.

---

Schritt 3 — Überprüfen und anpassen

Die generierte Spec lesen und bei Bedarf verfeinern.

Prompt:

Summarize spec SPEC-004 for project proj_abc123

Wenn etwas fehlt oder falsch ist:

Prompt:

Add a criterion to SPEC-004 for project proj_abc123:
"The system must validate card details client-side before sending to Stripe to minimize failed charges"

---

Schritt 4 — Die Spec belasten

Prompt:

Challenge spec SPEC-004 for project proj_abc123

Was zu erwarten ist: SpecForge wird folgendes prüfen:

• Was passiert, wenn der Stripe-Webhook vor der API-Antwort ankommt?
• Was, wenn der Benutzer während der Zahlung aktualisiert? (Idempotenz)
• Was, wenn der EUR-Konvertierungskurs-Dienst nicht verfügbar ist?
• Parallelität: Zwei Tabs schließen Zahlung gleichzeitig ab

Gefundene Lücken adressieren, bevor weitergemacht wird.

---

Schritt 5 — Bereitschaft prüfen

Prompt:

Check if spec SPEC-004 is ready for implementation in project proj_abc123

Dies validiert:

• Alle Kriterien sind testbar und eindeutig
• Keine blockierenden Abhängigkeiten (z.B. SPEC-001-Authentifizierung muss zuerst fertig sein)
• Einhaltung der Verfassung

Wenn es besteht, wird DoR: PASSED angezeigt. Wenn nicht, das Markierte beheben.

---

Schritt 6 — Aufwand schätzen

Prompt:

Estimate spec SPEC-004 for project proj_abc123

Was zu erwarten ist:

Effort: 8–13 story points
Time: 2–4 days (solo dev) / 1–2 days (pair)
Cost: $640–$1,040 at $80/hr
AI token estimate: ~45k tokens
Risk factors: Stripe webhook reliability, idempotency complexity

---

Schritt 7 — Sicherheitsprüfung

Da diese Spec Zahlungen beinhaltet:

Prompt:

Run a security check on spec SPEC-004 for project proj_abc123

Was zu prüfen ist: OWASP Top 10-Zuordnung, PCI-DSS-Angriffsfläche, Webhook-Signatur-Validierung, Stripe-API-Schlüssel-Handhabung.

---

Schritt 8 — Ausführungsplan generieren

Prompt:

Generate an execution plan for spec SPEC-004 in project proj_abc123

Dies generiert einen PLAN.md mit RED/GREEN/VERIFY-Schritten:

## Phase 1: Foundation (can parallelize 1a, 1b, 1c)
- [ ] 1a: Database migration — create payments + payment_events tables
- [ ] 1b: Define TypeScript interfaces for Stripe payloads
- [ ] 1c: Write failing tests for PaymentService (RED)

## Phase 2: Core Implementation
- [ ] 2a: Implement PaymentService.createCheckoutSession
- [ ] 2b: Implement webhook handler with signature validation
- [ ] 2c: Implement AdminRefundService

## Phase 3: Frontend
- [ ] 3a: Build CheckoutForm component with Stripe Elements
- [ ] 3b: Implement payment status polling/webhook SSE

## Phase 4: Verify
- [ ] 4a: Run full test suite (GREEN + VERIFY)
- [ ] 4b: Test with Stripe test cards
- [ ] 4c: Update spec SPEC-004 status to review

---

Schritt 9 — Tests generieren

Prompt:

Generate tests for spec SPEC-004 in project proj_abc123

Dies erzeugt Test-Stubs, die jedem Abnahmekriterium zugeordnet sind — bereit zum Ausfüllen oder als Ausgangspunkt für TDD.

---

Schritt 10 — Status auf "In Bearbeitung" setzen

Prompt:

Update status of spec SPEC-004 to in_progress in project proj_abc123

---

Schritt 11 — Implementieren

Den PLAN.md als Implementierungsleitfaden verwenden. Dein KI-Agent wird den RED/GREEN/VERIFY-Zyklus befolgen. Die Spec fungiert als Vertrag — jedes Abnahmekriterium muss erfüllt sein.

---

Schritt 12 — Implementierung validieren

Prompt:

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

Was zu erwarten ist:

Criterion 1: Payment creation ✅ covered
Criterion 2: Webhook handling ✅ covered
Criterion 3: Refund flow ✅ covered
Criterion 4: Email receipt ⚠️ partially covered — tests missing for failure case
Criterion 5: Currency validation ✅ covered

Coverage: 90% (1 criterion needs attention)

Die Lücke schließen und dann erneut validieren.

---

Schritt 13 — Als fertig markieren

Prompt:

Mark spec SPEC-004 as done in project proj_abc123

SpecForge validiert die DoD-Checkliste vor dem Akzeptieren des Übergangs. Einmal fertig, ist die Spec Teil des permanenten Projektdatensatzes.

---

Zeitübersicht

Schritt	Typische Zeit
Klären + Erstellen	5–15 Min.
Belasten + Bereitschaftsprüfung	5 Min.
Schätzen + Sicherheit	3 Min.
Plan + Tests generieren	5 Min.
Implementierung	Je nach Spec
Validieren + Als fertig markieren	5 Min.

Der SDD-Overhead beträgt 20–30 Minuten. Die Auszahlung ist eine produktionsreife Spec, ein sicherheitsgeprüftes Design und die Validierung, dass die Implementierung dem Vereinbarten entspricht.