Ein Coding-Agent, der sich an Regeln halten soll, braucht mehr als freundliche Bitten im Prompt. Genau hier setzen Hooks in Claude Code an: kleine Shell-Befehle, die an festen Punkten im Ablauf des Agenten zuverlässig ausgeführt werden – vor einem Tool-Aufruf, danach, beim Start einer Sitzung oder wenn der Agent fertig ist. Dieser Guide zeigt, welche Hook-Ereignisse es gibt, wie Sie die Konfiguration sauber im Repository ablegen und welche drei Hooks sich in fast jedem Team sofort lohnen.
Was Hooks leisten und was nicht
Anweisungen in der CLAUDE.md sind Empfehlungen. Das Modell befolgt sie meistens, aber nicht garantiert. Hooks dagegen sind deterministisch: Claude Code ruft das hinterlegte Kommando bei jedem passenden Ereignis auf, unabhängig davon, was das Modell gerade plant. Damit eignen sie sich für alles, was immer passieren muss – Code formatieren, Linter starten, sensible Dateien schützen, Benachrichtigungen verschicken.
Nicht geeignet sind Hooks für komplexe Logik, die selbst wieder Urteilsvermögen braucht. Ein Hook sollte schnell laufen, ein klares Ergebnis liefern und im Fehlerfall verständlich erklären, warum er eingegriffen hat.
Ein gutes Beispiel für die Abgrenzung: Die Regel, nach jeder Änderung den Formatter laufen zu lassen, gehört in einen Hook. Die Regel, bei neuen Features zuerst einen Test zu schreiben, bleibt in der CLAUDE.md, weil sie Verständnis der Aufgabe voraussetzt. Wer diese Trennung früh festlegt, vermeidet doppelte Regeln und Widersprüche zwischen Prompt und Automatisierung.
Die wichtigsten Ereignisse im Überblick
PreToolUse feuert, bevor ein Werkzeug wie Bash, Edit oder Write ausgeführt wird, und kann den Aufruf blockieren. PostToolUse läuft nach erfolgreicher Ausführung und ist der typische Ort für Formatter und Tests. UserPromptSubmit greift, sobald jemand einen Prompt abschickt, und kann zusätzlichen Kontext anhängen. SessionStart lädt beim Sitzungsbeginn etwa den aktuellen Branch-Status. Stop und SubagentStop melden sich, wenn der Agent oder ein Subagent seine Antwort beendet hat, Notification, wenn Claude Code auf eine Eingabe wartet.
Jeder Hook bekommt die Ereignisdaten als JSON über die Standardeingabe, darunter den Tool-Namen und die Parameter. Über einen Matcher, etwa für die Werkzeuge Edit und Write, legen Sie fest, für welche Werkzeuge der Hook gilt. Beendet sich ein Skript mit Exit-Code 2, wird die Aktion blockiert und die Fehlerausgabe als Rückmeldung an Claude übergeben – der Agent kann dann selbst korrigieren.
Hooks Schritt für Schritt anlegen
Hooks stehen in den Settings-Dateien von Claude Code. Für Team-Regeln gehört die Konfiguration in .claude/settings.json im Repository, persönliche Ergänzungen in .claude/settings.local.json oder in die Benutzer-Settings im Home-Verzeichnis.
- Öffnen Sie in Claude Code den Befehl /hooks, um bestehende Hooks zu sehen und neue interaktiv anzulegen.
- Wählen Sie das Ereignis, zum Beispiel PostToolUse, und definieren Sie einen Matcher, der die Werkzeuge Edit und Write abdeckt.
- Hinterlegen Sie ein Kommando, idealerweise ein Skript im Ordner .claude/hooks, das die Datei aus dem JSON-Input liest und gezielt bearbeitet.
- Speichern Sie die Konfiguration in den Projekt-Settings, damit das ganze Team sie per Git erhält.
- Testen Sie den Hook mit einer harmlosen Änderung und prüfen Sie die Ausgabe im Transcript-Modus.
Drei Hooks, die sich fast immer lohnen
Erstens ein Formatter-Hook nach jeder Dateiänderung: Prettier, Black, gofmt oder rustfmt laufen automatisch auf genau der geänderten Datei, und Diffs bleiben sauber. Zweitens ein Schutz-Hook vor Edit und Write, der Änderungen an .env-Dateien, Lockfiles oder Migrationsordnern mit Exit-Code 2 und einer klaren Begründung stoppt. Drittens ein Stop-Hook, der die schnellen Unit-Tests startet und bei Fehlern meldet, dass die Aufgabe noch nicht erledigt ist.
Typische Stolpersteine: Hooks laufen mit Ihren Benutzerrechten, also prüfen Sie jedes Skript wie Produktivcode. Lange Testläufe in PostToolUse bremsen jede einzelne Änderung aus. Und relative Pfade brechen, sobald der Agent das Arbeitsverzeichnis wechselt – nutzen Sie die Projekt-Variable CLAUDE_PROJECT_DIR.
Hooks im Team verankern
Am meisten bringen Hooks, wenn sie Teil eines gemeinsamen Playbooks sind: dokumentiert, versioniert und mit den Regeln aus CLAUDE.md abgestimmt. In den Agentic-Coding-Workshops von neooutput richten unsere AI Code Engineers Hooks direkt in Ihrer echten Codebasis ein, remote oder vor Ort, und erklären, welche Regeln in Hooks und welche besser in Prompts gehören.
Sie möchten wissen, welche Hooks für Ihren Stack sinnvoll sind? Buchen Sie ein kostenloses 15-Minuten-Erstgespräch und wir schauen gemeinsam auf Ihr Setup.
Häufige Fragen
Können Hooks gefährlich sein?
Ja, denn sie führen beliebige Shell-Befehle mit Ihren Rechten aus. Prüfen Sie Hook-Skripte im Code-Review wie jeden anderen Code. Übernehmen Sie keine Hook-Konfigurationen aus unbekannten Quellen ungeprüft.
Wie blockiert ein Hook eine Aktion?
Ein PreToolUse-Hook, der mit Exit-Code 2 endet, verhindert den Tool-Aufruf. Die Fehlerausgabe wird an Claude zurückgegeben, sodass der Agent den Grund kennt und einen anderen Weg wählen kann. Alternativ können Hooks strukturiertes JSON mit einer Entscheidung zurückgeben.
Gelten Hooks auch im Headless-Modus?
Ja. Hooks aus den Projekt-Settings greifen auch, wenn Claude Code per claude -p oder in einer CI-Pipeline läuft. Das macht sie zu einem guten Werkzeug, um Qualitätsregeln in automatisierten Abläufen durchzusetzen.