# Project Blueprint > Setzt ein neues Software-Projekt so auf, dass Claude Code es weitgehend selbstständig abarbeiten kann. Grillt den Menschen zuerst per grill-me Interview durch das Vorhaben und schreibt danach bewusst nur die Basis: docs/KONZEPT.md, CLAUDE.md als Projektgedächtnis und den .claude/-Ordner mit Subagenten, Slash-Command und Permissions. Phasenplan, User Stories und Parallelitätsplan folgen erst auf Wunsch als zweite Stufe. Nutze diesen Skill, sobald jemand ein neues Projekt oder Repo startet, eine Projektstruktur, ein Konzept, ein CLAUDE.md, ein Agenten-Setup oder einen Implementierungsplan braucht — auch bei Formulierungen wie "neues Projekt aufsetzen", "wie fange ich an", "Projektgerüst", "scaffold a new project", "bootstrap a repo", "plan out this project", und auch dann, wenn das Wort Skill, Blueprint oder Vorlage gar nicht fällt. - Skill: `jzbick/project-blueprint` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add jzbick/project-blueprint` - Raw SKILL.md: https://api.skillmd.com/api/skills/jzbick/project-blueprint/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: jzbick (https://skillmd.com/u/jzbick) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/jzbick/project-blueprint --- # 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.md` und `.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: 1. **Ein-Satz-Ziel und Erfolgsdefinition.** Was wird gebaut, für wen, und woran erkennt man in drei Monaten, dass es funktioniert hat? 2. **Umfang — und was bewusst draußen bleibt.** Die Draußen-Liste ist der wertvollere Teil. 3. **Stack und Zielplattform.** Sprache, Framework, Laufzeit, Deployment-Ziel. 4. **Wo sind Fehler teuer?** Datenverlust, Geld, Recht/Compliance, Sicherheit, schwer korrigierbare Architekturentscheidungen. Die wertvollste Frage im ganzen Interview — sie steuert später jede Modellwahl. 5. **Qualitäts-Gates.** Was muss grün sein, damit etwas fertig ist? Mit konkretem Befehl. 6. **Modulschnitt.** Welche Teile haben getrennte Dateien und getrennte Verantwortung? Siehe Schritt 2. 7. **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`: ```bash 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 und `git add`/`commit`, Deny für `push`/`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.md` ein 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.