/* voltgrid */ → spec

Spec-Driven mit KI

So arbeite ich: Requirements und technisches Design werden zuerst geschrieben, und zwar als Dateien im Projekt-Repo, nicht als Word-Anhang in einer Mail. Gegen diese Spec arbeitet dann ein Agenten-Loop-Harness: implementieren, testen, nachbessern, bis jedes Kriterium grün ist. Das Ergebnis ist ein Projekt, das sich selbst dokumentiert. Links die Spec von SPEC-042, rechts der Loop. Schau zu, wie die Checkboxen abgehakt werden.

requirements + technisches design→agenten-loop bis grün→code · tests · openapi→david.review()→voll dokumentiertes projekt
specs/SPEC-042-start-charging-session.md

# SPEC-042 · Start Charging Session

status: approved · owner: david · agents: enabled

## Goal

Drivers start a charging session from the app; pricing is estimated upfront and billing can never drift from the live estimate.

## Acceptance Criteria

  • AC-1available station + supported connector → 201 + receipt
  • AC-2station in maintenance → 422 (stationId)
  • AC-3occupied station → 422 (stationId)
  • AC-4unsupported connector → 422 (connectorType)
  • AC-5estimatedKwh outside 1–150 → 422 (estimatedKwh)
  • AC-6receipt contains estimated cost (price/kwh × kwh + base fee)

## API Contract

POST /api/v1/sessions {'{'} stationId, connectorType, estimatedKwh {'}'} → 201 | 422

## Technical Design

layers: controller → action → TariffCalculator (single pricing source, reused by billing worker) · SessionStarted event → realtime hub · errors as dedicated exceptions → 422 field errors

~/voltgrid · agent-harness · loop

// die spec ist die quelle, jedes artefakt dieser sandbox stammt aus ihr

acceptance criteria→Akzeptanzkriterien wurden 1:1 die Testnamen der Testsuite↗api contract→der API-Vertrag wurde openapi.json und die Swagger-Doku↗tech notes→die Tech-Notes wurden der Service-Layer (TariffCalculator als eine Preis-Wahrheit)↗

// das ergebnis: ein projekt, das sich selbst dokumentiert

~/voltgrid · repo
voltgrid/
├── docs/
│   ├── specs/                    ← requirements, versioned
│   │   ├── SPEC-041-station-filtering.md   ✓ implemented
│   │   ├── SPEC-042-start-charging.md      ✓ implemented
│   │   └── SPEC-043-invoice-pdf.md         ○ in progress
│   ├── design/                   ← technical design + ADRs
│   │   ├── architecture.md
│   │   └── adr/0007-queue-based-billing.md
│   └── api/openapi.json          ← always in sync
├── app/ · server/ · tests/          ← the code, right next to it
└── README.md
  • Requirements liegen als Specs versioniert im Repo, jede Anforderung hat eine Datei, einen Status und eine Historie.
  • Das technische Design steht daneben: Architektur-Doku und ADRs halten fest, was entschieden wurde und warum.
  • Der Loop hält alles synchron: Ändert sich eine Spec, ziehen Code, Tests und OpenAPI nach. Die Doku kann nicht veralten, sie ist die Quelle.
  • Onboarding und Übergabe: docs/ lesen genügt. Neue Entwickler, Kunden oder ein Audit finden das komplette Projektwissen an einem Ort.

// warum spec-driven, gerade mit ki

Doku entsteht zuerst, und veraltet nie

Requirements, API-Vertrag und technische Doku stehen vor der ersten Codezeile. Ändert sich die Anforderung, ändert sich die Spec, und der Loop zieht Code, Tests und OpenAPI nach. Es gibt keine zweite, veraltete Wahrheit.

Anforderungen werden testbar

Akzeptanzkriterien sind so formuliert, dass Agenten daraus direkt Tests ableiten. Was der Kunde abgenommen hat, ist wortwörtlich das, was die CI prüft, keine Übersetzungsverluste zwischen Fachlichkeit und Code.

KI wird produktiv statt riskant

Agenten sind schnell, aber nur so gut wie ihr Ziel. Gegen eine präzise Spec mit Loop-Harness arbeiten sie, bis die Kriterien grün sind, eine Halluzination scheitert am Test-Gate statt in Produktion.

Review auf der richtigen Ebene

Ich reviewe Spec und finalen Diff, nicht jeden Tastendruck. Architektur- und Fachentscheidungen bleiben beim Menschen, die Fleißarbeit übernimmt der Loop. Das ist der Tempo-Gewinn ohne Kontrollverlust.

// Genau so ist übrigens diese Portfolio-Seite entstanden: Konzept-Spec zuerst, dann iterative Umsetzung mit KI-Agenten · jede Zeile reviewed.