Benutzereingabe
$ARGUMENTS
Sie MÜSSEN die Benutzereingabe berücksichtigen, bevor Sie fortfahren (sofern nicht leer).
Vorab-Prüfungen
Überprüfung auf Erweiterungs-Hooks (vor der Klärung):
- Prü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_clarify. - 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 (inklusive des Parser-Fehlers) und dass keine Hooks geprü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 ohneenabled-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 (-). Zum 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} Prompt: {prompt} Zur Ausführung: `/{command}` - Obligatorischer Hook (
optional: false):
Nach dem Ausgeben des obigen Blocks MÜSSEN Sie den Hook tatsächlich aufrufen und darauf warten, dass er abgeschlossen ist, bevor Sie fortfahren. Führen Sie ihn genauso 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 der Gliederung 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, überspringen Sie stillschweigend.
Gliederung
Ziel: Erkennen und reduzieren Sie Unklarheiten oder fehlende Entscheidungspunkte in der aktiven Funktionsspezifikation und zeichnen Sie die Klärungen direkt in der Spezifikationsdatei auf.
Hinweis: Dieser Klärungsablauf soll VOR dem Aufruf von /speckit-plan ausgeführt (und abgeschlossen) werden. Wenn der Benutzer ausdrücklich angibt, dass er die Klärung überspringt (z. B. explorativer Spike), dürfen Sie fortfahren, müssen aber davor warnen, dass das Risiko von Nacharbeiten im weiteren Verlauf steigt.
Ausführungsschritte:
-
Führen Sie
.specify/scripts/bash/check-prerequisites.sh --json --paths-onlygenau einmal vom Repository-Stammverzeichnis aus (im kombinierten Modus--json --paths-only/-Json -PathsOnly). Parsen Sie minimale JSON-Nutzdatenfelder:FEATURE_DIRFEATURE_SPEC- (Optional
IMPL_PLAN,TASKSfür zukünftige verkettete Abläufe erfassen.) - Wenn das JSON-Parsing fehlschlägt, brechen Sie ab und weisen Sie den Benutzer an,
/speckit-specifyerneut auszuführen oder die Feature-Branch-Umgebung zu überprüfen. - 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").
-
FALLS VORHANDEN: Laden Sie
.specify/memory/constitution.mdfür Projektprinzipien und Governance-Einschränkungen. -
Laden Sie die aktuelle Spezifikationsdatei. Führen Sie eine strukturierte Analyse auf Unklarheiten und Abdeckung unter Verwendung dieser Taxonomie durch. Markieren Sie für jede Kategorie den Status: Klar / Teilweise / Fehlend. Erstellen Sie eine interne Abdeckungskarte für die Priorisierung (geben Sie die Rohkarte nur aus, wenn keine Fragen gestellt werden).
Funktionaler Umfang & Verhalten:
- Kernbenutzerziele & Erfolgskriterien
- Explizite Out-of-Scope-Deklarationen
- Benutzerrollen / Personas-Differenzierung
Domäne & Datenmodell:
- Entitäten, Attribute, Beziehungen
- Identitäts- & Eindeutigkeitsregeln
- Lebenszyklus-/Zustandsübergänge
- Datenvolumen / Skalierungsannahmen
Interaktion & Benutzererfahrungsfluss:
- Kritische Benutzerreisen / Sequenzen
- Fehler-/Leer-/Ladezustände
- Barrierefreiheits- oder Lokalisierungshinweise
Nicht-funktionale Qualitätsattribute:
- Leistung (Latenz, Durchsatzziele)
- Skalierbarkeit (horizontal/vertikal, Grenzen)
- Zuverlässigkeit & Verfügbarkeit (Betriebszeit, Wiederherstellungserwartungen)
- Beobachtbarkeit (Logging, Metriken, Tracing-Signale)
- Sicherheit & Datenschutz (Authentifizierung/Autorisierung, Datenschutz, Bedrohungsannahmen)
- Compliance / regulatorische Einschränkungen (falls vorhanden)
Integration & externe Abhängigkeiten:
- Externe Dienste/APIs und Fehlermodi
- Datenimport-/Exportformate
- Protokoll-/Versionierungsannahmen
Randfälle & Fehlerbehandlung:
- Negative Szenarien
- Ratenbegrenzung / Drosselung
- Konfliktlösung (z. B. gleichzeitige Bearbeitungen)
Einschränkungen & Abwägungen:
- Technische Einschränkungen (Sprache, Speicher, Hosting)
- Explizite Abwägungen oder abgelehnte Alternativen
Terminologie & Konsistenz:
- Kanonische Glossarbegriffe
- Vermiedene Synonyme / veraltete Begriffe
Abschlusssignale:
- Testbarkeit der Abnahmekriterien
- Messbare Definition of Done-artige Indikatoren
Sonstiges / Platzhalter:
- TODO-Markierungen / ungelöste Entscheidungen
- Mehrdeutige Adjektive („robust“, „intuitiv“) ohne Quantifizierung
Fügen Sie für jede Kategorie mit dem Status Teilweise oder Fehlend eine potenzielle Frage hinzu, es sei denn:
- Die Klärung würde die Implementierungs- oder Validierungsstrategie nicht wesentlich ändern.
- Der Punkt betrifft speziell die Implementierungsmethode, den Technologievergleich oder die Aufgabenaufteilung (intern notieren).
-
Erstellen Sie (intern) eine priorisierte Warteschlange potenzieller Klärungsfragen (maximal 5). Geben Sie sie NICHT auf einmal aus. Wenden Sie diese Einschränkungen an:
- Maximal 5 Fragen insgesamt über die gesamte Sitzung.
- Jede Frage muss mit ENTWEDER einer kurzen Multiple-Choice-Auswahl (2–5 sich gegenseitig ausschließende Optionen) ODER einer einwortigen/kurzen Antwort beantwortet werden können (explizit einschränken: „Antwort in <=5 Wörtern“).
- Fügen Sie nur Fragen ein, deren Antworten die Architektur, das Datenmodell, die Aufgabenzerlegung, das Testdesign, das UX-Verhalten, die Betriebsbereitschaft oder die Compliance-Validierung wesentlich beeinflussen.
- Stellen Sie eine ausgewogene Kategorieabdeckung sicher: Versuchen Sie, zuerst die unwesentlichsten ungelösten Kategorien mit der höchsten Auswirkung abzudecken; vermeiden Sie es, zwei Fragen mit geringer Auswirkung zu stellen, wenn ein einzelner Bereich mit hoher Auswirkung (z. B. Sicherheitslage) ungelöst ist.
- Schließen Sie bereits beantwortete Fragen, triviale stilistische Vorlieben oder planbezogene Ausführungsdetails aus (es sei denn, sie blockieren die Korrektheit).
- Bevorzugen Sie Klärungen, die das Risiko von Nacharbeiten im weiteren Verlauf verringern oder falsch ausgerichtete Abnahmetests verhindern.
- Wenn mehr als 5 Kategorien ungelöst bleiben, wählen Sie die Top 5 nach der Heuristik (Auswirkung * Unsicherheit).
-
Sequenzielle Fragerunde (interaktiv):
-
Präsentieren Sie EXAKT EINE Frage pro Mal.
-
Fragenformulierung (gilt für jede Frage, MC oder Kurzantwort):
- Beginnen Sie mit
**Frage:**gefolgt von einem vollständigen Fragesatz, der mit?endet. Der Fragetext vor dem?muss für sich allein sinnvoll sein. - Verwenden Sie NIEMALS eine Themenbezeichnung, eine Abschnittsüberschrift oder eine Anforderungs-ID als Frage selbst. Beispielsweise ist
Akzeptanz-Geräte-/Laufzeitmatrix (FR-023)UNGÜLTIG – es ist eine Bezeichnung, keine Frage. - Nach dem
?ist das einzige zulässige Suffix eine optionale parenthetische Anforderungs-/Fragen-ID. Exaktes Format:**Frage:** <Fragesatz>?oder**Frage:** <Fragesatz>? (FR-023). Setzen Sie die ID niemals vor das?und verwenden Sie niemals die ID (allein oder mit einer Themenbezeichnung) als gesamten Prompt. - Fügen Sie unmittelbar nach der Fragenzeile einen Satz in einfacher Sprache hinzu, der erklärt, „warum es wichtig ist“ (das Risiko für die Abnahme oder Auslieferung), bevor Sie die Empfehlung/Optionen geben.
- Verwenden Sie alltägliche Formulierungen; führen Sie Fachjargon nur ein, wenn er im selben Satz definiert wird. Selbstprüfung: Ein Leser, der Spec Kit nicht kennt, muss die Frage allein anhand der Fragenzeile beantworten können. Knappheit ist in Ordnung; kryptische Bezeichnungen nicht.
- Beginnen Sie mit
-
Bei Multiple-Choice-Fragen:
- Analysieren Sie alle Optionen und bestimmen Sie die am besten geeignete Option basierend auf:
- Best Practices für den Projekttyp
- Häufigen Mustern in ähnlichen Implementierungen
- Risikominimierung (Sicherheit, Leistung, Wartbarkeit)
- Übereinstimmung mit expliziten Projektzielen oder in der Spezifikation sichtbaren Einschränkungen
- Präsentieren Sie Ihre empfohlene Option prominent oben mit einer klaren Begründung (1-2 Sätze, die erklären, warum dies die beste Wahl ist).
- Formatieren Sie als:
**Empfohlen:** Option [X] - <Begründung> - Rendern Sie dann alle Optionen als Markdown-Tabelle:
Option Beschreibung A B C (bei Bedarf D/E bis zu 5 hinzufügen) Kurz Geben Sie eine andere kurze Antwort (<=5 Wörter) (Nur einfügen, wenn eine freie Alternative angemessen ist) - Fügen Sie nach der Tabelle hinzu:
Sie können mit dem Optionsbuchstaben antworten (z. B. „A“), die Empfehlung annehmen, indem Sie „ja“ oder „empfohlen“ sagen, oder Ihre eigene kurze Antwort geben.
- Analysieren Sie alle Optionen und bestimmen Sie die am besten geeignete Option basierend auf:
-
Bei Kurzantwort-Stil (keine sinnvollen diskreten Optionen):
- Geben Sie Ihre vorgeschlagene Antwort basierend auf Best Practices und Kontext.
- Formatieren Sie als:
**Vorgeschlagen:** <Ihr Lösungsvorschlag> - <kurze Begründung> - Geben Sie dann aus:
Format: Kurze Antwort (<=5 Wörter). Sie können den Vorschlag annehmen, indem Sie „ja“ oder „vorgeschlagen“ sagen, oder Ihre eigene Antwort geben.
-
Nachdem der Benutzer antwortet:
- Wenn der Benutzer mit „ja“, „empfohlen“ oder „vorgeschlagen“ antwortet, verwenden Sie Ihre zuvor genannte Empfehlung/den Vorschlag als Antwort.
- Andernfalls validieren Sie, dass die Antwort einer Option entspricht oder die Einschränkung von <=5 Wörtern erfüllt.
- Bei Unklarheit bitten Sie um eine kurze Klarstellung (zählt immer noch zur selben Frage; nicht weitergehen).
- Sobald die Antwort zufriedenstellend ist, zeichnen Sie sie im Arbeitsspeicher auf (noch nicht auf die Festplatte schreiben) und fahren Sie mit der nächsten Frage in der Warteschlange fort.
-
Hören Sie auf, weitere Fragen zu stellen, wenn:
- Alle kritischen Unklarheiten frühzeitig gelöst wurden (verbleibende Elemente in der Warteschlange werden unnötig), ODER
- Der Benutzer den Abschluss signalisiert („fertig“, „gut“, „keine mehr“), ODER
- Sie 5 gestellte Fragen erreicht haben.
-
Geben Sie niemals zukünftige Fragen in der Warteschlange im Voraus preis.
-
Wenn zu Beginn keine gültigen Fragen vorhanden sind, melden Sie sofort, dass keine kritischen Unklarheiten bestehen.
-
-
Integration nach JEDER akzeptierten Antwort (inkrementeller Ansatz):
- Behalten Sie die Spezifikation im Speicher (einmal zu Beginn geladen) zusammen mit den rohen Dateiinhalten.
- Für die erste integrierte Antwort in dieser Sitzung:
- Stellen Sie sicher, dass ein Abschnitt
## Klärungenexistiert (erstellen Sie ihn direkt nach dem übergeordneten Kontext-/Übersichtsabschnitt gemäß der Spezifikationsvorlage, falls nicht vorhanden). - Erstellen Sie darunter (falls nicht vorhanden) eine
### Sitzung YYYY-MM-DD-Unterüberschrift für heute.
- Stellen Sie sicher, dass ein Abschnitt
- Fügen Sie unmittelbar nach der Annahme eine Aufzählungszeile hinzu:
- F: <Frage> → A: <endgültige Antwort>. - Wenden Sie dann die Klärung sofort auf den/die am besten geeigneten Abschnitt(e) an:
- Funktionale Unklarheit → Aktualisieren oder fügen Sie einen Aufzählungspunkt in den Funktionale Anforderungen hinzu.
- Benutzerinteraktion / Akteursunterscheidung → Aktualisieren Sie den Unterabschnitt Benutzergeschichten oder Akteure (falls vorhanden) mit der geklärten Rolle, Einschränkung oder Szenario.
- Datenform / Entitäten → Aktualisieren Sie das Datenmodell (fügen Sie Felder, Typen, Beziehungen hinzu) unter Beibehaltung der Sortierung; notieren Sie hinzugefügte Einschränkungen prägnant.
- Nicht-funktionale Einschränkung → Fügen Sie messbare Kriterien in den Erfolgskriterien > Messbare Ergebnisse hinzu/ändern Sie sie (konvertieren Sie vage Adjektive in Metriken oder explizite Ziele).
- Randfall / negativer Ablauf → Fügen Sie einen neuen Aufzählungspunkt unter Randfälle / Fehlerbehandlung hinzu (oder erstellen Sie einen solchen Unterabschnitt, wenn die Vorlage einen Platzhalter dafür vorsieht).
- Terminologiekonflikt → Normalisieren Sie den Begriff in der gesamten Spezifikation; behalten Sie das Original nur bei, wenn nötig, indem Sie einmal „(früher bezeichnet als „X“)“ hinzufügen.
- Wenn die Klärung eine frühere mehrdeutige Aussage ungültig macht, ersetzen Sie diese Aussage, anstatt sie zu duplizieren; hinterlassen Sie keinen veralteten widersprüchlichen Text.
- Speichern Sie die Spezifikationsdatei NACH jeder Integration, um das Risiko von Kontextverlust zu minimieren (atomares Überschreiben).
- Bewahren Sie die Formatierung: Ordnen Sie nicht zugehörige Abschnitte nicht neu an; halten Sie die Überschriftenhierarchie intakt.
- Halten Sie jede eingefügte Klärung minimal und testbar (vermeiden Sie narrative Abschweifungen).
-
Validierung (durchgeführt nach JEDEM Schreibvorgang und abschließend):
- Der Abschnitt Klärungen enthält genau einen Aufzählungspunkt pro akzeptierter Antwort (keine Duplikate).
- Gesamtzahl der gestellten (akzeptierten) Fragen ≤ 5.
- Aktualisierte Abschnitte enthalten keine verbleibenden vagen Platzhalter, die die neue Antwort lösen sollte.
- Es bleibt keine widersprüchliche frühere Aussage bestehen (scannen Sie nach jetzt ungültigen alternativen Entscheidungen, die entfernt wurden).
- Markdown-Struktur gültig; nur zulässige neue Überschriften:
## Klärungen,### Sitzung YYYY-MM-DD. - Terminologiekonsistenz: derselbe kanonische Begriff wird in allen aktualisierten Abschnitten verwendet.
-
Schreiben Sie die aktualisierte Spezifikation zurück in
FEATURE_SPEC. -
Spezifikationsqualitäts-Checkliste erneut validieren (falls vorhanden):
- Prüfen Sie, ob
FEATURE_DIR/checklists/requirements.mdexistiert. - Wenn es NICHT existiert, überspringen Sie diesen Schritt stillschweigend.
- Wenn es existiert:
- Lesen Sie die Checklistendatei.
- Identifizieren Sie alle GitHub-Task-List-Kontrollkästchenzeilen – Zeilen, die
- [ ],- [x]oder- [X]entsprechen (Groß-/Kleinschreibung nicht beachtend, tolerant gegenüber führenden Leerzeichen für verschachtelte Elemente) außerhalb von Code-Blöcken. Ignorieren Sie alle anderen Inhalte (Überschriften, Notizen, Nicht-Kontrollkästchen-Aufzählungspunkte, Metadaten). - Zeichnen Sie für jede Kontrollkästchenzeile ihren aktuellen Markierungsstatus (markiert oder nicht markiert) und den Elementtext in einer Vorher-Snapshot-Liste auf.
- Bewerten Sie jedes Kontrollkästchenelement erneut anhand der aktualisierten Spezifikation (der in Schritt 7 gerade gespeicherten Version).
- Aktualisieren Sie für jedes Kontrollkästchenelement nur, wenn sich der markierte/nicht-markierte Zustand tatsächlich ändert:
- Wenn das Element jetzt besteht und nicht markiert war: ändern Sie
[ ]in[x]. - Wenn das Element jetzt fehlschlägt und markiert war: ändern Sie
[x]/[X]in[ ]. - Wenn der Zustand unverändert ist: belassen Sie ihn.
- Wenn das Element jetzt besteht und nicht markiert war: ändern Sie
- Prüfen Sie, ob
[... für die Übersetzung gekürzt]