claude-workflow/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Zweck

Dieses Repository enthält die globale Claude-Code-Workflow-Konfiguration für alle Projekte von Martin Tröger. Es definiert Skills, Agenten, Hooks und Dokumentation — kein ausführbarer Anwendungscode.

Einrichtung

Neuer Rechner (2 Schritte)

git clone https://gitea.troeger-net.org/martin/claude-workflow.git <pfad>
<pfad>/bootstrap.sh

Der Pfad ist frei wählbar. Das Bootstrap-Skript erstellt alle Symlinks, prueft Voraussetzungen und zeigt fehlende Installationsbefehle an.

Voraussetzungen

Tool	Zweck	Installieren
jq	Statusline-Parsing	apt install jq
ruff	Python-Formatter (Hook)	pipx install ruff
eslint	JS/TS/Vue-Formatter (Hook)	Projektabhängig
shellcheck	Bash-Linter (Hook + /script)	apt install shellcheck
fnm + Node.js	Node-Version-Manager	curl -fsSL https://fnm.vercel.app/install | bash && fnm install --lts
markdownlint-cli2	Markdown-Lint (Hook)	npm install -g markdownlint-cli2
gh	GitHub CLI	apt install gh
go + gitea-mcp	Gitea-MCP-Binary	go install gitea.com/gitea/gitea-mcp@latest

Gitea-Token einrichten

mkdir -p ~/.config/gitea && chmod 700 ~/.config/gitea
echo 'DEIN_TOKEN' > ~/.config/gitea/token && chmod 600 ~/.config/gitea/token

Sync zwischen Rechnern

Pushen (Rechner 1):

cd <repo-pfad>
git add -p && git commit -m "..." && git push

Übernehmen (Rechner 2):

cd <repo-pfad> && git pull

Da alles über Symlinks verbunden ist, sind Änderungen sofort aktiv.

Workflow-Weiterentwicklung

Beim Aktualisieren dieses Workflows immer zuerst die externe Best-Practice-Referenz konsultieren und auf relevante Neuerungen prüfen:

https://github.com/shanraisshan/claude-code-best-practice

Vorgehen: URL via WebFetch abrufen → mit aktuellem Workflow vergleichen → Abweichungen bewerten → bei Bedarf anpassen.

Struktur

skills/              ← Slash-Commands (Symlinks nach ~/.claude/skills/)
agents/              ← Agenten-Definitionen (Symlinks nach ~/.claude/agents/)
hooks/               ← Shell-Hooks (durch settings.json registriert)
dotfiles/            ← ~/.claude/CLAUDE.md, settings.json, statusline-command.sh
skills-optimization/ ← Eval-Datensätze für Skill-Performance-Messung
bootstrap.sh         ← Einrichtungsskript

Aktivierung (nach Neuinstallation)

Nach System-Neuinstallation bootstrap.sh ausführen (erstellt alle Symlinks automatisch).

Story-Lifecycle

Research → Plan (Opus) → /plan-review → Implement (Sonnet) → /go → Security-Audit

Kurzbefehl für den gesamten Ablauf: /story

Phase	Befehl	Modell
Planung	EnterPlanMode	Opus 4.6
Plan-Review	/plan-review	Opus 4.6 (Subagent)
Implementierung	direkt	Sonnet 4.6
Test + Simplify + PR	/go	Haiku / Sonnet (Subagenten)
Commit + PR + Merge	/ship	Sonnet (fork)
Security-Audit	security-audit-Agent	Opus 4.6

Skills

Befehl	Datei	Beschreibung
/go	skills/go/SKILL.md	test-runner → code-simplifier → Gitea-PR
/ship	skills/ship/SKILL.md	Commit → Push → PR → Merge → Cleanup (finales Kommando)
/plan-review	skills/plan-review/SKILL.md	Startet plan-reviewer-Agent (Opus, fork)
/script	skills/script/SKILL.md	Bash-Script-Lifecycle: Planung (Opus) → Implementierung (Sonnet) → Shellcheck + Test-Empfehlungen → /ship
/story	skills/story/SKILL.md	Voller Lifecycle von Research bis PR
/workflow-review	skills/workflow-review/SKILL.md	Opus reviewt alle Skills/Konfig → Umsetzungsplan für Sonnet
/implement	skills/implement/SKILL.md	Implementierung direkt aus bestehendem Plan (überspringt Research/Planung)

Agenten

Agent	Modell	Tools	Rolle
plan-reviewer	Opus 4.6	Read, Glob, Grep	Prüft Pläne auf Vollständigkeit, Risiken, fehlende Tests
test-runner	Haiku 4.5	alle	Tests ausführen, Coverage prüfen
security-audit	Opus 4.6	alle	OWASP-Analyse, Security-Tests schreiben
n8n-architect	Opus 4.6	alle	n8n-Workflow-Design und Refactoring

Hooks

Event	Trigger	Skript	Aktion
PreToolUse	Bash	hooks/pre-bash-checks.sh	Git-main-Schutz, apt -y Blockade
PostToolUse	Edit / Write	hooks/auto-format.sh	ruff (Python), eslint --fix (JS/TS/Vue) oder shellcheck (Bash)
Stop	Session-Ende	hooks/verify-on-stop.sh	Uncommittete Änderungen anzeigen

auto-format.sh liest den Dateipfad aus $CLAUDE_TOOL_INPUT_FILE_PATH und erkennt den Typ anhand der Dateiendung.

Modell-Strategie

• Opus 4.6: Planung, Plan-Review, Security-Audit — überall wo Fehlentscheidungen teuer sind
• Sonnet 4.6: Implementierung, Refactoring, Bug-Fixes (Standard)
• Haiku 4.5: Tests, Lint, Format, PR-Beschreibung

/fast aktiviert Opus 4.6 mit schnellerer Ausgabe — sinnvoll bei langen Implementierungen.

Kontext-Management

• < 200k Tokens: Normal weiterarbeiten
• 200–350k Tokens: /compact "aktueller Stand: [Hinweis]" ausführen
• > 350k Tokens: Neue Session, isolierte Subagenten bevorzugen

Git-Workflow (Abweichung von globaler CLAUDE.md)

In diesem Repository wird direkt auf main committet — ohne Feature-Branches und ohne PRs. Die globale Regel „Niemals direkt auf main committen" gilt hier nicht, da es sich um ein Konfigurations-Repo ohne Deployment-Pipeline handelt.

Gitea-Integration

• Instanz: https://gitea.troeger-net.org
• Token für Gitea-MCP: $(secret-tool lookup user claude-code token gitea)
• MCP-Server gitea muss aktiv sein (Binary: ~/go/bin/gitea-mcp)