Claude Code Hooks und Rules: Team-Konventionen in der KI-gestützten Entwicklung durchsetzen
KI-Coding-Assistenten ermöglichen es allen, eine Codebasis zu ändern, auch Personen, die die Konventionen des Teams nie gesehen haben. Software Engineer Raúl Avilés Saltos erklärt, warum zusätzliche Anweisungen in CLAUDE.md das Problem nicht lösen und wie sein Team mit Claude Code Hooks und Rules dafür sorgt, dass diese Konventionen für alle gelten, die am Code mitarbeiten, ob sie sie kennen oder nicht.
Das Wichtigste in Kürze
- Mit KI-Coding-Assistenten können mehr Menschen zu einer Codebasis beitragen. Anweisungen in
CLAUDE.mdsind jedoch Kontext und keine Durchsetzung, deshalb befolgt Claude sie nur manchmal. - In seinem aktuellen Projekt hat Raúl die Konventionen des Teams ins Repository verlagert: Hooks laufen bei jeder Änderung, um Dateien zu linten, den Zugriff auf Secrets zu blockieren und geschäftliche Grenzen durchzusetzen. Rules liefern Claude die passenden Konventionen, sobald es mit einer entsprechenden Datei arbeitet.
- Das Ergebnis sind weniger wiederholte PR-Kommentare: In den zwei Monaten nach der Umstellung sank die Zahl der Review-Kommentare zu Konventionen in den Frontend-PRs des Teams von 12 bei 88 PRs auf drei bei 110. Die Konventionen gelten jetzt für alle Mitwirkenden, und Schutzmechanismen für Daten, Sicherheit und Geld hängen nicht mehr vom Urteil des Modells ab.
Montagmorgen. Ein Pull Request kommt herein, der nicht aus Ihrem Team stammt.
Vielleicht brauchte jemand aus dem Backend eine kleine Korrektur im Frontend, vielleicht ist jemand neu im Team und in der ersten Woche, vielleicht hat jemand aus einem anderen Team den Code einmal angefasst und wird ihn nie wiedersehen. Alle haben dasselbe getan: das Repository geöffnet, Claude um die Änderung gebeten und gepusht.
Der Code funktioniert, aber der PR enthält unformatierte Dateien, eine Lint-Warnung, um die sich niemand gekümmert hat, und ein px, wo sich das Team schon vor Monaten auf rem geeinigt hat. Nichts davon ist dramatisch, aber alles landet im Review.
Das ist die Situation, die KI-Coding-Assistenten ganz unauffällig geschaffen haben. Code schreiben nicht mehr nur die Leute, die das Projekt kennen, denn alle mit Zugang und einem Assistenten können beitragen. Das bringt einen echten Geschwindigkeitsgewinn, aber auch ein echtes Risiko für die Konsistenz. Denn die Konventionen, die eine Codebasis gesund halten, stehen meist auf einer Wiki-Seite, die niemand öffnet, in den Köpfen von zwei Senior-Entwicklern und in wiederholten PR-Kommentaren.
Unser Projekt ist eine App, mit der Mitarbeitende im Schweizer Gesundheitswesen Schichten planen und ihre Arbeitszeit erfassen. Sie ist mit Angular, Ionic und Capacitor für Web, iOS und Android gebaut und Teil eines grösseren Java/Spring-Monorepos. Die App umfasst rund 275 Komponenten, und in den letzten sechs Monaten haben 13 Personen Commits beigesteuert: Mitarbeitende aus dem Frontend, aus dem Backend, die gelegentlich etwas im Frontend korrigieren, und aus anderen Teams. Das ist der Montagmorgen von oben, jede Woche.
Wir haben das mit zwei Funktionen von Claude Code gelöst: Hooks und Rules. Dieser Artikel zeigt, was sich in der Praxis verändert hat, warum die übliche Lösung, noch mehr Anweisungen zu schreiben, nicht trägt, und wie ein Ansatz mit Leitplanken dafür sorgt, dass Konventionen für alle gelten, ob man sie kennt oder nicht.
Das Problem: Anweisungen sind Vorschläge
Der erste Reflex ist immer derselbe: Wenn Claude eine Konvention nicht befolgt, schreibt man sie auf. Eine Zeile mehr in CLAUDE.md, der Datei, die Claude Code zu Beginn jeder Sitzung liest:
Immer mit Prettier formatieren, ESLint ausführen und die Typen prüfen.
Wenn das nicht funktioniert, wird die Anweisung wiederholt und dann in Grossbuchstaben geschrieben. Weiter unten in der Datei, nach 200 Zeilen anderer Anweisungen, findet man dann so etwas:
MERKE: NIEMALS X TUN. WIRKLICH, NIEMALS.
Grossbuchstaben machen eine Anweisung nicht verbindlicher, nur lauter. Das ist keine Kritik am Modell, sondern liegt daran, wie der Mechanismus angelegt ist. Die Dokumentation von Claude Code ist da eindeutig: Claude behandelt CLAUDE.md-Dateien „als Kontext, nicht als erzwungene Konfiguration“, und „um eine Aktion unabhängig davon zu blockieren, was Claude entscheidet, verwenden Sie stattdessen einen PreToolUse-Hook“ (Claude Code Dokumentation, Memory).
Eine Anweisung im Prompt konkurriert mit allem anderen im Kontextfenster. In einer langen Sitzung mit viel Code dazwischen verändert sich ihr Gewicht. Mal formatiert der Assistent die Datei, mal nicht, je nach Tag, Kontext und je nachdem, ob ihn jemand drei Nachrichten vorher daran erinnert hat. Das ist probabilistisches Verhalten, und für eine Team-Konvention wollen Sie deterministisches Verhalten.
Die Veränderung: ein Auslöser im Lebenszyklus des Agenten
Um zu verstehen, wo Hooks ansetzen, hilft ein Blick darauf, was passiert, wenn Sie Claude Code einen Prompt schicken. Das ist keine Magie, sondern eine Schleife: Sie schreiben etwas, der Agent entscheidet, ob er ein Tool braucht (eine Datei lesen, eine Datei bearbeiten, einen Befehl ausführen), nutzt es, prüft das Ergebnis und wiederholt das, bis er antworten kann.

Zwei Momente in dieser Schleife sind hier entscheidend: unmittelbar bevor ein Tool läuft und unmittelbar danach. Claude Code stellt beide als Events bereit, PreToolUse und PostToolUse (Claude Code Dokumentation, Hooks). Wer schon mit einem Frontend-Framework gearbeitet hat, kennt das Konzept. Es ist ein Lifecycle Hook wie useEffect in React, mounted in Vue oder ngOnInit in Angular, nur eben für den Lebenszyklus des Agenten statt für den einer Komponente.
Ein Hook ist ein Skript mit einem Auslöser. Sie registrieren ihn einmal in .claude/settings.json, die zusammen mit dem Projekt committet wird, und ab dann läuft er jedes Mal, wenn sein Event eintritt. Er ist kein Vorschlag, den das Modell gegen anderen Kontext abwägen kann, sondern Code, der ausgeführt wird. Der Unterschied zwischen den beiden Events ist wichtig: PreToolUse läuft vor der Aktion und kann sie deshalb blockieren. PostToolUse läuft nach der Aktion, kann sie also nicht rückgängig machen, aber das Ergebnis korrigieren oder darüber berichten.
Die Anwendung: drei Leitplanken
Wir haben jeden Fall nach demselben Muster in vier Schritten erzählt: das eigentliche Problem, der übliche Lösungsversuch, der Hook und das Ergebnis. Eines der Beispiele stammt aus unserem eigenen Projekt, die anderen beiden zeigen, wie sich dasselbe Muster auf Secrets und Geschäftsregeln übertragen lässt.
Beispiel 1: Automatisches Linting nach jeder Änderung
Das Problem. Unser Team hatte bereits eine Checkliste: formatieren, linten, Typen prüfen. Alle im Kernteam kannten sie gut. Das Problem war nie, die Schritte zu kennen, sondern dass nicht alle sie ausgeführt haben. Wenn jemand Neues ins Team kommt und niemand den Ablauf erklärt oder jemand aus einem anderen Team einen einzelnen Bug behebt, werden Prettier und ESLint übersprungen und niemand führt den Type Check aus. Das Ergebnis sind unübersichtliche PRs, in denen im Review niemand mehr echte Änderungen von Formatierungsänderungen unterscheiden kann.
Der übliche Versuch. Noch eine Zeile in CLAUDE.md, die leicht übersehen und schnell vergessen wird, sobald der Kontext lang wird.
Der Hook. Stattdessen haben wir einen PostToolUse-Hook registriert, der jedes Mal auslöst, wenn Claude eine Datei bearbeitet oder anlegt:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lint-check-changed-file.sh"
}
]
}
]
}
}
Die Konfiguration besteht aus drei Teilen und sonst nichts: dem Event (PostToolUse, nach dem Bearbeiten oder Anlegen), dem Matcher (Edit|Write, damit er nur bei diesen Tools auslöst) und dem Befehl, der auf ein Skript im Projekt verweist. Das Skript erhält den Pfad der bearbeiteten Datei als JSON über die Standardeingabe. Es führt Prettier und eslint --fix nur für diese Datei aus, startet dann tsc und filtert die Ausgabe auf Fehler in dieser Datei. Lässt sich etwas nicht automatisch beheben, geht der Bericht zurück an Claude, und Claude korrigiert es in derselben Sitzung.
Das Ergebnis. Dieselben drei Prüfungen laufen jetzt nach jeder Änderung, egal wer tippt: die neue Person im Team, externe Mitarbeitende, die den Code nur einmal anfassen, oder Sie selbst am Freitagnachmittag. Niemand muss an etwas denken, und genau darum geht es.
Beispiel 2: Zugriff auf Secrets blockieren
Das Problem. Gleiche Geschichte, andere Datei. Externe Mitarbeitende erhalten Zugriff für einen einzigen PR, oder jemand ist in der ersten Woche im Team, und Claude liest beim Erkunden des Projekts die .env-Datei. Nicht einmal absichtlich, sondern weil niemand gesagt hat, dass sie tabu ist.
Der übliche Versuch. Freundlich bitten: „Bitte die .env-Datei weder lesen noch bearbeiten.“ Aber eine Bitte ist keine Mauer. Sie ist eine offene Tür mit einem Zettel, auf dem „Bitte draussen bleiben“ steht.
Der Hook. Gleiche Struktur, anderes Event:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Read|Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-env.sh"
}
]
}
]
}
}
Diesmal ist das Event PreToolUse, das Skript läuft also vor der Aktion und kann sehr kurz sein:
#!/usr/bin/env bash
file_path="$(jq -r '.tool_input.file_path // empty')"
if [[ "$(basename "$file_path")" == .env* ]]; then
echo "Der Zugriff auf .env-Dateien ist durch die Projektrichtlinie gesperrt." >&2
exit 2
fi
exit 0
Das Ergebnis. Exit-Code 2 blockiert den Tool-Aufruf, das Lesen findet also nie statt, und die Meldung auf der Standardfehlerausgabe geht als Begründung an Claude zurück (Claude Code Dokumentation, Hooks). Claude erhält eine klare Erklärung und macht weiter. Für eine einfache Pfadsperre bietet Claude Code auch permissions.deny-Regeln in den Einstellungen. Ein Hook ist dann die bessere Wahl, wenn die Entscheidung Logik braucht, wie im nächsten Beispiel.
Beispiel 3: Die Mauer bei 100 $
Der Kontext. Hooks sind nicht auf den Code-Stil beschränkt. Dasselbe Muster gilt für Geschäftsregeln in jedem Agenten, der Tools aufruft. Stellen Sie sich einen Agenten vor, der Rückerstattungen für einen Onlineshop abwickelt. Die Geschäftsregel ist einfach: Bis 100 $ erledigt der Agent die Rückerstattung allein, darüber muss zuerst ein Mensch zustimmen.
Der übliche Versuch. Die Regel in den Prompt des Agenten schreiben, dann wiederholen, dann in Grossbuchstaben setzen. Es bleibt ein Prompt und keine Regel, und diesmal geht es um echtes Geld, nicht um ein px.
Der Hook. Ein PreToolUse-Hook auf dem Rückerstattungs-Tool. Wird das Tool über einen MCP-Server namens shop bereitgestellt, nennt Claude Code es mcp__shop__process_refund, und genau darauf zielt der Matcher:
{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__shop__process_refund",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-refund.sh"
}
]
}
]
}
}
Das Skript entscheidet, es schlägt nichts vor:
#!/usr/bin/env bash
input="$(cat)"
if jq -e '.tool_input.amount > 100' >/dev/null <<<"$input"; then
cat <<'EOF'
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Rückerstattungen über 100 $ erfordern eine Prüfung durch einen Menschen."
}
}
EOF
fi
exit 0
Das Ergebnis. Unterhalb des Schwellenwerts bleibt der Hook still, und die Rückerstattung läuft im normalen Ablauf weiter. Darüber wird der Aufruf abgelehnt, mit einer Begründung, die der Agent an die Kundschaft und an den Eskalationsprozess weitergeben kann. Bitten Sie den Agenten nicht höflich, im Budget zu bleiben, sondern ziehen Sie bei 100 $ eine Mauer hoch.
Eine praktische Faustregel: Wann Sie einen Hook brauchen
Wenn Sie zweimal „WICHTIG“ in CLAUDE.md geschrieben haben, ist das das Signal. Die Grossbuchstaben zeigen, dass Sie Determinismus wollen und keinen überzeugenderen Prompt. Was Sie brauchen, ist ein Hook, kein weiterer Absatz.
Rules: Konventionen, die bisher in jemandes Kopf lebten
Hooks setzen durch, aber vieles, was eine Codebasis konsistent macht, lässt sich nicht auf ein Skript reduzieren: Benennung, Komponentenarchitektur, API-Konventionen und Design Tokens. Dieses Wissen muss zum richtigen Zeitpunkt erklärt werden, und genau dafür gibt es Rules. Eine Rule ist eine Markdown-Datei in .claude/rules/. Mit einem paths-Feld im Frontmatter wird sie nur dann in den Kontext geladen, wenn Claude mit einer passenden Datei arbeitet (Claude Code Dokumentation, pfadspezifische Rules):
---
paths:
- 'src/**/*.scss'
---
Für width, height, font-size und andere Grössenangaben rem verwenden.
Ausnahmen: border und box-shadow bleiben in px.
Farb-Tokens aus dem Styleguide statt fest codierter Hex-Werte verwenden.
Anders als CLAUDE.md wird eine Rule nicht zu Beginn jeder Sitzung geladen. Sie erscheint, wenn die Datei, an der Sie arbeiten, zum Muster passt. Die SCSS-Konventionen tauchen also auf, wenn Claude ein Stylesheet öffnet, und nicht, wenn Claude gerade einen Unit Test schreibt.
Ein echtes Beispiel. Als ich ins Projekt kam, bekam mein erster PR einen Kommentar: „rem statt px verwenden.“ Ich habe es korrigiert, und bei meinem zweiten PR kam derselbe Kommentar. Die Konvention lebte nicht im Projekt, sondern im Kopf des Reviewers. Seit sie eine Rule ist, taucht der Kommentar nicht mehr auf. Nicht, weil ich sie gelernt hätte, sondern weil sie nicht mehr davon abhängt, dass ich daran denke. Ein triviales Beispiel, aber ein echtes.
Derselbe Mechanismus lässt sich auf jede Konvention übertragen. Inzwischen haben wir eigene Rules für SCSS, TypeScript und HTML Templates, die zum Teil aus wiederkehrenden PR-Kommentaren und Befunden der statischen Code-Analyse entstanden sind, und jede wird nur geladen, wenn sie relevant ist. Wer aus einem anderen Team kommt oder neu dabei ist, kennt diese Rules nicht, befolgt sie aber trotzdem, ohne Onboarding-Termin und ohne Wiki-Seite. Die Rule lebt im Repository, und das Repository vergisst nicht.
Eine ehrliche Einschränkung: Auch eine Rule ist Kontext und keine Durchsetzung. Sie macht das richtige Verhalten deutlich wahrscheinlicher, weil sie die Konvention zum richtigen Zeitpunkt vor das Modell bringt. Wenn „deutlich wahrscheinlicher“ nicht reicht, ist das ein Fall für einen Hook.
Zusammengefasst: Rules erklären, Hooks setzen durch
Die beiden Mechanismen lösen zwei Hälften desselben Problems. Rules machen aus einer Konvention Text, den Claude genau dann liest, wenn es darauf ankommt. Hooks machen aus einer Konvention Code, der in jedem Fall läuft. Keiner ersetzt den anderen. Eine nützliche Entscheidungshilfe: Ist ein Verstoss gegen die Konvention nur lästig, reicht meist eine Rule. Kostet er Geld, legt er Daten offen oder blockiert er ein Release, braucht es einen Hook.
Die eigentliche Verschiebung betrifft den Ort, an dem Konventionen leben. Früher lebten sie in Menschen: in Reviewern, in Senior-Entwicklern, in Onboarding-Terminen. Jetzt leben sie im Repository, versioniert und geprüft wie jeder andere Code. Denselben Schritt haben Teams vor Jahren mit CI-Pipelines und Lintern gemacht. Hier wird er auf eine neue Art von Mitwirkenden angewendet.
Was das für Teams bedeutet
Für Entwicklerinnen und Entwickler verändert sich der Arbeitsalltag in kleinen, aber spürbaren Punkten. Sie müssen dem Assistenten nicht mehr hinterherlaufen, damit er Typen korrigiert, den Linter ausführt und die Datei formatiert, und Reviews konzentrieren sich auf Logik statt auf Stil. Ausserdem schreiben Sie nicht mehr zum fünften Mal denselben PR-Kommentar.
Für Tech Leads und Architekturverantwortliche lautet die Frage nicht mehr „Wie stellen wir sicher, dass alle die Konventionen kennen?“, sondern „Welche Konventionen sind im Repository verankert?“. Die zweite Frage lässt sich viel leichter beantworten und prüfen. Leitplanken sind in .claude/ sichtbar, werden in PRs geprüft und gelten für alle Mitwirkenden gleich, intern wie extern.
Für Entscheidungsverantwortliche ist das die Voraussetzung dafür, eine Codebasis sicher für mehr Mitwirkende zu öffnen. KI-Assistenten senken die Hürde für Beiträge, was hilft, wenn Teams Code über Produkte hinweg teilen oder sich vorübergehend Unterstützung holen. Hooks und Rules sorgen dafür, dass diese niedrigere Hürde nicht auf Kosten von Qualität, Sicherheit oder Geschäftsregeln geht, denn die wichtigsten Regeln bleiben nicht dem Urteil des Modells überlassen.
Was sich in unserem Projekt verändert hat, ist weniger Rauschen. Rules und Hooks kamen am 26. August gemeinsam ins Repository. In den 66 Tagen davor gab es in 88 Frontend-PRs 12 Review-Kommentare zu Konventionen, etwa px statt rem, inject() statt des Konstruktors, Benennung und Ordnerstruktur. Das entspricht etwa einem Kommentar alle sieben PRs. In den 66 Tagen danach waren es drei bei 110 PRs, etwa einer alle 37 PRs. Kommentare von Review Bots sind nicht mitgezählt. Die Stichprobe ist klein, und im selben Zeitraum hat sich auch anderes verändert, darunter die Besetzung im Review und die Einführung eines automatisierten Review Bots. Es handelt sich also nicht um ein kontrolliertes Ergebnis. Es passt aber zu dem, was das Team beobachtet hat: weniger wiederholte PR-Kommentare, Konventionen, die nicht mehr erklärt werden müssen, und Fehler, die nie ins Review gelangen, weil sie gar nicht erst entstehen.
Der Einstieg: Aus Anweisungen werden Leitplanken
Am einfachsten beginnen Sie mit Ihrer eigenen CLAUDE.md. Jedes „NIEMALS“ und „IMMER“ darin ist ein Kandidat für einen Hook, denn die Grossbuchstaben zeigen, wo Sie eine Garantie wollen und keine Erinnerung. Ein einzelner PostToolUse-Hook, der die bearbeitete Datei formatiert und lintet, ist ein risikoarmer erster Schritt. PreToolUse ist das richtige Event für alles, was nicht passieren darf, etwa das Lesen von Secrets oder das Überschreiten eines geschäftlichen Schwellenwerts.
Für Konventionen, die sich nicht skripten lassen, schauen Sie sich Ihre PR-Kommentare an. Wenn Sie denselben Kommentar zweimal in einem Review geschrieben haben, schreiben Sie ihn stattdessen einmal als pfadbezogene Rule in .claude/rules/. Und committen Sie alles, denn Leitplanken wirken nur dann für alle Mitwirkenden, wenn sie im Repository leben.
Bitten Sie Ihren Assistenten nicht, sich zu erinnern. Sorgen Sie dafür, dass er sich daran hält.