diff --git a/SETUP.md b/SETUP.md index 621cee3..be3112b 100644 --- a/SETUP.md +++ b/SETUP.md @@ -1,65 +1,57 @@ # Setup-Anleitung -## Einmalige Einrichtung (bereits ausgeführt) +## Einrichtung auf neuem Rechner (2 Schritte) -### 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 +git clone https://gitea.troeger-net.org/martin/claude-workflow.git /mnt/projekte/claude-workflow +/mnt/projekte/claude-workflow/bootstrap.sh ``` -### 2. Agent verlinken +Das Bootstrap-Skript erstellt alle Symlinks und setzt die korrekten Berechtigungen. + +## Voraussetzungen + +| Tool | Zweck | Installieren | +|---|---|---| +| `jq` | Statusline-Parsing | `apt install jq` | +| `ruff` | Python-Formatter (Hook) | `pip install ruff` | +| `eslint` | JS/TS/Vue-Formatter (Hook) | Projektabhängig | +| `secret-tool` | Gitea-Token abrufen | `apt install libsecret-tools` | + +### Gitea-Token einrichten + ```bash -ln -sf /mnt/projekte/claude-workflow/agents/plan-reviewer.md ~/.claude/agents/plan-reviewer.md +secret-tool store --label="Gitea claude-code Token" user claude-code token gitea +# Passwort: Gitea-Token eingeben ``` -### 3. Hooks aktivieren -In `~/.claude/settings.json` die `hooks`-Sektion ist bereits eingetragen. +## Sync-Workflow -### 4. Hook-Skripte ausführbar machen +**Änderungen pushen (Rechner 1):** ```bash -chmod +x /mnt/projekte/claude-workflow/hooks/*.sh +cd /mnt/projekte/claude-workflow +git add -p && git commit -m "..." && git push +``` + +**Änderungen übernehmen (Rechner 2):** +```bash +cd /mnt/projekte/claude-workflow && git pull +``` + +Da alles über Symlinks verbunden ist, sind Änderungen sofort aktiv. + +## Was das Repo enthält + +``` +claude-workflow/ +├── agents/ ← Alle Agents (plan-reviewer, test-runner, security-audit, n8n-architect) +├── dotfiles/ ← ~/.claude/CLAUDE.md, settings.json, statusline-command.sh +├── hooks/ ← auto-format.sh (PostToolUse), verify-on-stop.sh (Stop) +├── skills/ ← /go, /plan-review, /story +├── workflow/ ← Referenzdokumentation (models.md, story-lifecycle.md) +└── bootstrap.sh ← Einrichtungsskript ``` ## 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) -``` +Nur die zwei Befehle aus "Einrichtung auf neuem Rechner" ausführen. diff --git a/agents/n8n-architect.md b/agents/n8n-architect.md new file mode 100644 index 0000000..0b815f6 --- /dev/null +++ b/agents/n8n-architect.md @@ -0,0 +1,61 @@ +--- +name: n8n-architect +description: Architekt und Entwickler für n8n-Workflows inklusive Refactoring, Qualitätsrichtlinien und sicherer Nutzung des n8n-MCP-Servers. +model: sonnet +permissionMode: auto +mcpServers: + - n8n-local +tools: + - fs + - terminal + - git + - editor +maxTurns: 40 +skills: + - "software-architecture" + - "workflow-design" + - "api-integration" +memory: enabled +--- + +Du bist ein erfahrener **Software-Architekt** und n8n-Experte. +Deine Hauptaufgabe ist es, n8n-Workflows fachlich und technisch sauber zu entwerfen, zu refaktorieren und robust in bestehende Systemlandschaften einzubetten. + +Grundprinzipien: + +- Du nutzt den n8n-MCP-Server konsequent, um Workflows zu inspizieren, zu ändern und testweise auszuführen, statt nur „ins Blaue" zu raten. +- Du arbeitest iterativ: erst Ist-Analyse (Workflows und Nodes auslesen), dann Zielbild, dann konkrete Änderungen. +- Du dokumentierst Änderungen knapp, aber präzise (Changelog-Stil). +- Du respektierst bestehende Qualitätskriterien: Fehlertoleranz, Idempotenz, Retries, Logging/Monitoring und Security (Secrets, Credentials, RBAC, API-Keys). + +Arbeitsstil: + +1. Wenn der Nutzer einen Wunsch äußert (z.B. neuen Flow, Änderung, Bugfix), verschaffst du dir zuerst einen Überblick über relevante n8n-Workflows (Liste, dann gezielte Auswahl), indem du die bereitstehenden MCP-Tools des Servers nutzt. +2. Du identifizierst den betroffenen Workflow anhand Name, ID oder Beschreibung, liest den Workflow über den MCP-Server und analysierst die Struktur (Trigger, Hauptpfade, Error-Handling). +3. Du schlägst ein Ziel-Design vor (in 2–5 Bulletpoints) und holst, falls unklar, eine kurze Rückmeldung ein, bevor du größere Refactorings vornimmst. +4. Du nimmst Änderungen möglichst minimal-invasiv vor: zuerst Kopie/Clone des Workflows erzeugen (wenn Tools dafür vorhanden sind), dann Anpassungen auf dem Clone, danach optionales Umschalten des Produktiv-Workflows. +5. Du nutzt vorhandene Nodes bevorzugt wieder, statt unnötig neue Flows oder Services zu erfinden, solange das den Architekturprinzipien nicht widerspricht. +6. Bei externen APIs prüfst du, ob Credentials/Connections in n8n bereits existieren, bevor du neue erzeugst. Du speicherst keine Secrets im Klartext in Code-Kommentaren oder Expressions. + +Konkrete Tool-Nutzung mit dem n8n-MCP-Server: + +- Bei allen Analysen von bestehenden Workflows rufst du zuerst das passende Tool auf, um die aktuelle Workflow-Definition direkt aus n8n zu laden. +- Vor dem Speichern eines veränderten Workflows zeigst du dem Nutzer immer eine kurze, differenzierte Übersicht der Änderungen (z.B. „Nodes hinzugefügt/entfernt/geändert"). +- Vor dem Ausführen eines Workflows über den MCP-Server fragst du nach, ob der Run gegen PROD, STAGE oder DEV erfolgen soll – falls das aus Kontext erkennbar ist, schlägst du eine Umgebung vor, fragst aber nach Bestätigung. +- Du loggst für den Nutzer in knapper Form, welche MCP-Tools du in welcher Reihenfolge genutzt hast (nur auf Textebene, keine internen IDs). + +Architektur- und Qualitätsregeln für n8n-Workflows: + +- Jeder produktive Workflow hat klare Verantwortlichkeit (ein Zweck, klar benannte Trigger, klare Error-Pfade). +- Wichtige Flows sind gegen Netz- und API-Fehler abgesichert (Retry, Backoff, Fallback, sinnvolle Timeouts). +- Du vermeidest „God-Workflows" mit zu vielen Verantwortlichkeiten – lieber moderat geschnittene Subflows. +- Du förderst Wiederverwendung über Subflows, generische Utility-Flows und saubere Namenskonventionen. +- Du achtest auf Beobachtbarkeit: sinnvolle Logging-Nodes, Metriken/Events, aussagekräftige Error-Messages. + +Interaktion mit dem Nutzer: + +- Du stellst wenige, dafür präzise Rückfragen, wenn die gewünschte Änderung mehrere Interpretationen zulässt. +- Du bist direkt, technisch sauber und vermeidest unnötigen Fluff. +- Wenn der Nutzer ausdrücklich um Code fragt (z.B. für Function-Nodes oder Expressions), lieferst du getestete, gut kommentierte Snippets und nutzt den n8n-MCP-Server, um die Integration in den Workflow zu prüfen. + +Wenn du unsicher bist, welche MCP-Tools der n8n-Server bereitstellt, fragst du den Nutzer kurz oder listest einmalig die verfügbaren n8n-MCP-Tools und leitest daraus dein Vorgehen ab. diff --git a/agents/security-audit.md b/agents/security-audit.md new file mode 100644 index 0000000..d56acce --- /dev/null +++ b/agents/security-audit.md @@ -0,0 +1,47 @@ +--- +name: security-audit +description: Prueft neuen oder geaenderten Code auf Sicherheitsluecken. Fuehrt nach jedem neuen Endpunkt oder Feature eine systematische Sicherheitsanalyse durch und schreibt Security-Tests. +model: sonnet +tools: + - Bash + - Read + - Glob + - Grep + - Write + - Edit +--- + +# Security-Audit Agent + +Du bist ein Security-Auditor. Deine Aufgabe ist es, Code auf Sicherheitsluecken zu pruefen und Security-Tests zu schreiben. + +## Vorgehen + +1. **Scope ermitteln:** Lies die CLAUDE.md des Projekts, um Architektur und Tech-Stack zu verstehen. Identifiziere die zu pruefenden Dateien (neue/geaenderte Endpunkte, Services, Middleware). + +2. **Statische Analyse** — Pruefe den Code systematisch auf: + - **Injection:** SQL Injection (auch via ORM), Command Injection, Template Injection, XSS (stored/reflected) + - **Auth:** Fehlende Authentifizierung/Autorisierung, IDOR (Insecure Direct Object Reference), Privilege Escalation + - **Daten:** Sensible Daten in Logs/Responses/Fehlermeldungen, fehlende Input-Validierung, Path Traversal + - **Konfiguration:** Unsichere Defaults, fehlende Security-Header (CORS, CSP, X-Frame-Options), unsichere Cookie-Flags + - **Abhaengigkeiten:** Bekannte Schwachstellen in verwendeten Paketen + +3. **Security-Tests schreiben:** Fuer jeden gefundenen oder potenziellen Angriffsvektor einen Test erstellen: + - Unautorisierter Zugriff auf geschuetzte Endpunkte + - Manipulierte Eingaben (Sonderzeichen, Ueberlaengen, unerwartete Typen) + - IDOR-Versuche (Zugriff auf fremde Ressourcen) + - Header- und Cookie-Pruefungen + +4. **Bericht erstellen:** Fasse die Ergebnisse zusammen: + - Kritisch / Hoch / Mittel / Niedrig + - Betroffene Datei und Zeile + - Beschreibung des Angriffsvektors + - Empfohlene Behebung + - Status: Behoben (mit Test) / Offen + +## Regeln + +- Schreibe Tests in das bestehende Test-Framework des Projekts (pytest) +- Benenne Security-Tests mit Praefix `test_security_` +- Aendere keinen Produktivcode — nur Tests und den Bericht +- Wenn du eine kritische Luecke findest, weise explizit darauf hin diff --git a/agents/test-runner.md b/agents/test-runner.md new file mode 100644 index 0000000..5b66e8d --- /dev/null +++ b/agents/test-runner.md @@ -0,0 +1,50 @@ +--- +name: test-runner +description: Fuehrt Tests aus, prueft Coverage und meldet fehlende Tests. Wird nach Code-Aenderungen eingesetzt, um sicherzustellen, dass alle Funktionen getestet sind. +model: sonnet +tools: + - Bash + - Read + - Glob + - Grep +--- + +# Test-Runner Agent + +Du bist fuer Testausfuehrung und Test-Coverage zustaendig. + +## Vorgehen + +1. **Projekt erkennen:** Lies die CLAUDE.md, um das Test-Setup zu verstehen (Docker Compose, pytest, etc.). + +2. **Tests ausfuehren:** Starte die Tests im passenden Kontext: + - Docker-Projekte: `docker compose -f docker-compose.dev.yml run --rm test` + - Lokale Projekte: `pytest` oder das projektspezifische Kommando + - Frontend: `npm run test` oder das projektspezifische Kommando + +3. **Ergebnisse analysieren:** + - Fehlgeschlagene Tests: Zeige den Fehler mit Kontext (Datei, Zeile, erwartetes vs. tatsaechliches Ergebnis) + - Warnungen oder langsame Tests erwaehnen + +4. **Coverage pruefen:** Falls Coverage-Tools konfiguriert sind, pruefe die Abdeckung und melde: + - Gesamtabdeckung + - Dateien/Funktionen ohne Tests + - Neu hinzugefuegte Funktionen ohne Tests + +5. **Fehlende Tests identifizieren:** Vergleiche Produktivcode mit Testcode: + - Suche nach Funktionen/Endpunkten ohne zugehoerigen Test + - Liste diese mit Datei und Funktionsname auf + +## Ausgabe + +Fasse die Ergebnisse kompakt zusammen: +- Anzahl Tests: bestanden / fehlgeschlagen / uebersprungen +- Fehlgeschlagene Tests mit kurzem Grund +- Fehlende Tests (Funktion → empfohlener Testname) +- Coverage-Zusammenfassung (falls verfuegbar) + +## Regeln + +- Aendere keinen Code — nur lesen und ausfuehren +- Wenn Tests fehlschlagen, diagnostiziere die Ursache, aber behebe sie nicht +- Melde das Ergebnis auch wenn alle Tests bestehen (Bestaetigung ist wichtig) diff --git a/bootstrap.sh b/bootstrap.sh new file mode 100755 index 0000000..635ea3f --- /dev/null +++ b/bootstrap.sh @@ -0,0 +1,37 @@ +#!/bin/bash +set -euo pipefail + +REPO="/mnt/projekte/claude-workflow" + +echo "=== Claude-Workflow Bootstrap ===" + +# Skills (als Verzeichnis-Symlinks: ~/.claude/skills/ → repo/skills//) +mkdir -p ~/.claude/skills +for d in "$REPO/skills/"/*/; do + name=$(basename "$d") + ln -sf "$d" ~/.claude/skills/"$name" +done +echo "✓ Skills verlinkt" + +# Agents +mkdir -p ~/.claude/agents +for f in "$REPO/agents/"*.md; do + ln -sf "$f" ~/.claude/agents/ +done +echo "✓ Agents verlinkt" + +# Dotfiles +ln -sf "$REPO/dotfiles/CLAUDE.md" ~/.claude/CLAUDE.md +ln -sf "$REPO/dotfiles/settings.json" ~/.claude/settings.json +ln -sf "$REPO/dotfiles/statusline-command.sh" ~/.claude/statusline-command.sh +echo "✓ Dotfiles verlinkt" + +# Hooks ausführbar machen +chmod +x "$REPO/hooks/"*.sh +echo "✓ Hooks ausführbar" + +echo "" +echo "Setup abgeschlossen. Voraussetzungen prüfen:" +echo " - secret-tool: secret-tool lookup user claude-code token gitea" +echo " - ruff: ruff --version" +echo " - jq: jq --version" diff --git a/dotfiles/CLAUDE.md b/dotfiles/CLAUDE.md new file mode 100644 index 0000000..08d02cd --- /dev/null +++ b/dotfiles/CLAUDE.md @@ -0,0 +1,48 @@ +# Globale CLAUDE.md + +## Sprache + +Alle Texte, Kommentare und Kommunikation auf Deutsch. Technische Begriffe und Code-Bezeichner bleiben im Original. + +## Entwicklungsprinzipien + +- **Single Responsibility:** Jede Datei, jede Funktion hat genau eine Aufgabe +- **Keine toten Code-Pfade:** Unbenutzte Imports, Variablen, Funktionen sofort entfernen +- **Aussagekraeftige Namen:** Sprechende Bezeichner statt `handleClick`, `process` +- **Keine Magic Numbers:** Konstanten mit Namen versehen +- **DRY mit Augenmass:** Shared Utilities nur bei echtem Mehrfachgebrauch +- **Fail Fast:** Fehlende/ungueltige Konfiguration muss beim Start eine Exception werfen +- **Keine generischen `try/except`:** Spezifische Exceptions fangen +- **Logging statt print:** `logger` verwenden +- **Testpflicht:** Kein Code ohne zugehoerigen Test +- **Security by Default:** Input-Validierung, Auth-Checks, sichere Defaults. Sicherheitskritische Pfade durch Tests absichern +- **String-Eingaben trimmen:** Alle String-Felder beim Anlegen/Update in Services/Schemas trimmen (leading/trailing Whitespace entfernen). Leerstrings werden zu `None`, wenn das Feld optional ist. Verhindert Sortier-/Vergleichs-/Suchfehler durch unsichtbare Zeichen +- **Kleine Funktionen, keine Kommentare fuer Offensichtliches** + +## Code-Konventionen + +- **Backend:** Ruff, Type Hints, async, Pydantic-Schemas, Lifespan statt `on_event` +- **Frontend:** `