GalRogozinski/sdd

Skill für Spezifikationsgetriebene Entwicklung (SDD)

Führen Sie Benutzer durch GitHub's Spec-Kit für Spezifikationsgetriebene Entwicklung – eine Methodik, die die traditionelle Softwareentwicklung umkehrt, indem sie Spezifikationen ausführbar macht und direkt funktionierende Implementierungen generiert.

Kernphilosophie

Spezifikationsgetriebene Entwicklung betont:

• Intentionsgetriebene Entwicklung: Definiere das "Was" vor dem "Wie"
• Erstellung umfangreicher Spezifikationen: Nutze Leitplanken und organisatorische Prinzipien
• Mehrstufige Verfeinerung: Keine einmalige Codegenerierung
• KI-nativ: Starke Abhängigkeit von fortschrittlichen KI-Fähigkeiten

Denken Sie daran: Dies ist KI-native Entwicklung. Spezifikationen sind nicht nur Dokumentation – sie sind ausführbare Artefakte, die direkt die Implementierung steuern. Der KI-Agent verwendet sie, um funktionierenden Code zu generieren, der der in den Spezifikationen definierten Absicht entspricht.

Abnahmekriterien: Gherkin-Format (Erforderlich)

Jede User Story in jeder spec.md (oder specify.md) MUSS Gherkin-artige Abnahmekriterien enthalten, zusätzlich zur textlichen Beschreibung. Dies gilt sowohl für Greenfield- als auch für Brownfield-Projekte, für jede User Story, und unabhängig davon, ob das Artefakt von /speckit.specify erstellt oder manuell für ein Repository verfasst wurde, das nicht die CLI-generierte Vorlage verwendet. Die Beschreibung sagt, worum es in der Story geht; Gherkin-Szenarien sagen genau, wie man sie überprüft – das macht eine Spezifikation ausführbar anstatt beschreibend.

Format – ein eingerahmter gherkin-Block direkt unter jeder User Story, 1–4 Szenarien: zuerst der Happy Path, dann die Rand-/Negativfälle, die für diese Story relevant sind (nicht jeden Randfall der Spezifikation – diese gehören in den eigenen Abschnitt "Randfälle" der Spezifikation; nur die für diese Story spezifischen).

Szenario: <kurzer, spezifischer Name – nicht "Happy Path">
  Angenommen <die Vorbedingung / der Ausgangszustand>
  Wenn <die einzelne Aktion, die der Akteur ausführt>
  Dann <das beobachtbare, testbare Ergebnis>
  Und <zusätzliches Ergebnis, falls erforderlich>

Szenario: <der Rand-/Negativfall für diese Story>
  Angenommen <Vorbedingung>
  Wenn <Aktion>
  Dann <Ergebnis – was NICHT passieren sollte, ist ein gültiges Dann>

Schreibregeln:

• Ein Wenn pro Szenario. Mehrere Aktionen bedeuten mehrere Szenarien – so wird sichergestellt, dass jedes Szenario einem Test zugeordnet werden kann.
• Dann muss beobachtbar sein, nicht intern: "der Benutzer sieht einen Bestätigungs-Hinweis", nicht "der Zustand wird korrekt aktualisiert". Wenn Sie nicht sagen können, wie jemand es überprüfen würde, ist es nicht bereit.
• Verwenden Sie das eigene Vokabular der Spezifikation. Angenommen/Wenn/Dann-Schritte sollten dieselben Nomen wie die User Story und die funktionalen Anforderungen verwenden (Asset-Namen, Deal-Typen, Feldnamen) – nicht umschrieben.
• Formulieren Sie die funktionalen Anforderungen nicht als Gherkin neu. Abnahmekriterien verifizieren die Story; funktionale Anforderungen werden separat nachverfolgt. Überschneidungen sind in Ordnung, die Duplizierung jeder funktionalen Anforderung als Szenario ist es nicht.
• Nummerieren Sie Szenarien zur Rückverfolgbarkeit, wenn eine Story mehr als eines hat: Szenario: AC-1 — ..., Szenario: AC-2 — ... (optional für Stories mit einem einzigen Szenario).

Beim Zusammenfassen (die 10-Punkte-Vorlage, "Was wurde generiert"), melden Sie die Anzahl der Szenarien zusammen mit den Anzahlen der User Stories/Erfolgskriterien, z. B. "5 User Stories (11 Gherkin-Szenarien), 8 Erfolgskriterien." Wenn einer User Story Abnahmekriterien fehlen, markieren Sie dies unter "🔍 Wichtige Überprüfungspunkte", bevor Sie zu /speckit.plan übergehen – Pläne, die auf Stories ohne Abnahmekriterien basieren, neigen dazu, Tests zu unterschätzen.

Verhaltens-AKs: nur für Stories mit LLM-in-the-Loop

Gherkin geht davon aus, dass ein Durchlauf über Bestehen/Nichtbestehen entscheidet. Das bricht, wenn die Ausgabe eines Modells das Ergebnis bestimmt: Ein grüner Durchlauf einer nicht-deterministischen Story beweist fast nichts. Fügen Sie für solche Stories einen Verhaltens-AKs-Block unter dem Gherkin-Block hinzu.

Generieren Sie ihn nur, wenn das beobachtbare Ergebnis der Story von der Ausgabe eines Modells abhängt. Beispiele: eine Änderung von Prompt, System-Prompt, Mission, Skill-Datei oder Tool-Beschreibung; ein Modell wählt die Aktion aus, bewertet oder entscheidet etwas oder schreibt den benutzerseitigen Text; das Modell oder seine Parameter ändern sich. Generieren Sie ihn nicht für deterministischen Code, UI-Rendering von gespeicherten Daten, Infrastruktur oder eine Story, in der ein Modellaufruf vorhanden ist, aber seine Ausgabe nicht bestätigt wird. Fragen Sie im Zweifelsfall eine Frage; fügen Sie den Block nicht spekulativ hinzu. Eine Spezifikation ohne LLM-in-the-Loop-Stories hat überhaupt keine Verhaltens-AKs und auch keinen leeren Platzhalter.

Format: ein Block pro qualifizierender Story, direkt nach ihrem Gherkin.

**Verhaltens-AKs** (LLM-in-the-Loop: <was das Modell entscheidet>)
- **Fälle:** <N> Fälle unter `<Pfad zum Fallsatz>`, aus <echten Fehlschlägen / Spuren / Transkripten>; synthetische Eingaben nur, um Lücken zu füllen, niemals synthetische erwartete Ausgaben
- **Durchläufe:** k = <k> pro Fall (≈ 3 / erwartete Fehlerrate; 20–30, wenn unbekannt)
- **Bestehungsgrenze:** <Metrik> ≥ <Schwellwert> über k, übertrifft Baseline um mehr als das Rauschen (paarweiser Vergleich mit der aktuellen Version)
- **Bewerter:** Code-Prüfung | LLM-Richter (binär, einer pro Fehlermodus) | Mensch; ein Richter benennt auch seine Validierung: TPR/TNR ≥ 0,9 (0,8 Minimum) auf zurückgehaltenen menschlichen Labels, oder "UNVALIDIERT" klar gesagt
- **Befehl:** `<ein Befehl, der es ausführt und Bestehensrate, Kosten und Latenz ausgibt>`

Regeln:

• Nur ein echter Modelldurchlauf zählt. Ein Mock, eine Keyword-Simulation oder ein vorhergesagter Wert ist kein Ergebnis. Wenn es nicht ausgeführt werden kann (Kosten, Schlüssel), sagen Sie, die Story ist UNBEWERTET. Fälschen Sie keine Zahl.
• Bevorzugen Sie einen Code-Bewerter. Verwenden Sie einen Richter nur für das, was Code nicht überprüfen kann.
• Gherkin gilt weiterhin. Die Gherkin-Szenarien decken die deterministische Hülle ab (geschriebene Artefakte, eingehaltene Wächter). Die Verhaltens-AKs decken das Verhalten des Modells ab.
• plan.md enthält die Auswertung: den Ort des Fallsatzes, den Ausführungsbefehl, die Kosten pro Durchlauf und wann er ausgeführt wird (pro PR, oder nur vor dem Merge, wenn es teuer ist).

Beim Zusammenfassen zählen Sie sie separat, z. B. "5 User Stories (11 Gherkin-Szenarien, 2 mit Verhaltens-AKs)". Markieren Sie unter "Wichtige Überprüfungspunkte" jede LLM-in-the-Loop-Story, der der Block fehlt, und jeden als UNVALIDIERT markierten Richter.

Schnellentscheidungsbaum

Handelt es sich um ein neues Projekt (Greenfield)?

→ Siehe Greenfield-Workflow für den vollständigen 6-Schritte-Prozess

Handelt es sich um eine bestehende Codebasis (Brownfield)?

→ Siehe Brownfield-Workflow für Reverse-Engineering- und Integrationsanleitung

Benötigen Sie Installationshilfe?

→ Siehe Installationsanleitung für Einrichtung und Fehlerbehebung

Schnellstart Installation

Empfohlen (Dauerhaft):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Einmalige Nutzung:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJEKTNAME>

Überprüfen:

specify check

Ausführliche Installationsoptionen, Fehlerbehebung und Umgebungsvariablen finden Sie in der Installationsanleitung.

Unterstützte KI-Agenten

Funktioniert mit:

• ✅ Claude Code
• ✅ GitHub Copilot
• ✅ Gemini CLI
• ✅ Cursor
• ✅ Qwen Code
• ✅ opencode
• ✅ Windsurf
• ✅ Kilo Code
• ✅ Auggie CLI
• ✅ CodeBuddy CLI
• ✅ Roo Code
• ✅ Codex CLI
• ✅ Amp
• ⚠️ Amazon Q Developer CLI (unterstützt keine benutzerdefinierten Argumente für Slash-Befehle)

Artefakt-Zusammenfassung und Feedback-Schleife

KRITISCHER WORKFLOW: Nachdem ein SDD-Befehl Artefakte generiert oder geändert hat, führen Sie automatisch diese Feedback-Schleife aus, um den Benutzer zu involvieren:

Nach Abschluss jedes Befehls

1. Artefaktänderungen erkennen

   • Identifizieren Sie, welche Artefakte erstellt oder geändert wurden:
     • constitution.md (Projektprinzipien)
     • spec.md (Anforderungsspezifikation)
     • plan.md (Technischer Implementierungsplan)
     • tasks.md (Aufschlüsselung umsetzbarer Aufgaben)
     • Analyseberichte aus Brownfield-Workflows

2. Lesen und Zusammenfassen

   • Lesen Sie das/die relevante(n) Artefakt(e)
   • Extrahieren Sie Schlüsselinformationen:
     • Für constitution.md: Kernprinzipien, Codierungsstandards, Einschränkungen
     • Für spec.md: Hauptanforderungen, User Stories (mit ihren Gherkin-Abnahmekriterien), Erfolgskriterien
     • Für plan.md: Technologie-Stack-Entscheidungen, Architekturentscheidungen, Meilensteine
     • Für tasks.md: Anzahl der Aufgaben, Hauptaufgabenkategorien, Abhängigkeiten
     • Für Analyseberichte: Aktuelle Muster, technische Schulden, Integrationspunkte

3. Strukturierte Zusammenfassung präsentieren (10-Punkte-Vorlage unten verwenden)

   • Zeigen Sie, was generiert wurde und warum
   • Heben Sie die wichtigsten Entscheidungen mit Begründung hervor
   • Fügen Sie Qualitätsindikatoren und Warnhinweise ein
   • Halten Sie die Zusammenfassung fokussiert und umsetzbar
   • Verwenden Sie klare Überschriften für jeden Abschnitt

4. Feature-Status einbeziehen (Hybrider Ansatz)

   • Kurze Statuszeile in jeder Zusammenfassung
   • Detaillierter Status auf Anfrage mit /speckit.status
   • Siehe Abschnitt "Feature-Status-Tracking" unten

5. Feedback-Optionen anbieten

   • Option A: "Sieht gut aus, fahren Sie mit dem nächsten Schritt fort"
   • Option B: "Ich möchte [bestimmten Abschnitt] ändern"
   • Option C: "Mit diesen Änderungen neu generieren: [Benutzereingabe]"
   • Option D: "Erklären Sie, warum [bestimmte Entscheidung] getroffen wurde"

10-Punkte-Zusammenfassungsvorlage

Verwenden Sie dieses strukturierte Format NACH Abschluss eines SDD-Befehls:

## ✅ [Befehlsname] Abgeschlossen – Hier ist, was gerade passiert ist

### 🎯 Wichtigste getroffene Entscheidungen (Top 3)
1. [Entscheidung] - **Begründung:** [Warum dies gewählt wurde]
2. [Entscheidung] - **Begründung:** [Warum dies gewählt wurde]
3. [Entscheidung] - **Begründung:** [Warum dies gewählt wurde]

### 📋 Was wurde generiert
- [Artefakt 1]: [Kurze Beschreibung des Inhalts]
- [Artefakt 2]: [Kurze Beschreibung des Inhalts]

### 🔍 Wichtige Überprüfungspunkte (Top 3)
1. [Kritischer Punkt zum Prüfen und warum er wichtig ist]
2. [Wichtiges Detail zum Überprüfen und potenzielle Auswirkungen]
3. [Zu berücksichtigender Randfall und wie er das Design beeinflusst]

### ⚠️ Vorsicht bei (Top 2)
- [Potenzielles Problem oder Stolperfalle] - **So vermeiden:** [Anleitung]
- [Häufiger Fehler] - **So vermeiden:** [Anleitung]

### 🔄 Was dies als Nächstes ermöglicht (2 Optionen)
- **Option 1:** [Nächster Schritt] - Am besten, wenn: [Bedingung]
- **Option 2:** [Alternativer Schritt] - Am besten, wenn: [Bedingung]

📊 **Feature-Status:** [Aktueller Feature-Name] ([Phase]) → Als Nächstes: [Nächstes Feature]
   Fortschritt: [●●●○○] [X]% | Abgeschlossen: [N] von [Gesamt] Features | Abhängigkeiten: [Status]

**Ihre Optionen:** [A] Fortfahren [B] Ändern [C] Mehr erklären [D] Vollständigen Status anzeigen

Beispiel: Erweiterte Zusammenfassung nach /speckit.specify

## ✅ Specify Abgeschlossen – Hier ist, was gerade passiert ist

### 🎯 Wichtigste getroffene Entscheidungen
1. **Authentifizierung: JWT-Tokens** - Begründung: Zustandslose Architektur, horizontal skalierbar, Industriestandard
2. **Passwortanforderungen: 12+ Zeichen mit Komplexität** - Begründung: Balanciert Sicherheit (NIST-Richtlinien) mit Benutzerfreundlichkeit
3. **Session-Timeout: 24 Stunden** - Begründung: Standard für Web-Apps, balanciert Sicherheit und Benutzerfreundlichkeit

### 📋 Was wurde generiert
- `.speckit/features/user-auth/specify.md`: Vollständige Anforderungen mit 5 User Stories (12 Gherkin-Abnahmekriterien-Szenarien), 8 Erfolgskriterien, 3 Randfällen

### 🔍 Wichtige Überprüfungspunkte
1. **Passwort-Reset-Flow** - Überprüfen Sie, ob die E-Mail-Anforderungen Ihrer Infrastruktur entsprechen (SMTP-Server, Vorlagen)
2. **Multi-Faktor-Authentifizierung** - Derzeit als "zukünftige Erweiterung" markiert; möglicherweise im MVP erforderlich
3. **Ratenbegrenzung** - Auf 5 Anmeldeversuche pro 15 Minuten eingestellt; prüfen Sie, ob dies Ihrer Sicherheitsrichtlinie entspricht

### ⚠️ Vorsicht bei
- **E-Mail-Dienst-Abhängigkeit nicht spezifiziert** - So vermeiden: E-Mail-Dienst zu den Abhängigkeiten in plan.md hinzufügen
- **DSGVO-Konformität für Benutzerdaten** - So vermeiden: Überprüfen Sie die Anforderungen an Datenaufbewahrung und Benutzerlöschung

### 🔄 Was dies als Nächstes ermöglicht
- **Option 1:** `/speckit.plan` ausführen, um die technische Implementierung zu entwerfen - Am besten, wenn: Die Anforderungen gut aussehen
- **Option 2:** specify.md ändern - Am besten, wenn: Sie Anforderungen anpassen oder Features hinzufügen müssen

📊 **Feature-Status:** user-authentication (Spezifiziert) → Als Nächstes: profile-management
   Fortschritt: [●●○○○] 40% | Abgeschlossen: 1 von 5 Features | Abhängigkeiten: database-setup ✅

**Ihre Optionen:** [A] Zur Planung übergehen [B] Anforderungen ändern [C] JWT-Auswahl erklären [D] Vollständigen Status anzeigen

Wann die Zusammenfassung übersprungen werden soll

Überspringen Sie den Zusammenfassungsschritt nur, wenn:

• Der Benutzer explizit "Zusammenfassungen überspringen" oder "alle Schritte automatisch ausführen" anfordert
• Ein Befehl ohne Artefaktänderungen erneut ausgeführt wird
• Der Befehl fehlschlägt oder Fehler produziert (stattdessen Fehler beheben)

Vorteile dieses Workflows

• Beseitigt das Gefühl einer "Black Box": Klare Erklärungen, was generiert wurde und warum
• Ermöglicht frühzeitiges Feedback: Missverständnisse vor der Implementierung erkennen
• Erhält Agilität: Kurze Überprüfung mit strukturiertem Format, keine langwierigen Genehmigungsprozesse
• Schafft Vertrauen: Der Benutzer sieht die Argumentation und Entscheidungen der KI mit Begründung
• Bietet Kontext: Der Feature-Status hält die Benutzer über das gesamte Projekt orientiert

Feature-Status-Tracking

Hybrider Ansatz

Fügen Sie nach jedem SDD-Befehl eine kurze Feature-Statuszeile in die Zusammenfassung ein. Bieten Sie detaillierten Status auf Anfrage mit /speckit.status an.

Format der Kurzstatuszeile

Fügen Sie dies am Ende jeder Zusammenfassung ein:

📊 **Feature-Status:** [Aktueller Feature-Name] ([Phase]) → Als Nächstes: [Nächster Feature-Name]
   Fortschritt: [●●●○○] [X]% | Abgeschlossen: [N] von [Gesamt] Features | Abhängigkeiten: [Abh] ✅/⏸️

Phasenwerte:

• Wird spezifiziert (20% abgeschlossen)
• Wird geplant (40% abgeschlossen)
• Wird aufgeteilt (60% abgeschlossen)
• In Bearbeitung (80% abgeschlossen)
• Abgeschlossen (100% abgeschlossen)

Fortschrittsanzeige:

• Verwenden Sie gefüllte Kreise (●) für abgeschlossene Phasen
• Verwenden Sie leere Kreise (○) für ausstehende Phasen
• Berechnen Sie den Prozentsatz basierend auf der Phase

Detailliertes Status-Dashboard

Wenn der Benutzer den vollständigen Status anfordert (Option D) oder /speckit.status ausführt, zeigen Sie:

📊 Dashboard zum Feature-Status des Projekts

🎯 AKTUELLES FEATURE
├─ [feature-name] ([Phase] - [X]% abgeschlossen)
│  ├─ ✅ Anforderungen spezifiziert
│  ├─ 🔄 Implementierungsplan in Arbeit
│  ├─ ⏸️  Aufgaben nicht gestartet
│  └─ ⏸️  Implementierung nicht gestartet
│  Blockaden: [Keine | Beschreibung]
│  Abhängigkeiten: [feature-name] ✅

✅ ABGESCHLOSSENE FEATURES ([N])
├─ [feature-1] (100% abgeschlossen)
└─ [feature-2] (100% abgeschlossen)

📋 KOMMENDE FEATURES ([N])
├─ [feature-3] (abhängig von: [aktuelles-feature])
└─ [feature-4] (abhängig von: [feature-3])

⚠️  BLOCKIERTE FEATURES

…