Claude Code Hooks: Production-Patterns, die keiner zeigt

Das Problem mit höflichen Prompts

"Bitte führe immer Prettier aus, nachdem du Dateien bearbeitet hast."

Ich habe das in CLAUDE.md-Dateien geschrieben, in System-Prompts und in Projekt-Instruktionen. Und Claude befolgt es — meistens. Manchmal vergisst es Claude. Manchmal entscheidet Claude, dass die Datei keine Formatierung braucht. Manchmal steckt Claude mitten in einer komplexen Aufgabe und überspringt es.

Das ist das fundamentale Problem mit prompt-basierten Anweisungen: Es sind Vorschläge, keine Garantien. Hooks lösen das. Sie verwandeln "bitte mach X" in "X passiert jedes einzelne Mal, egal was."

Ich nutze Claude Code mit Hooks in Produktions-Workflows seit Monaten. Hier ist jedes Pattern, das tatsächlich wichtig ist.

Was Hooks wirklich sind

Hooks sind benutzerdefinierte Befehle, die automatisch an bestimmten Punkten in Claude Codes Lifecycle feuern. Sie fangen die KI ab — die KI kontrolliert sie nicht.

Drei Typen existieren:

• Command Hooks — Shell-Skripte, die JSON über stdin empfangen und über Exit-Codes kommunizieren
• Prompt Hooks — senden einen Prompt an Claude für eine Ja/Nein-Entscheidung
• Agent Hooks — spawnen einen Sub-Agenten mit Read/Grep/Glob-Zugriff zur Verifikation

Die kritische Unterscheidung: Hooks laufen mit deinen vollen System-Berechtigungen. Keine Sandbox. Sie können alles lesen, ändern oder löschen, worauf dein Account Zugriff hat. Anthropics Disclaimer: "USE AT YOUR OWN RISK."

Konfiguration lebt an drei Orten:

• ~/.claude/settings.json — benutzerweit, gilt überall
• .claude/settings.json — projektspezifisch, ins Version Control committen
• .claude/settings.local.json — persönliche Overrides, nicht committen

Seit Claude Code 2.1 kannst du Hooks auch direkt in Agent- und Skill-Frontmatter einbetten. Dazu später mehr.

Die 13 Lifecycle-Events

Claude Code bietet 13 Hook-Points. Hier die Übersicht:

Session-Lifecycle:

• Setup — vor Session-Start (über --init / --maintenance Flags)
• SessionStart — wenn die Session startet oder wiederaufgenommen wird
• SessionEnd — wenn die Session endet

Jeder Conversation-Turn:

• UserPromptSubmit — User drückt Enter, bevor Claude verarbeitet
• PreToolUse — bevor ein Tool ausgeführt wird (kann blocken oder modifizieren)
• PermissionRequest — wenn Claude um Erlaubnis fragt (kann auto-approven)
• PostToolUse — nachdem ein Tool erfolgreich war
• PostToolUseFailure — nachdem ein Tool fehlschlägt
• Stop — wenn Claude mit der Antwort fertig ist

Agent-Koordination:

• SubagentStart — Sub-Agent startet
• SubagentStop — Sub-Agent beendet

Notifications und Maintenance:

• Notification — Permission-Prompts, Idle-Alerts
• PreCompact — bevor das Context-Window komprimiert wird

Das Exit-Code-System ist simpel: Exit 0 heißt weiter, Exit 2 heißt Aktion blocken, alles andere ist ein Fehler.

Pattern 1: Auto-Format bei jedem Write

Der häufigste Hook. Nachdem Claude eine Datei schreibt oder bearbeitet, formatiert Prettier sie automatisch.

Hook auf PostToolUse, Matcher Write|Edit|MultiEdit. Der Befehl führt npx prettier --write auf den Dateipfad aus $CLAUDE_TOOL_INPUT_FILE_PATH aus. ESLint danach für Lint-Fixes verketten.

Das ist deterministisch. Claude entscheidet nicht, ob formatiert wird. Es passiert. Jedes Mal. Ich habe über diese Art von deterministischer Kontrolle als Fundament agentischer Architekturen geschrieben — Hooks sind die einfachste Umsetzung dieses Prinzips.

Pattern 2: Gefährliche Befehle blocken

PreToolUse-Hook auf Bash. Das Shell-Skript liest den JSON-Input von stdin, extrahiert den Befehl und prüft gegen eine Blocklist: rm -rf /, DROP TABLE, git push --force, chmod 777.

Exit 2 zum Blocken. Exit 0 zum Erlauben. Der Hook feuert bevor der Befehl läuft — Claude führt die gefährliche Operation nie aus.

Das ist wichtiger als die meisten denken. Ich habe gesehen, wie Claude rm -rf auf Verzeichnissen versucht hat, die es nicht anfassen sollte. Nicht böswillig — einfach selbstbewusst falsch darüber, was aufgeräumt werden muss. Ein 10-Zeilen-Bash-Skript verhindert alles.

Pattern 3: Sichere Operationen auto-approven

PermissionRequest-Hook mit Matcher Bash(npm test*)|Bash(npm run lint*). Das Skript gibt eine Allow-Decision für passende Befehle zurück.

Das eliminiert den Permissions-Dialog für Operationen, die du bereits als sicher eingestuft hast. Kein "Approve" mehr 50 Mal klicken während einer Test-Driven-Development-Session.

Wichtiger Vorbehalt: PermissionRequest-Hooks feuern nicht im nicht-interaktiven Modus (-p). Wenn du Claude Code headless betreibst, nutze stattdessen PreToolUse.

Pattern 4: Async Test Runner (Jan 2026)

Das ist neu. Seit Claude Code 2.1 können Hooks im Hintergrund laufen, ohne Claude zu blockieren. Füge "async": true zur Hook-Config hinzu.

Boris Cherny kündigte das am 25. Januar an: "Hooks can now run in the background without blocking Claude Code's execution."

PostToolUse-Hook auf Write, Async-Modus. Das Skript triggert deine Test-Suite im Hintergrund. Claude arbeitet sofort weiter. Wenn die Tests fertig sind, erscheinen die Ergebnisse beim nächsten Conversation-Turn.

Der Tradeoff ist explizit: Async-Hooks können Claudes Verhalten nicht blocken oder steuern. Die decision- und permissionDecision-Felder haben keinen Effekt. Jede Ausführung erstellt einen separaten Hintergrundprozess — keine Deduplizierung.

Geeignet für: Test-Suites, CI-Trigger, Log-Shipping, Backup-Erstellung. Nicht geeignet für alles, wo Claude das Ergebnis braucht, bevor es weiterarbeitet.

Pattern 5: Setup Hooks — Onboarding mit einem Befehl

Ebenfalls am 25. Januar 2026 released. Setup-Hooks laufen bevor die Session startet.

Drei CLI-Flags triggern sie:

• claude --init — führt das Setup aus, startet dann die Session
• claude --init-only — führt das Setup aus, beendet dann (CI-freundlich)
• claude --maintenance — führt Maintenance-spezifische Hooks aus

Der Killer-Use-Case: Team-Onboarding. Neuer Entwickler klont das Repo, führt claude --init aus, und der Hook installiert Dependencies, setzt die Datenbank auf, konfiguriert Umgebungsvariablen und validiert, dass alles funktioniert. Ein Befehl.

Das --init-only Flag ist für CI/CD-Pipelines designed. Es führt den Hook aus und gibt einen Exit-Code zurück — null für Erfolg, ungleich null für Fehler. Keine interaktive Session nötig. Das verbindet sich mit derselben Philosophie, die ich beim Bauen von Umgebungen statt Personas beschrieben habe — die Umgebung konfiguriert sich selbst.

Pattern 6: PreCompact Backup

Wenn Claude Codes Context-Window voll wird, komprimiert es die Conversation. Das passiert automatisch und ist irreversibel — das vollständige Transkript ist weg.

Ein PreCompact-Hook speichert die gesamte Conversation in eine Datei mit Zeitstempel, bevor die Komprimierung passiert. Simpel: Das Skript liest die Session-Daten und schreibt sie nach .claude/backups/.

Ich habe Debugging-Kontext durch Compaction mehr als einmal verloren. Dieser Hook verhindert das permanent.

Pattern 7: SessionStart Context Injection

SessionStart-Hook, der Git-Status, letzte Commits, offene Issues und die TODO-Liste deines Projekts lädt — und Claude als initialen Kontext übergibt.

Jede Session startet mit Claude, das bereits weiß, was sich seit dem letzten Mal geändert hat. Kein "lass mich mal das Git-Log checken" mehr am Anfang jeder Conversation.

Pattern 8: Stop Hook — Completion Enforcement

Stop-Hooks feuern, wenn Claude mit der Antwort fertig ist. Wenn du Exit 2 zurückgibst, wird Claude gezwungen weiterzumachen.

Das Pattern: Führe deine Test-Suite im Stop-Hook aus. Wenn Tests fehlschlagen, blocke die Completion und gib den Fehler-Output zurück an Claude. Claude sieht die fehlschlagenden Tests und fixt sie, bevor es fertig werden kann.

Das macht Claude Code zu einem selbstkorrigierenden System. Der Agent kann nicht "fertig" deklarieren, bis die objektiven Kriterien bestanden sind.

Zwei Fallstricke: Stop-Hooks feuern bei jeder Antwort, nicht nur bei Task-Completion. Und sie feuern nicht bei User-Interrupts (Ctrl+C). Entsprechend designen.

Pattern 9: Tool Input Modification

Seit v2.0.10 können PreToolUse-Hooks Tool-Inputs still vor der Ausführung modifizieren. Claude weiß nicht, dass die Inputs geändert wurden.

Use Cases, die zählen:

• --dry-run Flags bei destruktiven Befehlen erzwingen
• Dateipfade in ein Sandbox-Verzeichnis umleiten
• Secrets aus Befehlsargumenten entfernen
• Commit-Message-Formatierung erzwingen

Der Hook gibt updatedInput in seinem JSON-Output zurück. Claude sieht seinen originalen Befehl — die modifizierte Version ist das, was tatsächlich läuft.

Das ist das mächtigste und gefährlichste Pattern. Unsichtbare Modifikation bedeutet unsichtbare Bugs, wenn dein Hook Fehler hat.

Pattern 10: Skill-Scoped Hooks (Claude Code 2.1)

Die neueste Ergänzung. Hooks, die in Agent- oder Skill-Frontmatter-Dateien definiert werden.

Eine Markdown-Skill-Datei mit YAML-Frontmatter, das Hook-Definitionen enthält. Die Hooks reisen mit dem Skill — installiere den Skill, bekomme die Governance gratis.

Das ist signifikant für Teams. Statt dass jeder Entwickler Hooks manuell konfiguriert, bettet der Skill-Autor die Sicherheitschecks ein. Ein "Datenbank-Migration"-Skill enthält Hooks, die destruktives SQL blocken. Ein "Deployment"-Skill enthält Hooks, die Staging-first erzwingen.

Die drei Typen: Wann was nutzen

Command Hooks für alles Deterministische. Datei-Formatierung, Security-Blocking, Test-Running, Backups. Schnell, vorhersagbar, volle Kontrolle.

Prompt Hooks für Ermessensentscheidungen. "Sieht diese Datei aus, als enthielte sie Secrets?" "Ist diese Commit-Message beschreibend genug?" Das LLM bewertet und gibt Ja/Nein zurück. Kann nicht async laufen.

Agent Hooks für komplexe Verifikation. Der Hook spawnt einen Sub-Agenten mit Zugriff auf Read, Grep und Glob. Er kann Dateien inspizieren, Muster prüfen und informierte Entscheidungen treffen. Schwerer als Prompt-Hooks, aber leistungsfähiger.

Mein Verhältnis: 90% Command Hooks, 8% Prompt Hooks, 2% Agent Hooks. Determinismus schlägt Intelligenz bei den meisten operativen Patterns.

Was Hooks nicht können

Ehrliche Limitierungen:

• PostToolUse-Hooks können Aktionen nicht rückgängig machen. Das Tool ist schon gelaufen. Du kannst reagieren, aber nicht umkehren.
• Async-Hooks können nicht blocken. By Design. Die Aktion ist bereits weitergelaufen.
• Stop-Hooks feuern bei jeder Antwort. Nicht nur bei Task-Completion. Deine Test-Suite wird auch bei lockeren Antworten laufen, es sei denn, du baust Logik ein, um Task-Kontext zu erkennen.
• Keine Deduplizierung. Wenn Claude 10 Dateien schnell schreibt, feuert dein PostToolUse-Hook 10 Mal. Plane für Nebenläufigkeit.
• SubagentStop Prompt-Hooks sind buggy. Sie senden Feedback, verhindern aber nicht die Terminierung (GitHub Issue #20221).

Security: Die ehrliche Version

Hooks führen beliebige Shell-Befehle mit deinen vollen Benutzerrechten aus. Es gibt keine Sandbox.

Ein Sicherheitsmechanismus existiert: Wenn jemand deine Hooks-Settings-Datei direkt modifiziert (nicht über Claude Codes /hooks-Menü), werden die Änderungen nicht sofort wirksam. Du musst sie reviewen. Das verhindert, dass ein kompromittiertes Tool bösartige Hooks mid-Session injiziert.

Best Practices: Validiere und sanitize alle Inputs von stdin, quote jede Shell-Variable, nutze absolute Pfade, blocke Path-Traversal-Versuche und überspringe Operationen auf sensiblen Dateien (.env, Credentials).

Das Fazit

Hooks sind das am meisten unterschätzte Feature in Claude Code. Sie lösen das fundamentale Zuverlässigkeitsproblem der KI-gestützten Entwicklung: die Lücke zwischen "Claude macht X meistens" und "X passiert immer."

Die neuen Ergänzungen — Async-Hooks für nicht-blockierende Operationen, Setup-Hooks fürs Team-Onboarding und Skill-Scoped-Hooks für portable Governance — verwandeln das von einem Komfort-Feature in ein Produktions-Infrastruktur-Tool.

Starte mit Pattern 1 (Auto-Format) und Pattern 2 (gefährliche Befehle blocken). Füge den Rest hinzu, wenn dein Workflow es verlangt. Die Konfiguration ist JSON in einer Settings-Datei. Keine Dependencies. Kein Build-Step. Einfach deterministische Kontrolle über probabilistische KI.