Optimaler Entwicklungs-Workflow eingerichtet

- workflow/: Schnellreferenz, Modell-Strategie, Story-Lifecycle-Doku - skills/: /go, /plan-review, /story als globale Skills - hooks/: auto-format.sh (PostToolUse), verify-on-stop.sh (Stop) - agents/: plan-reviewer (Opus 4.7) für unabhängigen Plan-Review - Symlinks in ~/.claude/skills/ und ~/.claude/agents/ - settings.json um Hooks-Sektion erweitert Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
2026-04-19 10:38:30 +02:00
parent d804417757
commit a07c436a7d
10 changed files with 595 additions and 0 deletions
@@ -0,0 +1,65 @@
+# Setup-Anleitung
+
+## Einmalige Einrichtung (bereits ausgeführt)
+
+### 1. Skills verlinken
+```bash
+mkdir -p ~/.claude/skills
+ln -sf /mnt/projekte/claude-workflow/skills/go.md ~/.claude/skills/go.md
+ln -sf /mnt/projekte/claude-workflow/skills/plan-review.md ~/.claude/skills/plan-review.md
+ln -sf /mnt/projekte/claude-workflow/skills/story.md ~/.claude/skills/story.md
+```
+
+### 2. Agent verlinken
+```bash
+ln -sf /mnt/projekte/claude-workflow/agents/plan-reviewer.md ~/.claude/agents/plan-reviewer.md
+```
+
+### 3. Hooks aktivieren
+In `~/.claude/settings.json` die `hooks`-Sektion ist bereits eingetragen.
+
+### 4. Hook-Skripte ausführbar machen
+```bash
+chmod +x /mnt/projekte/claude-workflow/hooks/*.sh
+```
+
+## Nach System-Neuinstallation
+
+Die vier Symlink-Befehle aus Schritt 1+2 erneut ausführen.
+Die `hooks`-Sektion in `settings.json` erneut eintragen.
+
+## Verzeichnis-Struktur
+
+```
+/mnt/projekte/claude-workflow/
+├── SETUP.md                        ← Diese Datei
+├── workflow/
+│   ├── README.md                   ← Schnellreferenz (täglich nutzen)
+│   ├── models.md                   ← Modell-Strategie + Kosten
+│   └── story-lifecycle.md          ← Story-Phasen im Detail
+├── skills/
+│   ├── go.md                       ← /go: Test + Simplify + PR
+│   ├── plan-review.md              ← /plan-review: Opus reviewt Plan
+│   └── story.md                    ← /story: Voller Lifecycle
+├── hooks/
+│   ├── auto-format.sh              ← PostToolUse: ruff/eslint
+│   └── verify-on-stop.sh          ← Stop: Git-Status-Erinnerung
+└── agents/
+    └── plan-reviewer.md            ← Opus-basierter Plan-Reviewer
+```
+
+## Globale ~/.claude Verzeichnisse (nach Setup)
+
+```
+~/.claude/
+├── skills/
+│   ├── go.md         → Symlink zu claude-workflow/skills/go.md
+│   ├── plan-review.md → Symlink
+│   └── story.md       → Symlink
+├── agents/
+│   ├── plan-reviewer.md → Symlink zu claude-workflow/agents/plan-reviewer.md
+│   ├── test-runner.md   (original)
+│   ├── security-audit.md (original)
+│   └── n8n-architect.md  (original)
+└── settings.json    (Hooks eingetragen)
+```
@@ -0,0 +1,63 @@
+---
+name: plan-reviewer
+description: Unabhängiger Plan-Reviewer. Prüft Implementierungspläne auf Vollständigkeit, fehlende Tests, Security-Risiken und Migrations-Korrektheit. Wird durch /plan-review aktiviert.
+model: claude-opus-4-7
+tools: Read, Glob, Grep
+---
+
+Du bist ein erfahrener Software-Architekt und Code-Reviewer. Deine Aufgabe ist es, Implementierungspläne kritisch zu prüfen — bevor Code geschrieben wird.
+
+## Dein Vorgehen
+
+1. Lies den aktuellen Plan (neueste Datei in `/home/martin/.claude/plans/`)
+2. Lies die CLAUDE.md des betroffenen Projekts
+3. Analysiere den Plan systematisch
+
+## Prüfkriterien
+
+**Vollständigkeit**
+- Sind alle Akzeptanzkriterien messbar formuliert?
+- Sind API-Endpoints, Services und Modelle vollständig aufgelistet?
+- Sind Frontend-Komponenten und Routen berücksichtigt?
+
+**Tests**
+- Unit-Tests für jeden Service?
+- Integration-Tests für API-Endpoints?
+- Security-Tests für Auth-Pfade?
+- E2E-Tests für kritische Flows?
+
+**Datenbank**
+- Alembic-Migration für jede Schema-Änderung?
+- Seed-Daten für Lookup-Tabellen eingeplant?
+- Eager-Loading in der API-Schicht berücksichtigt?
+
+**Security**
+- Input-Validierung (Pydantic-Schemas / Trimming)?
+- Auth-Checks auf allen geschützten Endpoints?
+- Keine HTTP-Exceptions in Services?
+
+**Architektur**
+- api/ → services/ → models/ Richtung eingehalten?
+- HTTPException nur in api/-Schicht?
+- Keine zirkulären Abhängigkeiten?
+
+## Ausgabe-Format
+
+```
+## Plan-Review: [Plan-Name]
+
+### ✅ OK
+- [konkrete Punkte die gut sind]
+
+### ⚠️ Risiko
+- [Punkt]: [Warum problematisch] → [Empfehlung]
+
+### ❌ Fehlt
+- [Was fehlt]: [Warum notwendig]
+
+### Empfehlung
+[FREIGABE: Implementierung kann starten]
+[ANPASSEN: Diese Punkte zuerst ergänzen: ...]
+```
+
+Sei präzise und konkret. Keine allgemeinen Empfehlungen.
@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# PostToolUse-Hook: Formatiert geänderte Dateien nach Edit/Write
+# Wird von settings.json nach Edit- und Write-Tool-Aufrufen ausgeführt
+
+set -euo pipefail
+
+# Dateiname aus Umgebungsvariable (Claude Code setzt CLAUDE_TOOL_INPUT_FILE_PATH)
+FILE="${CLAUDE_TOOL_INPUT_FILE_PATH:-}"
+
+if [[ -z "$FILE" || ! -f "$FILE" ]]; then
+  exit 0
+fi
+
+EXT="${FILE##*.}"
+
+case "$EXT" in
+  py)
+    if command -v ruff &>/dev/null; then
+      ruff format --quiet "$FILE" 2>/dev/null || true
+      ruff check --fix --quiet "$FILE" 2>/dev/null || true
+    fi
+    ;;
+  js|ts|vue|jsx|tsx)
+    DIR=$(dirname "$FILE")
+    if [[ -f "$DIR/package.json" ]] || [[ -f "$DIR/../package.json" ]]; then
+      if command -v npx &>/dev/null; then
+        npx --yes eslint --fix --quiet "$FILE" 2>/dev/null || true
+      fi
+    fi
+    ;;
+esac
+
+exit 0
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Stop-Hook: Prüft ob offene Tasks oder ungestartete Tests vorhanden sind
+# Gibt eine Erinnerung aus, blockiert aber nicht
+
+set -euo pipefail
+
+REMINDERS=()
+
+# Prüfe ob wir in einem Git-Repo sind
+if git rev-parse --git-dir &>/dev/null 2>&1; then
+  # Uncommitted changes?
+  if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
+    REMINDERS+=("⚠️  Uncommittete Änderungen vorhanden — committen nicht vergessen")
+  fi
+
+  # Ungetrackte Dateien?
+  UNTRACKED=$(git ls-files --others --exclude-standard 2>/dev/null | wc -l)
+  if [[ "$UNTRACKED" -gt 0 ]]; then
+    REMINDERS+=("ℹ️  $UNTRACKED ungetrackte Datei(en) — ggf. zu .gitignore hinzufügen")
+  fi
+fi
+
+if [[ ${#REMINDERS[@]} -gt 0 ]]; then
+  echo ""
+  echo "╭─ Session-Erinnerung ───────────────────────────────"
+  for r in "${REMINDERS[@]}"; do
+    echo "│ $r"
+  done
+  echo "╰────────────────────────────────────────────────────"
+fi
+
+exit 0
@@ -0,0 +1,34 @@
+---
+description: Führt nach einer Implementierung Tests aus, vereinfacht den Code und erstellt einen PR in Gitea. Aktivieren wenn eine Feature-Implementierung abgeschlossen ist und ein PR erstellt werden soll.
+context: fork
+---
+
+# /go — Test + Simplify + PR
+
+Führe diese drei Schritte der Reihe nach aus:
+
+## Schritt 1: Tests ausführen
+
+Starte den `test-runner`-Agenten. Warte auf das Ergebnis.
+Wenn Tests fehlschlagen: Abbruch, Fehlerbericht ausgeben.
+
+## Schritt 2: Code vereinfachen
+
+Starte den `code-simplifier`-Agenten für alle in dieser Session geänderten Dateien.
+Ziel: Redundanzen entfernen, Lesbarkeit verbessern, keine neuen Features einführen.
+
+## Schritt 3: PR erstellen
+
+Ermittle den aktuellen Branch-Namen und die Commit-Zusammenfassung:
+```
+!git log --oneline origin/main..HEAD
+!git branch --show-current
+```
+
+Erstelle den PR via Gitea-API:
+- Gitea-Instanz: `https://gitea.troeger-net.org`
+- Token: `$(secret-tool lookup user claude-code token gitea)`
+- PR-Titel: Erster Commit-Titel des Branches
+- PR-Body: Alle Akzeptanzkriterien als Checkboxen + Verifikations-Hinweis
+
+Gib die PR-URL aus.
@@ -0,0 +1,35 @@
+---
+description: Startet einen unabhängigen Opus-Agenten der den aktuellen Plan auf Vollständigkeit, Risiken und fehlende Tests prüft. Aktivieren nach der Planungsphase, bevor die Implementierung beginnt.
+context: fork
+---
+
+# /plan-review — Unabhängiger Plan-Review
+
+Starte den `plan-reviewer`-Agenten mit folgendem Auftrag:
+
+1. Lies den aktuellen Plan aus `/home/martin/.claude/plans/` (neueste Datei)
+2. Lies die CLAUDE.md des aktuellen Projekts
+3. Prüfe den Plan auf:
+   - **Vollständigkeit**: Sind alle Akzeptanzkriterien abgedeckt?
+   - **Tests**: Sind Unit-, Integration- und Security-Tests eingeplant?
+   - **Migrations**: Sind Alembic-Migrationen für Schema-Änderungen vorgesehen?
+   - **Security**: Sind Input-Validierung und Auth-Checks berücksichtigt?
+   - **Abhängigkeiten**: Fehlen Abhängigkeiten zu anderen Modulen?
+   - **Risiken**: Was kann schiefgehen?
+
+Ausgabe-Format:
+```
+## Plan-Review
+
+### ✅ OK
+- [was in Ordnung ist]
+
+### ⚠️ Risiko
+- [potenzielle Probleme mit Empfehlung]
+
+### ❌ Fehlt
+- [was ergänzt werden muss, bevor implementiert werden darf]
+
+### Empfehlung
+[Implementierung freigeben / Plan zuerst anpassen]
+```
@@ -0,0 +1,49 @@
+---
+description: Orchestriert den vollständigen Story-Lifecycle von Planung bis PR. Aktivieren wenn eine neue User Story oder ein neues Feature implementiert werden soll.
+---
+
+# /story — Voller Story-Lifecycle
+
+Führe den Story-Lifecycle vollständig durch. Warte nach jeder Phase auf Bestätigung.
+
+## Phase 1: Research
+
+Starte bis zu 3 Explore-Subagenten parallel für:
+- Bestehende Implementierungen im relevanten Bereich finden
+- Test-Patterns und -Setup analysieren
+- Abhängige Services/Modelle identifizieren
+
+Hole Context-7-Dokumentation für alle beteiligten Frameworks:
+```
+mcp__plugin_context7_context7__resolve-library-id
+mcp__plugin_context7_context7__query-docs
+```
+
+## Phase 2: Planung
+
+Wechsle auf Opus: Sage dem Nutzer: "Wechsle für die Planung auf /model opus"
+Aktiviere Plan-Modus.
+Erstelle einen detaillierten Plan mit Akzeptanzkriterien.
+
+## Phase 3: Plan-Review
+
+Rufe `/plan-review` auf.
+Warte auf das Ergebnis.
+Bei ❌-Punkten: Plan anpassen, dann erneut reviewen.
+Bei ✅ Freigabe: weiter.
+
+## Phase 4: Implementierung
+
+Sage dem Nutzer: "Wechsle für die Implementierung auf /model sonnet"
+Feature-Branch erstellen:
+```
+!git checkout -b feature/<story-name>
+```
+Implementierung durchführen. Commits stündlich.
+
+## Phase 5: Abschluss
+
+Rufe `/go` auf (Test + Simplify + PR).
+Warte auf PR-URL.
+
+Ausgabe: PR-URL + kurze Zusammenfassung was implementiert wurde.
@@ -0,0 +1,81 @@
+# Claude Code Workflow — Schnellreferenz
+
+## Story-Lifecycle
+
+| Phase | Befehl / Agent | Modell |
+|---|---|---|
+| 1. Planung | `EnterPlanMode` | Sonnet |
+| 2. Plan-Review | `/plan-review` | **Opus 4.7** |
+| 3. Implementierung | Claude direkt | **Sonnet 4.6** |
+| 4. Test + Simplify + PR | `/go` | Haiku / Sonnet |
+| 5. Security-Audit | `security-audit`-Agent | **Opus 4.7** |
+
+Kurzform für den kompletten Lifecycle: `/story`
+
+---
+
+## Modell-Matrix
+
+| Aufgabe | Modell | Warum |
+|---|---|---|
+| Planung, Review | Opus 4.7 | Qualität entscheidend |
+| Implementierung | Sonnet 4.6 | Bestes Preis-Leistungs-Verhältnis |
+| Tests, Lint, Format | Haiku 4.5 | Schnell + günstig |
+| Security-Audit | Opus 4.7 | Sicherheit hat Priorität |
+| PR-Erstellung | Haiku 4.5 | Mechanische Aufgabe |
+
+---
+
+## Skills (Slash-Commands)
+
+| Befehl | Beschreibung | Datei |
+|---|---|---|
+| `/go` | Tests + Simplify + PR in einem Schritt | `skills/go.md` |
+| `/plan-review` | Opus reviewt aktuellen Plan | `skills/plan-review.md` |
+| `/story` | Voller Story-Lifecycle | `skills/story.md` |
+
+---
+
+## Aktive Hooks
+
+| Event | Aktion | Skript |
+|---|---|---|
+| `PostToolUse` (Edit/Write) | Auto-Format (ruff / eslint) | `hooks/auto-format.sh` |
+| `Stop` | Offene Tasks prüfen | `hooks/verify-on-stop.sh` |
+
+---
+
+## Agenten
+
+| Agent | Modell | Aufgabe |
+|---|---|---|
+| `test-runner` | Sonnet | Tests ausführen, Coverage prüfen |
+| `security-audit` | Sonnet | OWASP-Analyse, Security-Tests |
+| `plan-reviewer` | **Opus 4.7** | Plan auf Lücken/Risiken prüfen |
+| `n8n-architect` | Sonnet | n8n-Workflow-Design |
+
+---
+
+## MCP-Server
+
+| Server | Wann nutzen |
+|---|---|
+| `context7` | Bei jeder Bibliothek/Framework-Frage |
+| `n8n-local` | n8n-Workflow-Inspektion |
+
+---
+
+## Kontext-Management
+
+- **< 200k Tokens**: Normal weiterarbeiten
+- **200–350k Tokens**: `/compact` mit konkretem Hinweis ausführen
+- **> 350k Tokens**: Neue Session, Subagenten für Isolation nutzen
+- Nie auf automatisches Compacting verlassen — manuell mit Hints ist besser
+
+---
+
+## Weitere Details
+
+- Modell-Strategie: `models.md`
+- Story-Lifecycle: `story-lifecycle.md`
+- Installation/Setup: `../SETUP.md`
@@ -0,0 +1,81 @@
+# Modell-Strategie
+
+## Grundprinzip
+
+Teures Modell nur dort, wo Qualität den Unterschied macht.
+Günstiges Modell für mechanische, wiederholbare Aufgaben.
+
+## Modell-Übersicht (Stand April 2026)
+
+| Modell | ID | Stärke | Relative Kosten |
+|---|---|---|---|
+| Opus 4.7 | `claude-opus-4-7` | Höchste Reasoning-Qualität, adaptives Thinking | ●●●●● |
+| Sonnet 4.6 | `claude-sonnet-4-6` | Ausgewogen, sehr gute Codequalität | ●●●○○ |
+| Haiku 4.5 | `claude-haiku-4-5-20251001` | Schnell, kostengünstig | ●○○○○ |
+
+## Zuordnung nach Phase
+
+### Planung & Review → Opus 4.7
+Warum: Ein schlechter Plan kostet mehr Zeit als das teurere Modell.
+```
+/model opus
+```
+Einsatz:
+- `EnterPlanMode`
+- `/plan-review`
+- Architektur-Entscheidungen
+- Risiko-Analysen
+
+### Implementierung → Sonnet 4.6
+Warum: Ausreichende Qualität bei deutlich niedrigeren Kosten als Opus.
+```
+/model sonnet  (Standard / Default)
+```
+Einsatz:
+- Feature-Implementierung
+- Refactoring
+- Bug-Fixes
+- Frontend-Entwicklung
+
+### Tests / Lint / Format → Haiku 4.5
+Warum: Mechanische Aufgaben brauchen kein Reasoning.
+```
+/model haiku
+```
+Einsatz:
+- `test-runner`-Agent
+- Auto-Format-Hook
+- PR-Beschreibung generieren
+- Einfache Datei-Operationen
+
+### Security-Audit → Opus 4.7
+Warum: Sicherheitslücken zu übersehen kostet mehr als das Modell.
+```
+/model opus
+```
+Einsatz:
+- `security-audit`-Agent
+- Permission-Scan im PreToolUse-Hook
+
+## Kontext-Degradation
+
+Bei langen Sessions sinkt die Qualität aller Modelle:
+- **Sonnet**: Degradation ab ~300k Tokens
+- **Opus**: Robuster, aber ab ~400k Tokens trotzdem besser compacten
+
+Strategie:
+1. `/compact "aktueller Stand: [Zusammenfassung]"` bei 200–350k
+2. Neue Session + Subagenten bei > 350k
+3. Subagenten schützen Haupt-Kontext generell (immer bevorzugen für isolierte Aufgaben)
+
+## Fast Mode
+
+`/fast` aktiviert Opus 4.7 mit schnellerer Ausgabe (kein Downgrade).
+Sinnvoll bei: Langen Implementierungen mit Opus, wo Wartezeit stört.
+
+## Kosten-Faustregeln
+
+- 10 Story-Punkte Implementierung: ~80% Sonnet, ~20% Opus
+- Security-Audit pro Story: immer Opus (< 5% der Gesamtkosten, schützt vor Regressionen)
+- Test-Runner: immer Haiku (< 2% der Gesamtkosten)
+- Faustregel: Opus nur für Entscheidungen, Sonnet für Umsetzung, Haiku für Verifikation
@@ -0,0 +1,122 @@
+# Story-Lifecycle
+
+## Übersicht
+
+```
+Research → Plan → Review → Implement → Test → Security → PR
+```
+
+Kurzbefehl für alles: `/story`
+
+---
+
+## Phase 1: Research
+
+Ziel: Verstehen was gebaut werden soll und was bereits existiert.
+
+```
+# Subagenten für parallele Exploration starten
+Agent(Explore): Bestehende Implementierungen finden
+Agent(Explore): Test-Patterns analysieren
+```
+
+Checkliste:
+- [ ] Ähnliche bestehende Funktionen gefunden?
+- [ ] Abhängige Modelle/Services identifiziert?
+- [ ] Test-Setup verstanden?
+- [ ] CLAUDE.md des Projekts gelesen?
+
+---
+
+## Phase 2: Planung
+
+```
+/model opus    # Für beste Planqualität
+EnterPlanMode
+```
+
+Checkliste:
+- [ ] Context-7 für alle beteiligten Frameworks konsultiert?
+- [ ] Akzeptanzkriterien definiert?
+- [ ] Test-Typen festgelegt (Unit / Integration / E2E)?
+- [ ] Migrations-Bedarf (Alembic) geprüft?
+- [ ] Security-relevante Pfade markiert?
+
+---
+
+## Phase 3: Plan-Review
+
+```
+/plan-review   # Startet Opus-basierten plan-reviewer-Agent
+```
+
+Der Agent prüft:
+- Vollständigkeit der Akzeptanzkriterien
+- Fehlende Test-Abdeckung
+- Security-Risiken
+- Abhängigkeiten zu anderen Features
+- Migrations-Korrektheit
+
+Erst nach ✅ des Reviews: Implementierung starten.
+
+---
+
+## Phase 4: Implementierung
+
+```
+/model sonnet  # Zurück auf Sonnet
+ExitPlanMode
+```
+
+Regeln:
+- Feature-Branch (niemals direkt auf `main`)
+- Commits mind. stündlich
+- Kleine, fokussierte Commits
+- Subagenten für isolierte Teilaufgaben nutzen
+
+---
+
+## Phase 5: Test + Simplify + PR
+
+```
+/go
+```
+
+Führt aus:
+1. `test-runner`-Agent (Haiku): Tests + Coverage
+2. `code-simplifier`-Agent: Code-Review + Refactoring
+3. PR-Erstellung via Gitea-API
+
+---
+
+## Phase 6: Security-Audit
+
+Wird automatisch nach jeder Story durch CLAUDE.md-Regel ausgelöst,
+oder manuell:
+
+```
+# security-audit-Agent starten (Opus)
+Agent(security-audit): Neuen Code auf Sicherheitslücken prüfen
+```
+
+---
+
+## Phase 7: PR-Review & Merge
+
+- Akzeptanzkriterien einzeln als Checkboxen im PR
+- Review-Feedback als separater Commit (nicht amenden)
+- Squash-Merge auf main
+
+---
+
+## Kontext-Strategie pro Phase
+
+| Phase | Kontext-Empfehlung |
+|---|---|
+| Research | Subagenten (Explore) — schützt Haupt-Kontext |
+| Planung | Haupt-Kontext, Opus |
+| Review | Subagent (plan-reviewer) |
+| Implementierung | Haupt-Kontext, bei > 200k: /compact |
+| Test | Subagent (test-runner) |
+| Security | Subagent (security-audit) |
+| PR | Subagent oder Haiku direkt |