CLAUDE.md vraagt, een hook regelt
Het verschil zit in wie beslist. Een regel in CLAUDE.md komt in de context; het model leest hem en weegt hem mee. Meestal gaat dat goed. Maar in een lange sessie, na het samenvatten van de context of bij een lastige taak kan “nooit de map migrations aanpassen” het verliezen. De documentatie over het geheugen van Claude Code zegt het zelf: instructies zijn context, geen afdwinging, en om iets te blokkeren gebruik je een PreToolUse-hook.
Een hook is code die draait. Hij krijgt bij elk moment een stuk JSON binnen, bijvoorbeeld welke tool Claude wil gebruiken en met welke invoer, en beslist dan zelf.
| Zet het in CLAUDE.md als… | Maak er een hook van als… |
|---|---|
| Het om stijl of aanpak gaat | Het altijd moet gebeuren, zonder uitzondering |
| Een uitzondering soms prima is | Een fout schade doet: data, geheimen, productie |
| Claude het in de context moet afwegen | Je het met een script kunt controleren |
| Voorbeeld: “schrijf tests met pytest” | Voorbeeld: “nooit git push --force” |
| Voorbeeld: “gebruik onze API-conventies” | Voorbeeld: “na elke wijziging de formatter draaien” |
De belangrijkste momenten
- SessionStart: een sessie begint of wordt hervat. Extra context laden.
- UserPromptSubmit: je verstuurt een prompt. Context toevoegen of een verzoek tegenhouden.
- PreToolUse: voordat een tool draait. De enige plek om een actie vooraf te blokkeren.
- PostToolUse: nadat een tool slaagde. Formatter of linter op gewijzigde bestanden.
- Stop: Claude wil zijn beurt afronden. Met exitcode 2 laat je hem doorwerken.
- PreCompact en PostCompact: rond het samenvatten van de context.
- InstructionsLoaded: een CLAUDE.md of rules-bestand wordt geladen. Zo zie je welke instructies meedoen.
Er zijn er meer, zoals Notification, PermissionRequest, SubagentStart en SessionEnd.
Zo stel je er een in
- Kies het bestand.
.claude/settings.jsonin de repo voor het team,~/.claude/settings.jsonvoor jezelf,.claude/settings.local.jsonvoor lokale uitzonderingen. - Schrijf het script. Het leest JSON van stdin, met onder meer
tool_nameentool_input. - Koppel het aan een moment en een matcher. Onder
hookszet je het moment, bijvoorbeeldPreToolUse, eenmatcherzoalsBashofEdit|Write, en de handler met"type": "command"en het pad naar je script. - Laat de exitcode beslissen. 0 is goed. 2 is een blokkerende fout: de tool-aanroep gaat niet door en wat je script naar stderr schrijft gaat terug naar Claude, zodat het een andere weg zoekt. Andere codes zijn fouten die standaard niet blokkeren; zet bij een kritieke hook
onFailureop"block", dan blokkeert hij ook bij een fout of time-out. Wil je fijner sturen, eindig dan met 0 en geef JSON terug methookSpecificOutput.permissionDecisionopallow,denyofask(deferwerkt alleen in niet-interactieve-p-sessies). - Controleer met
/hooksen probeer de actie die je wilde tegenhouden.
Twee valkuilen uit de handleiding voor hooks. Een hook die bestanden beschermt, zoals een PreToolUse-hook op .env, houdt de bewerkingen van Claude tegen, maar Claude kan die bestanden nog steeds met shell-commando’s veranderen. Een Edit-deny-regel onder permissions.deny, bijvoorbeeld Edit(/.env), vangt een deel daarvan af; wie shell-commando’s echt wil inperken, zet volgens Anthropic sandboxing aan. En een Stop-hook die Claude laat doorwerken wordt overschreven na acht blokkades achter elkaar zonder tool-aanroep ertussen: lees stop_hook_active uit de JSON en stop vroeg als die true is.
Het misverstand: hooks vervangen CLAUDE.md
Ze vullen elkaar aan. Een hook weet niets over hoe jullie code eruitziet of waarom een keuze gemaakt is; hij kent alleen de gebeurtenis en wat zijn script kan opzoeken. Wie alles in hooks gaat vangen, krijgt een agent die vaak tegen een muur loopt zonder te weten waarom. Zet de reden in CLAUDE.md en het slot in een hook.
Wat dit betekent voor een team
Een hook in een gecommitte .claude/settings.json geeft elke ontwikkelaar dezelfde configuratie, en omdat het code is en geen tekst die geïnterpreteerd wordt, is het de plek voor de harde regels van het team. Of hij echt draait, hangt nog af van ieders instellingen, het script en de shell, en een projecthook kan iemand uitzetten. Wat niemand mag omzeilen, zet IT in managed settings. Maar hooks horen bij Claude Code: dezelfde ontwikkelaar in Cursor of ChatGPT valt er niet onder. En een hook kent alleen wat iemand in het script zette, niet wat het team vorige week in een mail besloot. Zie ook hoe het geheugen van Claude Code werkt en hoe je context deelt met je team.
Waar Bombos past
Hooks dwingen regels af die al zijn opgeschreven. Bombos is een plugin die Claude Code en de andere AI-tools van het team een gedeeld geheugen geeft waar die regels vandaan komen: wat het team geleerd heeft, wat in mail en documenten besloten is, en regels die de agent klaarzet voor de volgende vraag, terug te volgen naar hun bron. Eén ontwikkelaar kan het eerst zelf proberen op zijn eigen agents.
Vragen die hierbij horen
Waar zet ik een hook zodat het hele team hem heeft?
In .claude/settings.json in de repo, en die commit je. Een hook in ~/.claude/settings.json geldt alleen voor jou.
Hoe zie ik welke hooks actief zijn?
Typ /hooks in Claude Code. Je ziet de hooks uit alle bronnen, ook uit plugins en beheerd beleid.
Kan een hook iets anders zijn dan een shellcommando?
Ja. De soorten handlers zijn command, http, prompt, agent (experimenteel) en mcp_tool.
Wat doet exitcode 2 bij een Stop-hook?
Claude stopt dan niet en gaat verder met het gesprek. Handig om door te laten werken tot bijvoorbeeld de tests slagen.
