initial: claude code workflow bundle (plan-start, status, handoff, adr)
This commit is contained in:
Kristian
@@ -0,0 +1,173 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user