RaamPrashathT/spec-it

Was macht spec-it?

Verwandle $ARGUMENTS in eine Spezifikation, die ein Coding-Agent ohne Rückfragen umsetzen kann, plus Mockups, die jede Anforderung und jeden Grenzfall abbilden.

Idee → 1. Kontext (keine Fragen) → 2. Produktfragen → 3. Technische Fragen
     → 4. REQUIREMENTS.md → 5. Mockups → 6. Prüfung

Pfade wie references/… sind relativ zu ${CLAUDE_SKILL_DIR}. Die Ausgabe erfolgt nach spec-it/<kebab-name>/:

spec-it/<name>/
├── REQUIREMENTS.md      die eine Ausgabe: Absicht, Entscheidungen, Phasen, FRs, ECs, Annahmen
└── mockups/             index.html + screens, oder api.html + openapi.yaml, oder cli.html + transcripts.md
    └── assets/          theme.css, fixtures.js, app.js

Regeln

1. Fakten sind deine Sache, Entscheidungen sind ihre Sache. Frage nie, was das Repository, angehängte Dateien, das Web oder ein Standard beantworten kann. Lege nie den Umfang, Prioritäten oder Kompromisse für den Entwickler fest.
2. Jede Frage muss ihren Platz verdienen. Führe das Frage-Gate in references/questions.md vor jeder Frage aus. Ein Detail mit einer vertretbaren Standardeinstellung ist eine Annahme (A-n), keine Frage.
3. Kein Kontingent. Es gibt kein Minimum. Typische Durchläufe stellen 5–12 Fragen. Höre auf, wenn du die nächsten Antworten des Entwicklers vorhersagen kannst.
4. Frage über den Picker (AskUserQuestion; einfacher nummerierter Text ohne ihn). Bis zu 3 unabhängige Fragen pro Aufruf; fasse nie eine Frage zusammen, deren Optionen von einer anderen unbeantworteten Frage abhängen.
5. Jede Frage wird einmal gezeigt, als das Letzte in deiner Nachricht. Keine Zusammenfassung danach.
6. Schreibe den Zustand auf die Festplatte. Führe nach dem Kontextschritt REQUIREMENTS.md als Arbeitsdatei: skizziere §1–2 früh, fülle Entscheidungen nach, sobald sie getroffen sind. Nach einer Kontextkomprimierung lies sie erneut, bevor du handelst.
7. Mockups funktionieren offline. Kein CDN, Netzwerk oder Web-Fonts.
8. Das Prüfskript verriegelt den Abschluss: node ${CLAUDE_SKILL_DIR}/scripts/check.mjs spec-it/<name> beendet mit 0.

IDs: FR-n Anforderung, EC-n Grenzfall, D-n Entscheidung, A-n Annahme. Mit Modulen erhalten FR/EC/A einen Modul-Präfix (BOOK-FR-3). IDs sind permanent: nie umnummerieren; mit "(entfernt)" ausmustern.

1. Kontext (noch keine Fragen)

Führe dies durch, bevor du etwas fragst. Führe beide Suchläufe parallel aus, mit frischen Kontext-Unteragenten, wenn verfügbar:

• Codebasis-Scan (überspringe, wenn der Ordner leer ist): Stack, bestehende Funktionen, die die Idee überschneiden, Datenmodelle, Authentifizierung, UI-Kit und Design-Tokens, API- und CLI-Konventionen, alles Halbfertige. Maximal 25 Zeilen zurück.
• Stand-der-Technik-Scan (Websuche, 2–4 Suchen): wie 2–3 etablierte Produkte oder Standards dies lösen; die bekannten harten Probleme des Fachgebiets (die Dinge, die im echten Einsatz schiefgehen); das Standard-Feature-Set; alle relevanten Spezifikationen (RFC, clig.dev, WCAG, Zahlungs- oder Datenschutzregeln). Maximal 25 Zeilen zurück, mit Quellenlinks.

Zeige dem Entwickler dann eine Kontextübersicht, maximal 15 Zeilen:

Was ich gefunden habe
- Repo: <was existiert, das dies berührt oder wiederverwendet>
- Wie andere es machen: <Produkt A macht X, Produkt B macht Y>
- Harte Probleme in diesem Bereich: <2–4, z.B. No-Shows halten Räume leer; wiederkehrende Buchungen>
- Meine Einschätzung: <Ein-Satz-Hypothese, was du willst und warum> · Vertrauen <n>%

Klassifiziere den Typ (UI, API, CLI, gemischt) und erstelle REQUIREMENTS.md aus assets/requirements-template.md mit ausgefüllten §1 und dem Kontextabschnitt. Die gefundenen harten Probleme sind das Rohmaterial für deine besten Fragen.

2. Produktfragen

Lese references/questions.md. Arbeite vom riskantesten Unbekannten abwärts: ist dies das richtige Problem, für wen, was kommt zuerst, was ist ausgeschlossen, dann die harten Probleme des Fachgebiets als konkrete Szenarien. Notiere jede Antwort als D-n in § Entscheidungen, sobald sie eintrifft.

Wechsle zu technischen Fragen, wenn alle drei Bedingungen erfüllt sind:

• du kannst die Zusammenfassung (Ergebnis, Nutzer, warum jetzt, Erfolg, Ausgeschlossen) in den eigenen Worten des Entwicklers formulieren;
• der Umfang von Phase 1 und die Nicht-Ziele sind vereinbart;
• was übrig ist, dreht sich um wie, nicht um was, wer oder warum.

Ausnahme: eine harte Einschränkung, die den Umfang verändert ("muss offline laufen", "unseren Auth0-Mandanten wiederverwenden", "Daten bleiben in der EU") wird sofort gefragt, sobald sie auftaucht, weil sie die Produktfragen umformt.

3. Technische Fragen

Nur an Gabelpunkten: Stellen, an denen das Repository und die Standards es nicht klären, und die Antwort das Datenmodell, einen Vertrag oder das benutzersichtbare Verhalten ändert. Die Liste steht in references/questions.md § Technisch. Viele Durchläufe benötigen 0–4. Frage nie nach Hosting, CI, Framework oder Anbieterentscheidungen, die das Repository bereits festlegt.

Bestätigungs-Gate. Eine Nachricht: die Zusammenfassung (6 Zeilen), dann jede von dir getroffene Annahme (A-n, eine Zeile pro Annahme, mit ihrem Standardwert). Frage: Bestätigen, oder die zu ändernden benennen. Änderungen eintragen. Schreibe Status: Bestätigt in die Statuszeile der Spezifikation erst nach einem expliziten Ja.

Phasen und Module

Phasen (immer erwogen). Die Produktfrage "Was kommt zuerst" legt sie fest. Phase 1 ist die dünnste Scheibe, in der ein Nutzer die Kernaufgabe Ende-zu-Ende abschließt (Walking Skeleton). Wenn der Entwickler alles auf einmal will, gibt es eine Phase. Jede FR trägt Phase: n. Phase 1 wird vollständig spezifiziert; spätere Phasen erhalten einen Aufzählungspunkt pro Fähigkeit in § Lieferplan, bis --next-phase sie detailliert.

Module (nur bei Signalen). Behandle einen Bereich nur dann als Modul, wenn er zwei oder mehr erfüllt: unterschiedliche Personen oder Vokabular; besitzt eigene Daten; nützlich, wenn allein ausgeliefert; würde eigene 10+ Fragen erfordern. Bei 2+ qualifizierenden Bereichen frage einmal: eine Spezifikation mit Modulabschnitten (empfohlen), oder spezifiziere das wichtigste Modul jetzt und skizziere den Rest. Leite Module niemals davon ab, wie groß die Idee klingt. Module bleiben in derselben REQUIREMENTS.md als ## Abschnitte unter § Funktionale Anforderungen, mit ID-Präfixen.

Größenbeschränkung. Wenn Phase 1 etwa 25 Muss-FRs oder 12 Mockup-Artefakte überschreitet, frage, welche in Phase 2 verschoben werden sollen.

4. REQUIREMENTS.md schreiben

Fülle die Vorlage. Jede FR hat eine ID, Priorität, Phase, Given/When/Then und Quelle: Entscheidungs-IDs; jeder erhobene Grenzfall wird ein EC-n mit konkreten Fixture-Werten. FRs sagen, was der Nutzer beobachtet; Technologie kommt in § Technische Entscheidungen. Überprüfe dann einmal selbst gegen diese Liste und behebe, was nicht stimmt:

• Zwei Aussagen, die nicht beide gelten können; eine Regel doppelt genannt.
• Eine FR, die ein Entwickler auf zwei verschiedene Weisen bauen könnte (fehlender Grenzwert, Einheit, Rolle oder Fehlerverhalten).
• Ein Kriterium, das durch Beobachtung nicht bestanden oder nicht bestanden werden kann, oder ein vages Wort ohne Zahl.
• Eine Rolle, Entität oder ein Ablauf ohne FR; eine Entscheidung, die von nichts referenziert wird.
• Ein Wort, das gegen das Glossar verwendet wird.

5. Mockups

Liste die Artefakte (Bildschirme, Endpunktgruppen oder Befehlsgruppen) auf, maximal 12, jedes mit seinen Zuständen, und jeden EC einem Zustand zugeordnet. Zeige die Liste in einer Nachricht und fahre fort, es sei denn, der Entwickler widerspricht. Lese dann references/screens.md (UI) oder references/api-cli.md (API, CLI) und baue:

1. Schreibe zuerst mockups/assets/fixtures.js: jeder Name, jede ID, jeder Betrag und jedes Datum, das ein Artefakt zeigt.
2. UI: Schreibe die Designrichtung in § Designrichtung. Wenn das Repository ein Designsystem oder Tokens hat, folge ihm und überspringe die Designfrage; ansonsten stelle eine Designrichtungs-Frage mit ASCII-Skizzen in den Optionsvorschauen.
3. Kopiere ${CLAUDE_SKILL_DIR}/assets/theme.css und app.js nach mockups/assets/, setze die Tokens und führe die Prüfung aus, bis der Kontrast besteht.
4. Baue jedes Artefakt aus references/renderer.md: bei 4+ Artefakten und einem Unteragenten-Tool, ein Unteragent pro Artefakt parallel; ansonsten einzeln hier. CLI: Schreibe mockups/transcripts.md, dann node ${CLAUDE_SKILL_DIR}/scripts/cli-render.mjs spec-it/<name>.
5. Fülle mockups/index.html aus ${CLAUDE_SKILL_DIR}/assets/index.html.
6. UI mit einem Browser-Tool: optional references/critic.md ausführen und die wichtigsten Korrekturen einmal anwenden.

6. Prüfung und Bericht

Führe das Prüfskript aus, bis es mit 0 beendet wird; behandle Mehrdeutigkeitswarnungen als Formulierungshinweise. Berichte in maximal 10 Zeilen: den Pfad, Anzahlen (gestellte Fragen, FRs, ECs, Annahmen, Artefakte), die Prüfzusammenfassung, wie die Mockups angezeigt werden (öffne mockups/index.html, oder node ${CLAUDE_SKILL_DIR}/scripts/serve.mjs spec-it/<name>), und die nächste Phase, falls vorhanden. node ${CLAUDE_SKILL_DIR}/scripts/export.mjs spec-it/<name> schreibt Einzeldatei-Kopien zum Teilen auf Anfrage.

Spätere Durchläufe

• --next-phase: Lese die Spezifikation, nimm die Aufzählungspunkte der nächsten Phase, führe die Schritte 2–6 nur für sie aus (Fragen beginnen dort, wo Phase 1 offen gelassen wurde). Neue FRs setzen die Nummerierung fort; frühere IDs ändern sich nie.
• --revise (oder eine Änderungsanforderung): Notiere die neue Entscheidung, aktualisiere die betroffenen FRs und ECs, rendere nur die betroffenen Artefakte neu, führe die Prüfung erneut aus.

Rationalisierungen

Gedanke	Realität
"Ich sollte jeden Bereich abdecken, also frage ich nach Integrationen."	Frage nur, wenn die Antwort die Spezifikation ändert. "Keine in v1" ist eine Annahme.
"Ich frage, welchen Zeitschritt sie möchten."	Ein Standardstandard existiert. Protokolliere A-n; das Bestätigungs-Gate zeigt ihn an.
"Die Idee ist klar, überspringe den Kontextschritt."	Der Kontextschritt ist der Ort, an dem die guten Fragen herkommen. Führe ihn immer aus.
"Die Idee klingt groß, also Module."	Module brauchen die Signale, dann die Wahl des Entwicklers.
"Sie haben jede Empfehlung angenommen, großartig."	Empfehlungen könnten zu sicher sein. Deine nächste Frage sollte eine sein, der sie widersprechen würden.