jzbick Projekt-Blueprint
Wozu das gut ist
Ein Projekt, das ein Mensch mit Claude Code baut, scheitert selten an der Programmierung. Es scheitert daran, dass unklar ist, was gebaut wird, woran „fertig" gemessen wird, und dass jede Session bei null Kontext anfängt.
Dieser Skill setzt deshalb in zwei Stufen an — und Stufe 1 ist der Normalfall:
- Stufe 1 (immer): Interview, dann
docs/KONZEPT.md,CLAUDE.mdund.claude/mit den Agenten. Das ist alles, was man braucht, um sinnvoll anzufangen. - Stufe 2 (nur auf ausdrücklichen Wunsch): Phasenplan, User Stories, Parallelitätsplan, Wellen-Orchestrierung.
Der Grund für den Schnitt: Ein Phasenplan mit 35 Stories, der auf einem ungeprüften Konzept steht, ist Arbeit, die zweimal gemacht wird. Erst muss klar sein, was gebaut wird und wie es geschnitten ist — Stories lassen sich danach in einer halben Stunde nachziehen.
Der rote Faden über beide Stufen: Der Mensch entscheidet und nimmt ab, die Agenten implementieren, Tests und Gates sichern die Qualität.
Stufe 1
Schritt 1 — Interview per grill-me
Rufe den Skill grill-me auf (Skill-Tool, skill: grill-me). Er führt das Interview: eine Frage nach der anderen, mit Empfehlung, bis jede Verzweigung aufgelöst ist. Kein Fragebogen, keine Sammelfrage.
Gib ihm den Fokus mit. Das Interview ist erst fertig, wenn diese Punkte geklärt sind:
- Ein-Satz-Ziel und Erfolgsdefinition. Was wird gebaut, für wen, und woran erkennt man in drei Monaten, dass es funktioniert hat?
- Umfang — und was bewusst draußen bleibt. Die Draußen-Liste ist der wertvollere Teil.
- Stack und Zielplattform. Sprache, Framework, Laufzeit, Deployment-Ziel.
- Wo sind Fehler teuer? Datenverlust, Geld, Recht/Compliance, Sicherheit, schwer korrigierbare Architekturentscheidungen. Die wertvollste Frage im ganzen Interview — sie steuert später jede Modellwahl.
- Qualitäts-Gates. Was muss grün sein, damit etwas fertig ist? Mit konkretem Befehl.
- Modulschnitt. Welche Teile haben getrennte Dateien und getrennte Verantwortung? Siehe Schritt 2.
- Zeitbudget. Stunden pro Woche, Wunschhorizont.
Nach Bedarf, nur wenn der Kontext es nahelegt: zentrale veränderliche Werte (Preise, Limits, Flags), externe Abhängigkeiten mit Vorlaufzeit, Ton und Stil bei nutzersichtbaren Texten, Story-Präfix (drei Buchstaben, z. B. AMT), Sprache der Dokumente (Standard: die Gesprächssprache).
Was sich aus einem vorhandenen Repo beantworten lässt, wird gelesen statt gefragt.
Fasse am Ende in fünf Zeilen zusammen, was du verstanden hast — inklusive der Annahmen, die du selbst getroffen hast, ausdrücklich als Annahme markiert. Erst danach schreiben.
Schritt 2 — Architektur so schneiden, dass später Lanes entstehen
Zerlege das System in Module mit getrennten Dateien und getrennter Verantwortung, und halte für jedes fest, was es besitzt und was es nie anfassen darf. Ein bewährter Schnitt:
| Modul | Besitzt typischerweise | Charakter |
|---|---|---|
| Kern | Domänenlogik, Datenmodelle | Deterministisch, ohne I/O, vollständig testbar |
| Oberfläche | UI, Views, Assets | Liest Kern-Zustand, sendet Kommandos, enthält keine Logik |
| Plattform/Tools | Externe Dienste hinter Interfaces, Skripte, CI | Austauschbar, gemockt bis zur Integration |
| Doku/Content | docs/, Texte, Übersetzungen |
Konfliktfrei |
Zwei Eigenschaften machen den Schnitt tauglich: Der Kern muss ohne Oberfläche testbar sein, und jede Datei gehört genau einem Modul. Gehört eine Datei zwei Modulen, ist der Schnitt falsch — nicht der Plan.
Passt das nicht zum Projekt (Datenpipeline, CLI-Tool, Bibliothek), erfinde eigene Module nach demselben Prinzip: getrennte Ordner, klarer Besitz, Kern zuerst.
Dieser Schnitt ist gleichzeitig die Vorarbeit für die Lanes in Stufe 2 — deshalb steht er schon hier.
Schritt 3 — Konzept und Projektgedächtnis schreiben
Lies references/konzept.md für die beiden Vorlagen und schreibe in dieser Reihenfolge:
| # | Datei | Kern |
|---|---|---|
| 1 | docs/KONZEPT.md |
Ziel, Erfolgsdefinition, Umfang inkl. Nicht-Umfang, Stack, Modulschnitt, Risikotabelle, Gates, Annahmen |
| 2 | CLAUDE.md |
Projektgedächtnis: Stack, Befehle, Architekturregeln, Definition of Done, Ton, „Nicht tun" |
Mehr nicht. Kein Phasenplan, keine Stories, kein README-Paket — das ist Stufe 2.
Schritt 4 — .claude/ scaffolden
scripts/scaffold.py erzeugt die Agenten aus einer kleinen Konfiguration. Für Stufe 1 reichen vier Felder — project, prefix, commands, optional central_data_file:
python3 scripts/scaffold.py --config projekt.json --target /pfad/zum/repo
scripts/beispiel-config-stufe1.json zeigt genau diese Minimalvariante, scripts/beispiel-config.json die vollständige für Stufe 2. python3 scripts/scaffold.py --print-schema gibt die Feldbeschreibung aus.
Ohne das Feld waves entstehen:
.claude/agents/—core-worker(Opus, für risikoreiche Aufgaben),standard-worker(Sonnet, Arbeitspferd),docs-worker(Haiku, Mechanisches),story-reviewer(Opus, read-only Qualitäts-Gate).claude/commands/implement-story.md—/implement-story XYZ-012, nutzbar, sobald es Stories gibt.claude/settings.json— Vorab-Freigaben für Test/Lint/Build undgit add/commit, Deny fürpush/merge/rm -rf
Der Orchestrierungs-Workflow (implement-wave.js) entsteht bewusst nicht — er braucht einen Wellenplan und gehört damit in Stufe 2.
Prüfe nach dem Lauf, ob die Befehle in commands im Repo tatsächlich existieren. Die Worker verlassen sich darauf.
Wichtig beim Ablegen: Wenn das Repo auf dem Rechner des Menschen liegt und du über die Geräte-Bridge arbeitest, lehnt device_commit_files jeden Pfad unter .claude/ ab. Nutze dafür device_bash (Dateien im Container bauen, als Base64-Tarball übertragen, auf dem Gerät entpacken) und verifiziere anschließend per Prüfsumme.
Schritt 5 — Übergeben und stoppen
Übergib das Ergebnis, benenne ausdrücklich deine Annahmen und welche Stelle der Mensch als erstes prüfen sollte. Dann hör auf und biete Stufe 2 in einem Satz an.
Nicht ungefragt weiterschreiben. Das Konzept ist die Abnahmegrundlage; ein Phasenplan auf einem ungeprüften Konzept ist verlorene Arbeit.
Selbstcheck Stufe 1
- Steht im Konzept eine Erfolgsdefinition, die man beobachten kann — kein Gefühl?
- Ist die „bewusst draußen"-Liste gefüllt? Eine leere Liste heißt: nicht nachgedacht.
- Gehört jede Datei im Modulschnitt genau einem Modul?
- Hat jedes Risiko in der Tabelle eine Konsequenz fürs Vorgehen, nicht nur eine Beschreibung?
- Stimmen die Befehle in
CLAUDE.md, den Worker-Anweisungen und.claude/settings.jsonüberein? - Hat jede Architekturregel in
CLAUDE.mdein konkretes Fehlerbild aus dem Interview?
Stufe 2 — nur auf Wunsch
Erst starten, wenn der Mensch das Konzept abgenommen hat und ausdrücklich weiter will. Dann Lanes, Phasen, Stories, Wellen.
Lies references/dokumente.md für die Vorlagen und references/parallelisierung.md für Lanes, Wellenplan und Modellwahl. Schreibe in dieser Reihenfolge, jede Datei nutzt die vorherige als Input:
| # | Datei | Kern |
|---|---|---|
| 1 | docs/IMPLEMENTATION_PLAN.md |
Phasen 0…N mit Ziel, Deliverables, Exit-Kriterien als Checkboxen |
| 2 | docs/USER_STORIES.md |
Stories mit ID, Story-Satz, Akzeptanzkriterien, fertigem Prompt, Checkbox |
| 3 | docs/PARALLEL_EXECUTION.md |
Lanes, Abhängigkeitsgraph, Wellenplan, Modellwahl je Story, Merge-Reihenfolge |
| 4 | docs/PROJECT_SETUP.md |
Einmalige Einrichtung, Kickoff-Prompt, Arbeitszyklus, Branching |
| 5 | docs/ORCHESTRATION.md |
Wie eine Instanz die Worker steuert, Grenzen, Abnahme-Ritual |
| 6 | README.md |
Inhaltsverzeichnis des Pakets und „Loslegen" in vier Schritten |
| 7 | docs/ONBOARDING_CHECKLIST.md |
Nur wenn es externe Abhängigkeiten mit Vorlaufzeit gibt |
Danach scaffold.py erneut laufen lassen — diesmal mit waves in der Konfiguration und --force. Das erzeugt zusätzlich .claude/workflows/implement-wave.js. Prüfe mit node --check .claude/workflows/implement-wave.js und gleiche die Wellen gegen docs/PARALLEL_EXECUTION.md ab; das Skript kennt sie nur aus der Konfiguration.
Größenordnung: 25–40 Stories über 6–8 Phasen für ein Projekt von einigen Monaten Teilzeit. Deutlich weniger heißt meist zu grob geschnitten, deutlich mehr, dass Trivialitäten zu Stories geworden sind.
Was eine gute Story ausmacht: in einer Session implementierbar, in einem Commit ablieferbar, in zwei Minuten überprüfbar. Der Wert steckt in den Akzeptanzkriterien — sie beschreiben beobachtbares Verhalten, nicht Implementierung, und sind einzeln abhakbar. „Speichern funktioniert" ist kein Kriterium. „Ein Speicherstand aus Schema-Version 1 wird beim Laden migriert, ein Test deckt das ab" ist eins. Der mitgelieferte Prompt sagt was und woran es gemessen wird, nicht wie.
Selbstcheck Stufe 2: Taucht jede Story im Phasenplan und im Wellenplan auf? Hat jede Phase messbare Exit-Kriterien? Ist jede Modellzuordnung mit einer Fehlerkosten-Aussage begründet? Kennt der Kickoff-Prompt die richtige erste Story?
Prinzipien, die das Schema tragen
Diese Regeln gehören in CLAUDE.md und in die Worker-Anweisungen. Sie sind der Grund, warum das Paket funktioniert — nicht Beiwerk.
Konzept vor Plan. Ein Plan ist nur so gut wie das Verständnis darunter. Deshalb das Interview zuerst und das Konzept als eigenes, abnehmbares Dokument.
Ein Kriterium, keine Meinung. Fertig ist, was die Kriterien erfüllt und die Gates besteht. Passt ein Ergebnis nicht, benenne das verletzte Kriterium, statt nachbessern zu lassen.
Exit-Kriterien schlagen Zeitpläne. Eine Phase endet, wenn ihre Checkboxen gesetzt sind, nicht wenn die Woche um ist.
Eine Aufgabe, ein Prompt, ein Commit. Sammel-Prompts erzeugen Diffs, die niemand mehr reviewt — der Anfang der Review-Schulden.
Veränderliche Werte zentral. Was sich erfahrungsgemäß ändert, gehört in eine Datendatei mit Kommentaren, nicht in den Code.
Checkboxen setzt nur der Mensch. Agenten haken nichts ab und mergen nicht. Das ist zugleich der Punkt, an dem die Abnahme stattfindet.
Modellwahl nach Fehlerkosten, nicht nach Aufgabengröße. Das teure Modell dort, wo Fehler Daten, Geld, Rechtssicherheit oder die Kern-Architektur kosten. Standard ist das mittlere Modell, Mechanisches läuft auf dem kleinen. Bei knappem Budget: mit dem mittleren implementieren, den Diff vom großen reviewen lassen.
Der Engpass ist der Mensch. Jede Lane produziert einen Diff, der gelesen und ausprobiert werden muss. Zwei bis drei parallele Lanes sind die Obergrenze für eine Person.
Merge-Reihenfolge ist Teil des Plans. Kern zuerst, dann Plattform/Tools, dann Oberfläche, zuletzt Doku. Nach jedem Merge die Gates laufen lassen.
Was danach passiert
Nach Stufe 1: Der Mensch legt das Repo an, kopiert Konzept, CLAUDE.md und .claude/ hinein und kann sofort mit den Agenten arbeiten — Aufgabe für Aufgabe, formuliert aus dem Konzept.
Nach Stufe 2 kommt der strukturierte Betrieb dazu: Story für Story per /implement-story, oder wellenweise über den Workflow. Nach jeder Welle: Review-Befunde lesen, in der vorgegebenen Reihenfolge mergen, Gates laufen lassen, selbst ausprobieren, Checkboxen setzen. Erkenntnisse landen unter „Backlog-Notizen" am Ende von USER_STORIES.md — der Gedächtnisspeicher zwischen den Sessions.