Checklisten-Zweck: „Unit-Tests für Anforderungen"
KRITISCHES KONZEPT: Checklisten sind UNIT-TESTS FÜR DAS SCHREIBEN VON ANFORDERUNGEN – sie validieren die Qualität, Klarheit und Vollständigkeit von Anforderungen in einem bestimmten Bereich.
Nicht für Verifikation/Tests:
- ❌ NICHT „Überprüfen, ob der Button korrekt klickt"
- ❌ NICHT „Testen, ob die Fehlerbehandlung funktioniert"
- ❌ NICHT „Bestätigen, dass die API 200 zurückgibt"
- ❌ NICHT prüfen, ob Code/Implementierung mit dem Lastenheft übereinstimmt
FÜR Validierung der Anforderungsqualität:
- ✅ „Sind visuelle Hierarchieanforderungen für alle Kartentypen definiert?" (Vollständigkeit)
- ✅ „Ist ‚prominente Darstellung' mit spezifischen Größen-/Positionierungsangaben quantifiziert?" (Klarheit)
- ✅ „Sind Hover-Zustandsanforderungen konsistent über alle interaktiven Elemente hinweg?" (Konsistenz)
- ✅ „Sind Barrierefreiheitsanforderungen für die Tastaturnavigation definiert?" (Abdeckung)
- ✅ „Definiert das Lastenheft, was passiert, wenn das Logo-Bild nicht geladen werden kann?" (Randfälle)
Metapher: Wenn Ihr Lastenheft in Englisch geschriebener Code ist, ist die Checkliste seine Unit-Test-Suite. Sie testen, ob die Anforderungen gut geschrieben, vollständig, eindeutig und implementierungsbereit sind – NICHT, ob die Implementierung funktioniert.
Eigentum und Checkbox-Lebenszyklus:
- Vom Befehl generierte benutzerdefinierte Checklisten sind vom Prüfer verwaltete Qualitätsüberprüfungsartefakte für Anforderungen.
[x]bedeutet, dass der Prüfer festgestellt hat, dass das Kriterium für die Anforderungsqualität erfüllt ist.[x]bedeutet NICHT, dass die Implementierungsarbeit abgeschlossen ist.- Dieser Befehl generiert oder hängt Checklistenelemente an; er DARF generierte Elemente NICHT als
[x]markieren. - Ein Agent darf nur dann bei der Bewertung von Elementen helfen, wenn der Prüfer dies explizit verlangt.
checklists/requirements.mdist eine separate eingebaute Checkliste für die Lastenheftqualität, die von/speckit-specifyund/speckit-clarifyverwaltet wird; behandeln Sie diese Ausnahme nicht als auf benutzerdefinierte Checklisten anwendbar.
Benutzereingabe
$ARGUMENTS
Sie MÜSSEN die Benutzereingabe berücksichtigen, bevor Sie fortfahren (falls nicht leer).
Vorausführungsprüfungen
Prüfung auf Erweiterungs-Hooks (vor Checklistengenerierung):
- Überprüfen Sie, ob
.specify/extensions.ymlim Projektstammverzeichnis existiert. - Wenn es existiert, lesen Sie es und suchen Sie nach Einträgen unter dem Schlüssel
hooks.before_checklist - Wenn das YAML nicht geparst werden kann oder ungültig ist, überspringen Sie es nicht stillschweigend: Teilen Sie dem Benutzer mit, dass
.specify/extensions.ymlnicht gelesen werden konnte (geben Sie den Parser-Fehler an) und dass keine Hooks überprüft wurden, einschließlich aller dort registrierten obligatorischen (optional: false) Hooks, und fahren Sie dann normal fort - Filtern Sie Hooks heraus, bei denen
enabledexplizitfalseist. Behandeln Sie Hooks ohne einenabled-Feld als standardmäßig aktiviert. - Versuchen Sie für jeden verbleibenden Hook nicht, Hook-
condition-Ausdrücke zu interpretieren oder auszuwerten:- Wenn der Hook kein
condition-Feld hat oder dieses null/leer ist, behandeln Sie den Hook als ausführbar - Wenn der Hook eine nicht leere
conditiondefiniert, überspringen Sie den Hook und überlassen Sie die Bedingungsauswertung der HookExecutor-Implementierung
- Wenn der Hook kein
- Ersetzen Sie beim Erstellen von Befehlsaufrufen aus Hook-Befehlsnamen Punkte (
.) durch Bindestriche (-). Beispiel:speckit.git.commit→/speckit-git-commit. - Geben Sie für jeden ausführbaren Hook basierend auf seinem
optional-Flag Folgendes aus:- Optionaler Hook (
optional: true):## Erweiterungs-Hooks **Optionaler Pre-Hook**: {extension} Befehl: `/{command}` Beschreibung: {description} Aufforderung: {prompt} Zur Ausführung: `/{command}` - Obligatorischer Hook (
optional: false):
Nach dem Ausgeben des obigen Blocks MÜSSEN Sie den Hook tatsächlich aufrufen und auf sein Ende warten, bevor Sie fortfahren. Führen Sie ihn so aus, wie Sie den Befehl selbst in diesem Agenten/Session ausführen würden (der Aufruf kann von der oben gezeigten literalen## Erweiterungs-Hooks **Automatischer Pre-Hook**: {extension} Ausführung: `/{command}` EXECUTE_COMMAND: {command} Warten Sie auf das Ergebnis des Hook-Befehls, bevor Sie mit den Ausführungsschritten fortfahren.{command}-ID abweichen, z. B. führt ein Skills-Modus-Agent ihn als/skill:speckit-...oder$speckit-...aus). Das bloße Ausgeben des Blocks führt den Hook nicht aus.
- Optionaler Hook (
- Wenn keine Hooks registriert sind oder
.specify/extensions.ymlnicht existiert, stillschweigend überspringen
Ausführungsschritte
-
Einrichtung: Führen Sie
.specify/scripts/bash/check-prerequisites.sh --json --template checklist-templatevom Repository-Stammverzeichnis aus und parsen Sie JSON nach FEATURE_DIR, AVAILABLE_DOCS-Liste und TEMPLATE_CONTENT.- Alle Dateipfade müssen absolut sein.
- Verwenden Sie für einfache Anführungszeichen in Argumenten wie „I'm Groot" die Escape-Syntax: z. B. 'I'''m Groot' (oder doppelte Anführungszeichen, wenn möglich: "I'm Groot").
-
WENN VORHANDEN: Laden Sie
.specify/memory/constitution.mdfür Projektprinzipien und Governance-Einschränkungen. -
Absicht klären (dynamisch): Leiten Sie bis zu DREI einleitende kontextbezogene Klärungsfragen ab (kein vorgefertigter Katalog). Sie MÜSSEN:
- Aus der Formulierung des Benutzers und extrahierten Signalen aus dem Lastenheft/Plan/Aufgaben generiert werden
- Nur nach Informationen fragen, die den Checklisteninhalt wesentlich ändern
- Einzeln übersprungen werden, wenn sie bereits in
$ARGUMENTSeindeutig sind - Präzision vor Breite bevorzugen
Generierungsalgorithmus:
- Signale extrahieren: Domänenschlüsselwörter der Funktion (z. B. Auth, Latenz, UX, API), Risikoindikatoren („kritisch", „muss", „Compliance"), Stakeholder-Hinweise („QA", „Review", „Sicherheitsteam") und explizite Liefergegenstände („a11y", „Rollback", „Verträge").
- Signale in Kandidaten-Fokusbereiche (max. 4) gruppieren, nach Relevanz geordnet.
- Wahrscheinliche Zielgruppe und Zeitpunkt (Autor, Prüfer, QA, Release) identifizieren, falls nicht explizit.
- Fehlende Dimensionen erkennen: Umfang der Breite, Tiefe/Strenge, Risikoschwerpunkt, Ausgrenzungsgrenzen, messbare Abnahmekriterien.
- Fragen aus diesen Archetypen formulieren:
- Umfangsverfeinerung (z. B. „Soll dies Integrationskontaktpunkte mit X und Y umfassen oder auf die Korrektheit des lokalen Moduls beschränkt bleiben?")
- Risikopriorisierung (z. B. „Welche dieser potenziellen Risikobereiche sollten obligatorische Gate-Prüfungen erhalten?")
- Tiefenkalibrierung (z. B. „Ist dies eine einfache Pre-Commit-Sanity-Liste oder ein formelles Release-Gate?")
- Zielgruppen-Framing (z. B. „Wird dies nur vom Autor oder von Kollegen während des PR-Reviews verwendet?")
- Grenzausschluss (z. B. „Sollen Leistungsoptimierungspunkte in dieser Runde explizit ausgeschlossen werden?")
- Szenarioklassenlücke (z. B. „Keine Wiederherstellungsabläufe erkannt – sind Rollback-/Teilfehlerpfade im Umfang enthalten?")
Formatierungsregeln für Fragen:
- Wenn Optionen präsentiert werden, generieren Sie eine kompakte Tabelle mit den Spalten: Option | Kandidat | Warum es wichtig ist
- Auf maximal A–E Optionen begrenzen; Tabelle weglassen, wenn eine Freitextantwort klarer ist
- Fragen Sie den Benutzer nie, das zu wiederholen, was er bereits gesagt hat
- Vermeiden Sie spekulative Kategorien (keine Halluzinationen). Bei Unsicherheit explizit fragen: „Bestätigen Sie, ob X zum Umfang gehört."
Standardeinstellungen, wenn Interaktion unmöglich ist:
- Tiefe: Standard
- Zielgruppe: Prüfer (PR), wenn codebezogen; andernfalls Autor
- Fokus: Top 2 Relevanzcluster
Geben Sie die Fragen aus (kennzeichnen Sie sie als Q1/Q2/Q3). Nach Antworten: Wenn ≥2 Szenarioklassen (Alternativ / Ausnahme / Wiederherstellung / Nicht-funktionaler Bereich) weiterhin unklar sind, dürfen Sie bis zu ZWEI weitere gezielte Folgefragen (Q4/Q5) mit einer einzeiligen Begründung stellen (z. B. „Ungelöstes Wiederherstellungspfadrisiko"). Überschreiten Sie insgesamt fünf Fragen nicht. Überspringen Sie die Eskalation, wenn der Benutzer explizit weitere Fragen ablehnt.
-
Benutzeranfrage verstehen: Kombinieren Sie
$ARGUMENTS+ Klärungsantworten:- Checklisten-Thema ableiten (z. B. Sicherheit, Review, Deployment, UX)
- Explizite vom Benutzer genannte Muss-Elemente konsolidieren
- Fokusauswahlen auf Kategoriengerüst abbilden
- Fehlenden Kontext aus Lastenheft/Plan/Aufgaben ableiten (NICHT halluzinieren)
-
Funktionskontext laden: Aus FEATURE_DIR lesen:
- spec.md: Funktionsanforderungen und Umfang
- plan.md (falls vorhanden): Technische Details, Abhängigkeiten
- tasks.md (falls vorhanden): Implementierungsaufgaben
Kontextladestrategie:
- Nur notwendige Teile laden, die für aktive Fokusbereiche relevant sind (vollständiges Datei-Dumping vermeiden)
- Lange Abschnitte bevorzugt in prägnante Szenario-/Anforderungsaufzählungspunkte zusammenfassen
- Progressive Offenlegung verwenden: Nur bei erkannten Lücken zusätzlichen Abruf hinzufügen
- Bei großen Quelldokumenten Zwischenzusammenfassungselemente generieren, anstatt Rohtext einzubetten
-
Checkliste generieren - TEMPLATE_CONTENT als strukturelle Vorlage verwenden und „Unit-Tests für Anforderungen" erstellen:
FEATURE_DIR/checklists/-Verzeichnis erstellen, falls nicht vorhanden- Eindeutigen Checklisten-Dateinamen generieren:
- Kurzen, beschreibenden Namen basierend auf der Domäne verwenden (z. B.
ux.md,api.md,security.md) - Format:
[domain].md
- Kurzen, beschreibenden Namen basierend auf der Domäne verwenden (z. B.
- Dateiverhalten:
- Wenn Datei NICHT existiert: Neue Datei erstellen und Elemente ab CHK001 nummerieren
- Wenn Datei existiert: Neue Elemente an vorhandene Datei anhängen, beginnend mit der letzten CHK-ID (z. B. wenn letztes Element CHK015 ist, neue Elemente bei CHK016 beginnen)
- Vorhandenen Checklisteninhalt niemals löschen oder ersetzen – immer erhalten und anhängen
- Jedes neu generierte Element ungeprüft lassen (
[ ]); der Checkbox-Status gehört dem Prüfer
KERNPRINZIP - Testen Sie die Anforderungen, nicht die Implementierung: Jedes Checklistenelement MUSS die ANFORDERUNGEN SELBST auf Folgendes prüfen:
- Vollständigkeit: Sind alle notwendigen Anforderungen vorhanden?
- Klarheit: Sind Anforderungen eindeutig und spezifisch?
- Konsistenz: Stimmen die Anforderungen untereinander überein?
- Messbarkeit: Können Anforderungen objektiv verifiziert werden?
- Abdeckung: Werden alle Szenarien/Randfälle adressiert?
Kategoriestruktur - Elemente nach Anforderungsqualitätsdimensionen gruppieren:
- Anforderungsvollständigkeit (Sind alle notwendigen Anforderungen dokumentiert?)
- Anforderungsklarheit (Sind Anforderungen spezifisch und eindeutig?)
- Anforderungskonsistenz (Stimmen Anforderungen ohne Konflikte überein?)
- Qualität der Abnahmekriterien (Sind Erfolgskriterien messbar?)
- Szenarioabdeckung (Sind alle Abläufe/Fälle adressiert?)
- Randfallabdeckung (Sind Grenzbedingungen definiert?)
- Nicht-funktionale Anforderungen (Leistung, Sicherheit, Barrierefreiheit usw. – sind sie spezifiziert?)
- Abhängigkeiten und Annahmen (Sind sie dokumentiert und validiert?)
- Mehrdeutigkeiten und Konflikte (Was ist zu klären?)
WIE CHECKLISTENELEMENTE GESCHRIEBEN WERDEN – „Unit-Tests für Anforderungen":
❌ FALSCH (Implementierung testen):
- „Überprüfen, ob die Landingpage 3 Episodenkarten anzeigt"
- „Testen, ob Hover-Zustände auf dem Desktop funktionieren"
- „Bestätigen, dass der Logo-Klick zur Startseite navigiert"
✅ RICHTIG (Anforderungsqualität testen):
- „Sind die genaue Anzahl und das Layout der vorgestellten Episoden spezifiziert?" [Vollständigkeit]
- „Ist ‚prominente Darstellung' mit spezifischen Größen-/Positionierungsangaben quantifiziert?" [Klarheit]
- „Sind Hover-Zustandsanforderungen konsistent über alle interaktiven Elemente hinweg?" [Konsistenz]
- „Sind Anforderungen für die Tastaturnavigation für alle interaktiven UI definiert?" [Abdeckung]
- „Ist das Fallback-Verhalten spezifiziert, wenn das Logo-Bild nicht geladen werden kann?" [Randfälle]
- „Sind Ladezustände für asynchrone Episodendaten definiert?" [Vollständigkeit]
- „Definiert das Lastenheft die visuelle Hierarchie für konkurrierende UI-Elemente?" [Klarheit]
ELEMENTSTRUKTUR: Jedes Element sollte diesem Muster folgen:
- Frageformat, das nach der Anforderungsqualität fragt
- Fokus auf das, was GESCHRIEBEN ist (oder nicht geschrieben) im Lastenheft/Plan
- Qualitätsdimension in Klammern angeben [Vollständigkeit/Klarheit/Konsistenz/usw.]
- Lastenheftabschnitt referenzieren
[Spec §X.Y]beim Prüfen vorhandener Anforderungen - Marker
[Lücke]verwenden, wenn auf fehlende Anforderungen geprüft wird
BEISPIELE NACH QUALITÄTSDIMENSION:
Vollständigkeit:
- "Sind Fehlerbehandlungsanforderungen für alle API-Fehlermodi definiert? [Lücke]"
- "Sind Barrierefreiheitsanforderungen für alle interaktiven Elemente spezifiziert? [Vollständigkeit]"
- "Sind mobile Breakpoint-Anforderungen für responsive Layouts definiert? [Lücke]"
Klarheit:
- "Ist ‚schnelles Laden' mit spezifischen Zeitschwellen quantifiziert? [Klarheit, Spec §NFR-2]"
- "Sind Auswahlkriterien für ‚zugehörige Episoden' explizit definiert? [Klarheit, Spec §FR-5]"
- "Ist ‚prominent' mit messbaren visuellen Eigenschaften definiert? [Mehrdeutigkeit, Spec §FR-4]"
Konsistenz:
- "Stimmen die Navigationsanforderungen auf allen Seiten überein? [Konsistenz, Spec §FR-10]"
- "Sind die Anforderungen an die Kartenkomponente zwischen Landing- und Detailseiten konsistent? [Konsistenz]"
Abdeckung:
- "Sind Anforderungen für Null-Zustandsszenarien (keine Episoden) definiert? [Abdeckung, Randfall]"
- "Werden gleichzeitige Benutzerinteraktionsszenarien adressiert? [Abdeckung, Lücke]"
- "Sind Anforderungen für partielle Datenladefehler spezifiziert? [Abdeckung, Ausnahmefluss]"
Messbarkeit:
- "Sind Anforderungen an die visuelle Hierarchie messbar/testbar? [Abnahmekriterien, Spec §FR-1]"
- "Kann ‚ausgewogenes visuelles Gewicht' objektiv verifiziert werden? [Messbarkeit, Spec §FR-2]"
Szenarioklassifikation und -abdeckung (Fokus auf Anforderungsqualität):
- Prüfen, ob Anforderungen für folgende Szenarien existieren: Primär, Alternativ, Ausnahme/Fehler, Wiederherstellung, Nicht-funktional
- Für jede Szenarioklasse fragen: „Sind [Szenariotyp]-Anforderungen vollständig, klar und konsistent?"
- Wenn Szenarioklasse fehlt: „Wurden [Szenariotyp]-Anforderungen absichtlich ausgeschlossen oder fehlen sie? [Lücke]"
- Resilienz/Rollback einbeziehen, wenn Zustandsänderungen auftreten: "Sind Rollback-Anforderungen für Migrationsfehler definiert? [Lücke]"
Rückverfolgbarkeitsanforderungen:
- MINIMUM: ≥80 % der Elemente MÜSSEN mindestens eine Rückverfolgbarkeitsreferenz enthalten
- Jedes Element sollte referenzieren: Lastenheftabschnitt
[Spec §X.Y], oder Marker verwenden:[Lücke],[Mehrdeutigkeit],[Konflikt],[Annahme] - Wenn kein ID-System existiert: "Ist ein Schema für Anforderungs- und Abnahmekriterien-IDs etabliert? [Rückverfolgbarkeit]"
Probleme aufdecken und lösen (Probleme mit der Anforderungsqualität): Fragen zu den Anforderungen selbst stellen:
- Mehrdeutigkeiten: "Ist der Begriff ‚schnell' mit spezifischen Metriken quantifiziert? [Mehrdeutigkeit, Spec §NFR-1]"
- Konflikte: "Stehen Navigationsanforderungen zwischen §FR-10 und §FR-10a im Konflikt? [Konflikt]"
- Annahmen: "Ist die Annahme einer ‚immer verfügbaren Podcast-API' validiert? [Annahme]"
- Abhängigkeiten: "Sind Abhängigkeiten von externen Diensten dokumentiert? [Lücke]"