# Claude Code Workflow — Universal Bundle Ein minimaler Satz von vier Skills plus Templates für einen nachvollziehbaren Planungs-, Bau- und Übergabe-Workflow in Claude Code. Ziel: Projektstatus lebt auf der Platte (in `docs/`), nicht im Sitzungskontext — und die Skills sorgen dafür, dass diese Dateien konsistent wachsen statt chaotisch. Dieses Bundle ist **rechnerübergreifend portabel**: du klonst / kopierst diesen Ordner auf jede neue Maschine und installierst den globalen Teil mit einem einzigen Kopier- bzw. Symlink-Schritt. --- ## Speicherorte auf einen Blick Die Skills teilen sich in zwei Ebenen. Wichtig: in diesem Bundle liegt aktuell **nur der globale Teil**. Projektspezifische Skills entstehen pro Projekt direkt im jeweiligen Repo (siehe unten) und gehören nicht hierher, weil sie projekt- spezifischen Kontext tragen. | Was | Quelle in diesem Bundle | Ziel auf deinem Rechner | Scope | |---|---|---|---| | Globale Skills (plan-start, status, handoff, adr) | `global-skills/` | `~/.claude/skills/` | maschinenweit, alle Projekte | | Projekt-Wegweiser | wird von `plan-start` erzeugt | `/CLAUDE.md` | nur dieses Projekt | | Projekt-Doku | wird von `plan-start` erzeugt | `/docs/` | nur dieses Projekt | | Projektspezifische Skills (optional) | — (im Projekt anlegen) | `/.claude/skills/` | nur dieses Projekt | Die Trennung ist bewusst: alles unter `~/.claude/skills/` ist **Verb** (Prozess, überall gleich), alles unter `/` ist **Kontext** (Inhalt, projekt- spezifisch). Skills im Projekt-Repo werden mitcommittet und sind Teil der Dokumentation. --- ## Installation (pro Rechner, einmalig) ### Option A — symlinken (empfohlen) Wenn du dieses Bundle per Git versionierst und auf mehreren Rechnern spiegelst, sind Symlinks der saubere Weg. Änderungen werden zentral gepflegt, jeder Rechner zieht nach `git pull` automatisch mit. ```bash # einmalig anlegen mkdir -p ~/.claude/skills # für jeden Skill einen Symlink — Pfad auf dein geklontes Bundle anpassen ln -s "$PWD/global-skills/plan-start" ~/.claude/skills/plan-start ln -s "$PWD/global-skills/status" ~/.claude/skills/status ln -s "$PWD/global-skills/handoff" ~/.claude/skills/handoff ln -s "$PWD/global-skills/adr" ~/.claude/skills/adr ``` ### Option B — kopieren Wenn du lieber unabhängige Kopien willst (z. B. weil du pro Rechner abweichend tunen möchtest): ```bash mkdir -p ~/.claude/skills cp -r global-skills/plan-start ~/.claude/skills/ cp -r global-skills/status ~/.claude/skills/ cp -r global-skills/handoff ~/.claude/skills/ cp -r global-skills/adr ~/.claude/skills/ ``` ### Prüfen Nach Install sollte in Claude Code die Skill-Liste die vier Namen enthalten. Grobe Kontrolle auf der Shell: ```bash ls ~/.claude/skills/ # plan-start status handoff adr ``` --- ## Die vier Skills im Überblick | Skill | Phase | Was er tut | |---|---|---| | `plan-start` | Projektstart | Legt `CLAUDE.md`, `docs/`-Struktur und erste Dateien nach Template an. Einmal pro Projekt. | | `status` | Wiedereinstieg | Liest `docs/90-status.md` + letztes Session-Log, fasst in 5–10 Zeilen zusammen. Dein „Wo stehen wir?"-Befehl. | | `handoff` | Sessionende | Fragt drei kurze Reflexionsfragen, schreibt Session-Log nach `docs/sessions/`, aktualisiert `docs/90-status.md`. | | `adr` | nach Architektur-Entscheidung | Legt nummerierten ADR nach `docs/30-decisions/` an. Kontext, Entscheidung, Konsequenzen, Alternativen. | Nicht dabei (bewusst): `/debug-log` und `/concept-lock`. Die baust du nach zwei, drei Wochen Praxis — dann weißt du, wie sie konkret aussehen müssen. Alles andere wäre hypothetisch. --- ## Was `plan-start` im Projekt erzeugt ``` / ├── CLAUDE.md # Wegweiser, verweist auf docs/90-status.md ├── .claude/ │ └── skills/ # leer — hier landen später projektspezifische Skills └── docs/ ├── 00-overview.md # Zweck, Ziele, Nicht-Ziele ├── 10-plan.md # Phasen, Milestones, aktueller Fokus ├── 20-architecture.md # Stack, Entscheidungen in Kurzform ├── 30-decisions/ # ADRs, einer pro Datei, nummeriert ├── 40-workflows/ # Deploy-, Backup-, Debug-Prozeduren ├── 90-status.md # Single Source of Truth: aktueller Stand └── sessions/ # Session-Logs chronologisch, YYYY-MM-DD-.md ``` Die Nummerierung ist kein Selbstzweck — sie sortiert alphabetisch in der Lese-Reihenfolge, in der eine frische Claude-Code-Instanz die Dateien beim Scannen wahrnimmt, und gibt dir visuelle Hierarchie im Editor. `90-status.md` steht bewusst ganz unten: die eine Datei, die du immer aktualisierst und die jede neue Session zuerst liest. --- ## Projektspezifische Skills (optional, pro Repo) Wenn du in einem konkreten Projekt merkst, dass du immer wieder denselben projektspezifischen Handgriff ausführst (z. B. „Deploy-Pipeline prüfen", „Testdaten regenerieren"), lege ihn als Skill in diesem Repo an: ``` /.claude/skills//SKILL.md ``` Commit mit. Damit ist der Skill Teil der Projekt-Doku — und andere Rechner / Mitwirkende haben ihn automatisch. --- ## Konventionen, die das Ganze tragen - **Sprache**: Prosa auf Deutsch, Code / Pfade / Kommandos / Skill-Namen auf Englisch. Das gilt in allen Templates und Skills konsistent. - **Single Source of Truth**: `docs/90-status.md`. Kein anderer Ort beschreibt „wo wir gerade stehen". - **ADRs sind append-only**: einmal geschrieben, nur noch durch neue ADRs ersetzt (`Supersedes: 0003`). Nie rückwirkend umschreiben — das killt die Nachvollziehbarkeit. - **Session-Logs sind verpflichtend**: `handoff` am Ende jeder relevanten Session. Wer das überspringt, hat nach drei Sessions wieder das alte Problem — nur mit mehr Dateien drumherum. - **CLAUDE.md bleibt schlank** (~50–80 Zeilen): Navigation, nicht Enzyklopädie. Sie verweist auf `docs/`, sie enthält keine Inhalte, die dort hingehören. --- ## Erste Schritte in einem neuen Projekt ```bash cd ~/projekte/mein-neues-ding # in Claude Code: # skill: plan-start "Kurzbeschreibung der Idee" ``` `plan-start` fragt ein paar Basics ab (Name, Zweck, Stack-Hinweise), generiert die Ordnerstruktur und schreibt eine erste `CLAUDE.md` sowie `docs/00-overview.md`, `docs/10-plan.md` und `docs/90-status.md`. Am Ende der Session: `skill: handoff`. Beim nächsten Einstieg: `skill: status`. Das ist der komplette Kreislauf. --- ## Lizenz / Umgang Internes Tooling, keine formelle Lizenz. Passe die Templates an deinen Stil an — sie sind als Ausgangspunkt gedacht, nicht als Dogma.