Kristian
174 lines
6.6 KiB
Markdown
174 lines
6.6 KiB
Markdown
# 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.
|
||
|
||
```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
|
||
|
||
```
|
||
<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**: `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.
|