Spec-Driven Development¶

Spec-Driven Development (SDD) ist eine Entwicklungsmethodik für die strukturierte Zusammenarbeit zwischen Entwicklern und Coding Agents (Claude Code, Cursor, Gemini CLI, etc.). Polycrate stellt die technische Infrastruktur bereit: ein standardisiertes .specs/-Verzeichnis-Layout, ein maschinenlesbares Spec-Format mit ID-basiertem Lifecycle-Management sowie vollständige CLI-Commands für alle Phasen. Optional pflegen Teams zusätzlich eine Referenzarchitektur in .specs/ARCHITECTURE.md (direkt editierbar, nicht index-getrieben) — siehe Referenzarchitektur.

Warum Spec-Driven Development?¶

Ohne SDD entstehen in AI-gestützten Entwicklungsworkflows typische Probleme:

• Coding Agents schreiben Code ohne dokumentierten Kontext — niemand weiß mehr, warum etwas so implementiert wurde
• Releases sind schwer nachvollziehbar — welche Änderungen gehören zu welcher Version?
• Agents bearbeiten Dateien direkt und korrumpieren dabei Strukturen, die Maschinen lesen müssen
• Kein gemeinsames "Backlog" zwischen Mensch und Agent — Aufgaben existieren nur im Chat-Kontext

SDD löst diese Probleme durch einen definierten Prozess:

Konzepte¶

Specs¶

Eine Spec ist ein strukturiertes Markdown-Dokument, das eine Änderung, einen Bugfix oder ein Feature von der Idee bis zur Implementierung begleitet. Jede Spec hat:

• Eine eindeutige ID (ganzzahlig, nie wiederverwendet)
• Einen Status (planned, pending-approval, approved, pending-verification, implemented, cancelled)
• Einen Typ (Conventional Commits: feat, fix, breaking, …)
• Strukturierte Sektionen: Context, Solution, Migration, Open Questions, Review und weitere (siehe Sektionsschema)
• Optionale Labels für Filterung und Grouping
• Optionale Abhängigkeiten (needs) zu anderen Specs — blockierend
• Optionale thematische Links (relates-to) — nicht blockierend
• Optionale Risikofelder (severity, likelihood, impact) mit Werten low, medium, high

Specs liegen in .specs/.next/ (Backlog) oder .specs/<version>/ (einem Release zugewiesen).

Index¶

Die Datei .specs/index.yml ist die einzige Quelle der Wahrheit für alle Specs. Sie enthält ID, Name, Status, Typ, Labels, Needs, Datei-Pfad und Version jeder Spec sowie den next_id-Counter.

Referenzarchitektur (.specs/ARCHITECTURE.md)¶

Die Datei .specs/ARCHITECTURE.md ist kein Spec-Dokument und nicht in index.yml eingetragen. Sie dient als empfohlene (should-have, nicht Pflicht für Finalize oder Release) Referenzarchitektur der verwalteten Software: Module, Grenzen, Datenflüsse, Verweise auf Code-Pfade — fortlaufend und inkrementell gepflegt.

Zwei Lifecycle-Phasen¶

ARBEITSPHASE                          RELEASE-PHASE
polycrate spec *                      polycrate release *
────────────────────────────          ────────────────────────────────────
Tage bis Wochen                       Minuten, nach abgeschlossener Arbeit

Specs erstellen, ausarbeiten,         Specs einer Version zuweisen
einreichen, reviewen,                 CHANGELOG.poly schreiben
implementieren, verifizieren          Release Notes (RELEASENOTE.md) füllen
"Was machen wir, und warum?"          workspace.poly version setzen
                                      Git-Tag erstellen
                                      "Dokumentation, dass etwas fertig ist"

Verzeichnisstruktur¶

my-workspace/
├── .specs/
│   ├── index.yml           # Einzige Quelle der Wahrheit (nie direkt bearbeiten!)
│   ├── ARCHITECTURE.md     # Referenzarchitektur (optional, direkt editierbar)
│   ├── .rules.md           # Projekt-spezifische Regeln für Agents (optional)
│   ├── .next/              # Backlog — noch keiner Version zugewiesen
│   │   ├── 0-login-timeout-fix.md
│   │   └── 1-api-integration.md
│   ├── 1.0.0/              # Released
│   │   └── 2-initial-setup.md
│   └── 1.1.0/              # In Vorbereitung
│       └── 3-neue-funktion.md
├── workspace.poly
└── CHANGELOG.poly

.specs/.rules.md¶

Optionale Datei mit projektspezifischen Regeln für Agents. Wird von polycrate spec rules show ausgegeben und in die generierten Agent-Rules-Dateien integriert.

# Projekt-Regeln

## Sprache
Alle Specs auf Deutsch verfassen.

## Spec-Scope
Jede Spec deckt genau ein Problem ab.

Spec-Lifecycle¶

Status-Übergänge¶

planned ──► pending-approval ──► approved ──► pending-verification ──► implemented
   │                                                                       │
   └───────────────────────────────────────────────────────────────────────┤
                                                                           │
                                                                     cancelled (jederzeit)

Cancelled Specs¶

Wenn ein Feature abgelehnt oder durch eine andere Spec ersetzt wird, kann es nicht-destruktiv archiviert werden:

polycrate spec update <id> --set status=cancelled --set cancellation_reason="Replaced by spec #18"

• spec list blendet cancelled per Default aus; --all zeigt alle inkl. cancelled
• spec validate ignoriert cancelled Specs
• release diff ignoriert cancelled Specs

Abhängigkeiten (needs) und thematische Links (relates-to)¶

Needs sind blockierende Abhängigkeiten. Der Übergang zu pending-verification wird verhindert, solange Abhängigkeiten nicht implemented sind:

# Spec 5 kann erst verifiziert werden, wenn Specs 3 und 4 implemented sind
polycrate spec link 5 --needs 3 --needs 4

# Äquivalent via spec update
polycrate spec update 5 --add-needs 3 --add-needs 4

# Abhängigkeit entfernen
polycrate spec update 5 --remove-needs 3

spec list zeigt [BLOCKED] wenn mindestens eine needs-Spec nicht implemented ist.

Validierung: Das System verhindert self-references und Zirkularitäten — direkte wie transitive.

Relates-to sind nicht-blockierende thematische Verknüpfungen. Sie dokumentieren Zusammenhänge, ohne den Lifecycle zu beeinflussen:

# Spec 5 ist thematisch verwandt mit Spec 8
polycrate spec link 5 --relates-to 8

# Äquivalent via spec update
polycrate spec update 5 --add-relates-to 8

# Link entfernen
polycrate spec update 5 --remove-relates-to 8

Risikofelder¶

Jede Spec kann optional mit Risikofeldern versehen werden:

polycrate spec update <id> --set severity=high --set likelihood=medium --set impact=low

# Filtern nach Mindest-Severity
polycrate spec list --min-severity medium    # Zeigt medium + high
polycrate spec list --min-severity high      # Nur high

Coding Agents: Submit, Open Questions und Staging¶

polycrate spec submit prüft u. a., dass die Sektion Open Questions leer ist. Das ist kein Freibrief, die Sektion zu leeren, nur um die Prüfung zu bestehen: Leer heißt „es gibt keine offenen Designfragen mehr“, weil die Antworten in Solution / Context stehen — nicht „wir haben die Fragen gelöscht“.

Für Arbeitsstil (sparsam mit Kontext/Tools, gezielte Edits statt Voll-Rewrites) gelten dieselben Hinweise wie im polycrate spec manual und in den generierten Agent-Rules (polycrate spec rules show).

Spec-Typen¶

Jede Spec hat einen Typ nach Conventional Commits. Der Typ steuert, welche Platzhalter-Hints beim spec create in die ## Context-Sektion geschrieben werden.

polycrate spec create --name "Fix login bug" --type fix
polycrate spec create --name "Add dark mode" --type feat   # Default wenn --type fehlt
polycrate spec create --name "Drop v1 API"   --type breaking
polycrate spec update <id> --set type=refactor

Gültige Typen: fix | perf | feat | refactor | chore | docs | ci | build | style | test | breaking | analysis

Sektionsschema¶

Alle Specs verwenden ein einheitliches Sektionsschema mit der zentralen Sektion ## Context:

Der Typ steuert den Scaffold-Hint in ## Context:

• fix, perf, analysis: „Symptom, analysis steps, confirmed root cause."
• feat, refactor, chore, docs, …: „Background, requirements, scope boundaries."
• breaking: „Background, requirements, why breaking change is necessary." + ## Migration ist Pflicht

Heading-Level-Regel¶

Innerhalb von Spec-Sektionen sind nur H3 (###) und tiefere Überschriften erlaubt. H1 (#) und H2 (##) sind verboten, da H2 als Sektionsgrenze reserviert ist.

• Schreibzeit: Content mit H1/H2 wird von spec update mit einem Error abgelehnt
• Lesezeit: spec inspect gibt eine Warnung auf stderr aus, wenn bestehender Content H1/H2 enthält

# Dies wird abgelehnt:
polycrate spec update 5 --section context="## Bad heading"
# Error: section "Context": line 1 contains H1/H2 heading...

# H3+ ist erlaubt:
polycrate spec update 5 --section context="### Subsection\nContent here"

Labels¶

Labels ermöglichen freies Tagging von Specs für Filterung und Grouping:

# Labels hinzufügen und entfernen
polycrate spec update <id> --add-label sdd --add-label agent
polycrate spec update <id> --remove-label sdd

# Filtern
polycrate spec list --label sdd
polycrate spec list --label sdd --type fix

Quickstart¶

1. SDD initialisieren¶

polycrate spec init

Legt .specs/, index.yml und .specs/.rules.md an. Generiert außerdem Agent-Rules-Dateien im Workspace-Root (siehe Agent-Integration).

2. Spec anlegen¶

# Mit explizitem Typ — steuert den Scaffold-Hint in ## Context
polycrate spec create --name "Login Timeout Fix" --type fix
# → Erstellt .specs/.next/0-login-timeout-fix.md mit Context (Fix-Hints)
# → Registriert in index.yml mit ID 0, Status: planned

polycrate spec create --name "Dark Mode" --type feat
# → Erstellt .specs/.next/1-dark-mode.md mit Context (Feature-Hints)

3. Quick-Capture für neue Observations¶

Wenn während der Implementierung ein neues Problem auffällt — ohne den aktuellen Kontext zu unterbrechen:

polycrate spec note "S3 upload schlägt still fehl bei 403" --type fix --label s3
# → Erstellt planned Spec sofort, gibt ID zurück
# → Weiterarbeiten am aktuellen Task

4. Spec ausarbeiten¶

# Context füllen — inline
polycrate spec update 0 --section context="Nach 30 Minuten Inaktivität werden Nutzer ausgeloggt. SESSION_COOKIE_AGE ist auf 1800s gesetzt."
polycrate spec update 0 --section solution="Erhöhe auf 28800s, aktiviere Sliding-Window."

# Sektionen aus Datei (für längeren Content) — Staging außerhalb .specs/, z. B.:
# mkdir -p /tmp/.polycrate/spec-sections
polycrate spec update 0 --section-file solution=/tmp/.polycrate/spec-sections/spec-0-solution.md

# Sektionen aus Stdin (für Pipes und Scripte)
polycrate spec inspect 0 --section context | process.py | \
  polycrate spec update 0 --section-stdin solution

# Risikofelder setzen
polycrate spec update 0 --set severity=medium --set impact=high

Verfügbare Sektionen: context, solution, affected-files, acceptance-criteria, migration, open-questions, review

5. Spec lesen¶

polycrate spec inspect 0
polycrate spec inspect 0 --section solution   # Nur eine Sektion

6. Spec einreichen¶

polycrate spec submit 0
# Validiert: solution nicht leer, open-questions leer
# Bei type=breaking: migration nicht leer
# Setzt status: pending-approval

7. Review, Implementierung, Verifikation¶

# Reviewer gibt frei
polycrate spec update 0 --set status=approved

# Nach Implementierung: zur Verifikation einreichen
# (needs-Check: alle Abhängigkeiten müssen implemented sein)
polycrate spec update 0 --set status=pending-verification

# Nach Verifikation
polycrate spec update 0 --set status=implemented

# Optional: Review-Sektion füllen (Nachbetrachtung)
polycrate spec update 0 --section review="Performance-Impact verifiziert, keine Regression."

8. Überblick behalten¶

# Kompakte Tabelle (Default seit 0.32.0)
polycrate spec list

# Filter
polycrate spec list --open             # Nicht implemented, nicht cancelled (ohne --status / --exclude-status)
polycrate spec list --status pending-approval
polycrate spec list --status planned --status approved
polycrate spec list --status planned,pending-approval
polycrate spec list --min-severity medium
polycrate spec list --exclude-status implemented,cancelled
polycrate spec list --label sdd
polycrate spec list --type fix
polycrate spec list --blocked          # Nur Specs mit nicht-implementierten Abhängigkeiten
polycrate spec list --all              # Inkl. cancelled Specs

# Sortierung (Default: id aufsteigend)
polycrate spec list --sort name
polycrate spec list --sort created:desc

# Maschinenlesbar / ohne TUI
polycrate spec list --format json
polycrate spec list --format tsv --columns id,status,name
polycrate spec list --format csv --no-header

# Releases (gleiche Idee für Formate und Sortierung)
polycrate release list --sort version:desc --format tsv

Code-Referenzen in Kommentaren¶

Wenn eine Spec in einem Code-Kommentar referenziert wird, ist die stabile Referenz die Spec-ID, nicht der Dateipfad:

// Spec: polycrate spec inspect 5     ← KORREKT (stabil, funktioniert nach Release)
// Spec: .specs/.next/5-feature.md    ← FALSCH (Pfad ändert sich beim Release)

Der Dateipfad ist ein Implementierungsdetail. polycrate spec inspect <id> funktioniert unabhängig von Status und Speicherort.

Release-Lifecycle¶

Release erstellen¶

# Vorschau: welche Specs sind bereit?
polycrate release diff 1.0.0

# Release erstellen und Specs zuweisen
polycrate release create 1.0.0 --spec 0 --spec 1
# → Verschiebt Spec-Dateien von .next/ nach 1.0.0/
# → Aktualisiert index.yml
# → Erstellt automatisch RELEASENOTE.md (Scaffold)

Changelog und Release Notes schreiben¶

# Changelog-Eintrag
polycrate release update 1.0.0 \
  --set type=feat \
  --set message="Login Timeout Fix + API Integration" \
  --changelog-item "FIX: Session-Timeout auf 8h erhöht, Sliding-Window aktiviert" \
  --changelog-item "FEAT: Neue REST-API Integration für Kundendaten"

# Dokumentations-Link setzen (erscheint als Warning in release status wenn fehlend)
polycrate release update 1.0.0 \
  --set docs_url="https://docs.ayedo.de/polycrate/releases/cli/1.0.0/"

# Release Notes schreiben (RELEASENOTE.md)
polycrate release update 1.0.0 \
  --note-section highlights="Highlights der Version 1.0.0" \
  --note-section changes="Detaillierte Änderungen"

# Release Notes aus Datei
polycrate release update 1.0.0 \
  --note-section-file highlights=/tmp/.polycrate/spec-sections/highlights.md

Release Notes (RELEASENOTE.md)¶

Jedes Release hat eine strukturierte RELEASENOTE.md im Versionsverzeichnis (.specs/<version>/RELEASENOTE.md). Sie wird automatisch beim release create als Scaffold angelegt.

# Release Note Status prüfen
polycrate release note status 1.0.0

# Release Note anzeigen
polycrate release note inspect 1.0.0
polycrate release note inspect 1.0.0 --section highlights

# Release Note manuell erstellen (falls nicht via release create geschehen)
polycrate release note create 1.0.0

Die gleiche Heading-Level-Regel wie für Specs gilt auch für Release Notes: nur H3 und tiefer innerhalb von Sektionen.

Release abschließen¶

Vor release finalize führt Polycrate automatisch Guards durch:

polycrate release status 1.0.0    # Zeigt Warnings und Checklist

polycrate release finalize 1.0.0
# → Setzt workspace.poly version: 1.0.0
# → Erstellt Git-Tag v1.0.0
# → Führt Pre/Post-Actions aus (falls konfiguriert)

# Danach committen und pushen
polycrate workspace sync

Release-Übersicht¶

polycrate release list
polycrate release status 1.0.0

Validation¶

polycrate spec validate

Prüft alle Specs auf Konsistenz (Index, Dateipfade, Sektionen, Abhängigkeiten). .specs/ARCHITECTURE.md ist kein Spec und wird von der Validierung nicht als solches behandelt. Fehlermeldungen sind aktionierbar — sie zeigen immer den Fix-Command:

WARNING: spec 5 [feat]: both 'Context' and 'Solution' are empty
  → Fix: polycrate spec update 5 --section context="Background and requirements."

ERROR: spec 12 [breaking]: 'Migration' section is empty — required for type=breaking
  → Fix: polycrate spec update 12 --section-file migration=/tmp/.polycrate/spec-sections/spec-12-migration.md

ERROR: spec 7 cannot move to pending-verification — blocked by:
  #3 "Volume Discovery" [planned]
  → Fix: implement spec #3 first

Agent-Integration¶

SDD ist für die Arbeit mit Coding Agents konzipiert. polycrate spec init und polycrate spec rules generate erzeugen automatisch Instruktionsdateien im Workspace-Root:

Was die Agent-Rules-Dateien enthalten¶

• Strikte Regeln für .specs/: Direkte Edits für Spec-Dateien, index.yml und index-getriebenen Release-Zustand sind verboten — dokumentierte Ausnahme: .specs/ARCHITECTURE.md (Referenzarchitektur)
• Agent discipline: Kein vorschnelles spec submit; Open Questions nicht leeren, um nur das Submit-Gate zu passen; Staging-Dateien für --section-file unter /tmp/.polycrate/spec-sections/ statt unter .specs/; knappe, effiziente Arbeitsweise (siehe polycrate spec manual)
• Antwort-Text (Meta): Dieselbe Regel wie in der Tabelle Coding Agents: Finalisieren, Open Questions und Staging weiter oben — bei eingehaltener CLI-Nutzung nicht proaktiv betonen, dass Spec-Arbeit „nur per polycrate spec *“ oder „ohne manuelle .specs/-Edits“ erfolgte; nur bei Nachfrage, Fehler/Recovery oder bewusster SDD-Einweisung.
• Session-Start-Protokoll: Was der Agent zu Beginn einer Session tun muss (inkl. empfohlenem Überflug von ARCHITECTURE.md, falls vorhanden)
• Vollständige Command-Referenz mit konkreten Beispielen — inkl. Typen, Labels, Needs, Quick-Capture, Code-Referenzen, Release-Guards
• Recovery-Commands für Index-Inkonsistenzen
• Projektspezifische Regeln aus .specs/.rules.md
• Versionsheader: Zeigt mit welcher Polycrate-Version die Rules generiert wurden

Agent-Workflow (Session-Start)¶

# 1. Manual lesen (LLM-optimiert)
polycrate spec manual --no-pager -w /path/to/workspace

# 2. Projektspezifische Regeln lesen
polycrate spec rules show --no-pager -w /path/to/workspace

# 3. Aktuellen Stand sehen
polycrate spec list --format json -w /path/to/workspace

# 4. (Empfohlen) Wenn .specs/ARCHITECTURE.md existiert: kurz lesen für Abgleich mit aktueller Arbeit

Agent-Rules aktualisieren¶

# Nach Polycrate-Upgrade (enthält Versionsheader für Erkennung)
polycrate spec rules generate --force

# Vorschau ohne Schreiben
polycrate spec rules show --no-pager

Recovery¶

Wenn der Index durch externe Eingriffe inkonsistent geworden ist (z. B. manuelle Bearbeitung von Spec-Dateien oder fehlgeschlagene Operationen — nicht durch reine Pflege von .specs/ARCHITECTURE.md):

# Index aus Dateisystem neu aufbauen
# Erkennt automatisch Legacy-Formate und vergibt stabile IDs via Dateiname-Hash
polycrate spec index rebuild

# Konsistenz prüfen
polycrate spec validate

Sandbox und Runtime-Verzeichnis¶

SDD-Commands (polycrate spec *, polycrate release *) starten keinen vollständigen Workspace — kein Docker, kein Container. Sie sind leichtgewichtig und funktionieren auch in eingeschränkten Umgebungen.

In Sandbox-Umgebungen (z. B. eingeschränkte Schreibrechte auf HOME):

polycrate spec list --runtime-dir /tmp/polycrate-run -w /pfad/zum/projekt

→ Details: CLI-Referenz — Runtime-Verzeichnis

Typischer Workflow (Gesamtübersicht)¶

sequenceDiagram
    participant Dev as Entwickler
    participant CLI as polycrate spec
    participant Agent as Coding Agent
    participant Rel as polycrate release

    Dev->>CLI: spec init
    CLI-->>Dev: .specs/ + Agent-Rules-Dateien

    Dev->>CLI: spec create --name "Feature X" --type feat
    CLI-->>Dev: ID 0, status: planned

    Dev->>CLI: spec update 0 --section context="..."
    Dev->>CLI: spec update 0 --section solution="..."

    Agent->>CLI: spec inspect 0
    CLI-->>Agent: Spec-Inhalt
    Dev->>CLI: spec submit 0
    CLI-->>Dev: Status: pending-approval

    Dev->>CLI: spec update 0 --set status=approved
    Agent->>Agent: Implementierung
    Agent->>CLI: spec note "Neues Problem entdeckt" --type fix
    Agent->>CLI: spec update 0 --set status=pending-verification
    Dev->>CLI: spec update 0 --set status=implemented

    Dev->>Rel: release create 1.0.0 --spec 0
    Dev->>Rel: release update 1.0.0 --set type=feat ...
    Dev->>Rel: release status 1.0.0
    Dev->>Rel: release finalize 1.0.0
    Rel-->>Dev: workspace.poly version=1.0.0, Git-Tag v1.0.0

Alle Commands im Überblick¶

polycrate spec¶

polycrate release¶

Siehe auch¶

• CLI-Referenz
• Workspaces
• Git-Integration
• Best Practices