From a07c436a7d95c9f28c9b19af83cd8ab572a695c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Tr=C3=B6ger?= Date: Sun, 19 Apr 2026 10:38:30 +0200 Subject: [PATCH] Optimaler Entwicklungs-Workflow eingerichtet MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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) --- SETUP.md | 65 +++++++++++++++++++ agents/plan-reviewer.md | 63 +++++++++++++++++++ hooks/auto-format.sh | 33 ++++++++++ hooks/verify-on-stop.sh | 32 ++++++++++ skills/go.md | 34 ++++++++++ skills/plan-review.md | 35 +++++++++++ skills/story.md | 49 +++++++++++++++ workflow/README.md | 81 ++++++++++++++++++++++++ workflow/models.md | 81 ++++++++++++++++++++++++ workflow/story-lifecycle.md | 122 ++++++++++++++++++++++++++++++++++++ 10 files changed, 595 insertions(+) create mode 100644 SETUP.md create mode 100644 agents/plan-reviewer.md create mode 100755 hooks/auto-format.sh create mode 100755 hooks/verify-on-stop.sh create mode 100644 skills/go.md create mode 100644 skills/plan-review.md create mode 100644 skills/story.md create mode 100644 workflow/README.md create mode 100644 workflow/models.md create mode 100644 workflow/story-lifecycle.md diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..621cee3 --- /dev/null +++ b/SETUP.md @@ -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) +``` diff --git a/agents/plan-reviewer.md b/agents/plan-reviewer.md new file mode 100644 index 0000000..11042ea --- /dev/null +++ b/agents/plan-reviewer.md @@ -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. diff --git a/hooks/auto-format.sh b/hooks/auto-format.sh new file mode 100755 index 0000000..8ce97ff --- /dev/null +++ b/hooks/auto-format.sh @@ -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 diff --git a/hooks/verify-on-stop.sh b/hooks/verify-on-stop.sh new file mode 100755 index 0000000..bbaa22e --- /dev/null +++ b/hooks/verify-on-stop.sh @@ -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 diff --git a/skills/go.md b/skills/go.md new file mode 100644 index 0000000..8c58f40 --- /dev/null +++ b/skills/go.md @@ -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. diff --git a/skills/plan-review.md b/skills/plan-review.md new file mode 100644 index 0000000..8e8022a --- /dev/null +++ b/skills/plan-review.md @@ -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] +``` diff --git a/skills/story.md b/skills/story.md new file mode 100644 index 0000000..924b9f8 --- /dev/null +++ b/skills/story.md @@ -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/ +``` +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. diff --git a/workflow/README.md b/workflow/README.md new file mode 100644 index 0000000..d02a404 --- /dev/null +++ b/workflow/README.md @@ -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` diff --git a/workflow/models.md b/workflow/models.md new file mode 100644 index 0000000..5e914d7 --- /dev/null +++ b/workflow/models.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 diff --git a/workflow/story-lifecycle.md b/workflow/story-lifecycle.md new file mode 100644 index 0000000..1f7f886 --- /dev/null +++ b/workflow/story-lifecycle.md @@ -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 |