Kristian
6.6 KiB
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 |
<projekt>/CLAUDE.md |
nur dieses Projekt |
| Projekt-Doku | wird von plan-start erzeugt |
<projekt>/docs/ |
nur dieses Projekt |
| Projektspezifische Skills (optional) | — (im Projekt anlegen) | <projekt>/.claude/skills/ |
nur dieses Projekt |
Die Trennung ist bewusst: alles unter ~/.claude/skills/ ist Verb (Prozess,
überall gleich), alles unter <projekt>/ 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.
# 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):
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:
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
<projekt>/
├── 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-<slug>.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:
<projekt>/.claude/skills/<skill-name>/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:
handoffam 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
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.