Spec-Gatekeeper: Spezifikationsgetriebener Entwicklungs-Workflow
Verwenden Sie diese Fertigkeit immer dann, wenn ein Quellcode-Schreibvorgang durch spec-gatekeeper blockiert wird, oder wenn Sie ein neues Feature, einen neuen Dienst oder eine größere Refaktorisierung beginnen.
Spezifikationsgetriebene Entwicklung (SDD) stellt Klarheit sicher und eliminiert Drift, indem ein vereinbarter, strukturierter Architekturvertrag vor der Implementierung erforderlich ist.
Arbeitsschritte
Schritt 1: Durchführung des 4-Fragen-Entwicklerinterviews
Bevor Sie Code schreiben oder Dateien anlegen, stellen Sie dem Entwickler die folgenden 4 fokussierten Fragen (oder extrahieren Sie Antworten aus vorhandenen Anforderungen und bitten Sie um Bestätigung):
-
Umfang & Sicherheit:
- Was sind die Kernziele und expliziten Nicht-Ziele dieser Aufgabe?
- Welche Architekturkomponenten oder Systemgrenzen sind betroffen?
- Welche Sicherheits-, Berechtigungs-, Authentifizierungs- oder Sandbox-Einschränkungen gibt es?
-
Datenverträge:
- Was sind die genauen Schemata, API-Schnittstellen, Typen und Protokollformen?
- Was sind die präzisen Eingabeparameter und erwarteten Ausgabe-Payloads?
-
Grenzfälle & Resilienz:
- Was sind die wichtigsten Fehlermodi, Netzwerk-/IO-Unterbrechungen und fehlerhaften Eingaben?
- Welche Fehlerbehandlungs-, Validierungs- und Fallback-Mechanismen müssen vorhanden sein?
-
Abnahmekriterien:
- Welche deterministische Verifikationsmatrix und Testfälle definieren „Fertig“?
- Wie wird jedes Abnahmekriterium validiert?
Schritt 2: SPEC.md erstellen
Erstellen oder aktualisieren Sie SPEC.md im aufgelösten Projektstammverzeichnis (<repo_root>/SPEC.md).
Erforderliche Struktur
Die Spezifikationsdatei muss folgende Anforderungen erfüllen:
- Größenanforderung: Mindestens 300 UTF-8 Bytes an substanziellem Inhalt.
- Kanonische Abschnittsüberschriften: Markdown-Überschriften der Ebene 1 bis 3 außerhalb von Codeblöcken, die jedem der 4 erforderlichen Abschnitte entsprechen:
- Umfang & Sicherheit: Überschriften, die
Scope,Security,Architecture,Overview,Boundaries,Threat ModeloderPermissionsenthalten. - Datenverträge: Überschriften, die
Data Contract,Data Contracts,Schema,Schemas,Interface,Interfaces,API,Types,PayloadoderProtocolenthalten. - Grenzfälle: Überschriften, die
Edge Case,Edge Cases,Error Handling,Failure Mode,Failure Modes,Resilience,ConstraintsoderFallbacksenthalten. - Abnahmekriterien: Überschriften, die
Acceptance Criteria,Acceptance Test,Test Matrix,Verification,Testing,Definition of DoneoderValidationenthalten.
- Umfang & Sicherheit: Überschriften, die
Vorlage
# Spezifikation: <Feature- oder Dienstname>
## 1. Umfang & Sicherheit
### Ziele & Architekturgrenzen
- Detaillierte Beschreibung des Umfangs...
### Sicherheit & Bedrohungsmodell
- Berechtigungsprüfungen und Sicherheitsgrenzen...
## 2. Datenverträge
### Schemata & Schnittstellen
- Typen, API-Signaturen, Anfrage-/Antwortformate...
## 3. Grenzfälle & Resilienz
### Fehlerbehandlung & Fallbacks
- Randbedingungen, Eingabevalidierung, Fehlermodi...
## 4. Abnahmekriterien
### Verifikation & Testmatrix
- AT-01: ...
- AT-02: ...
Schritt 3: Entwickler-Freigabe & Implementierung
- Legen Sie den Entwurf der
SPEC.mddem Entwickler zur Überprüfung und expliziten Freigabe vor. - Sobald
SPEC.mdcommittet und gültig ist (>= 300 Bytes mit allen 4 Abschnitten), erlaubt derspec-gatekeeper-Hook automatisch das Schreiben von Implementierungsquelldateien.