CLAUDE.md Is a Wish List; Hooks Are the Checks
The rules you write into CLAUDE.md, the agent violates at step 40. Rules are requests; hooks are checks. Breaking down Claude Code’s hook mechanism: six events, three response modes, five types, and the Stop hook that makes “done” actually mean tests pass.
You write “never run rm -rf” into CLAUDE.md. Forty steps later, the agent runs it anyway. Claude Code is Anthropic’s command-line coding agent. CLAUDE.md is the project’s instruction file, which the model reads every session. So it did see that line. The problem is not that it didn’t read it. A line in the context is only a request, and requests get weighed against the model’s other available information and then overridden.
Valentin breaks this down clearly on X: rules are requests, hooks are checks. CLAUDE.md is good for documenting project structure, common commands, and team style. It cannot make an action fail. Hooks are bound to events in the Claude Code lifecycle and run every time an event fires. The model doesn’t need to remember them, agree with them, or even know they exist.
Hooks live in settings files. Project-level .claude/settings.json, global ~/.claude/settings.json. Each hook specifies an event, an optional tool matcher, and the command to run:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": ".claude/hooks/no-rm.sh" }
]
}
]
}
}
A hook receives the event JSON via stdin: tool name, tool input, session, working directory. It reads the input, makes a decision, and answers.
Remember these six events first:
- SessionStart: runs when a session starts, resumes, is cleared, or is compacted. Loads live context, such as open issues, current branch, and overnight changes.
- UserPromptSubmit: runs before Claude sees your message. Can add context to each prompt or reject it outright.
- PreToolUse: before a tool call, the one and only gate. Can allow, ask, or deny.
- PostToolUse: after a tool returns. The action has already happened; good for formatting, linting, and logging.
- Stop: runs when Claude is about to finish. Block it, and Claude keeps working.
- PreCompact: runs before context is trimmed. Write down the information that will still be needed after trimming.
PreToolUse and Stop do most of the work. PreToolUse guards the gate; Stop guards “done.”
Hooks have three ways to respond. exit 0 with no output means make no decision and continue the normal permission flow. exit 2 means block, and the content in stderr is returned to Claude as the reason. A complete rm guard:
#!/bin/bash
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")
if [[ "$command" == rm* ]]; then
echo "Blocked: rm is not allowed, move files to ./trash instead" >&2
exit 2
fi
exit 0
That stderr line matters more than it looks. If you just say “no,” the agent will try again a different way. Give it an alternative, and only then does it switch.
exit 0 with JSON is the precise version. Return a permission decision and reason on PreToolUse:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Use rg instead of grep"
}
}
deny cancels the call and tells Claude why. ask goes through the normal confirmation dialog. allow skips the dialog. Each hook picks one style.
Then there’s the Stop hook, the one few people write. Every agent will say “done.” It is rarely asked to prove it. The Stop hook runs at the moment Claude is about to hand back control. Return decision: "block" and a reason; Claude reads the reason and keeps working. Put the test suite in there, and “done” becomes something verifiable.
#!/bin/bash
input=$(cat)
[ "$(jq -r '.stop_hook_active' <<<"$input")" = "true" ] && exit 0
if ! out=$(npm test 2>&1); then
jq -n --arg r "$(tail -20 <<<"$out")" '{decision: "block", reason: $r}'
fi
There are two built-in brakes to prevent infinite loops. stop_hook_active being true means continuation has already started. Check it; otherwise a test that never passes will keep occupying the session. After eight consecutive continuations, Claude Code will also force it to stop. The reason field must be specific. Send the failing test and the last few lines of output, not just “tests failed.” The agent can only fix what it can see.
Five kinds of hooks; four do not involve the model. command runs a script—cheapest and fastest, with the same result every time. http sends the same JSON to a URL, so one server can enforce a consistent policy for the whole team. mcp_tool calls a tool in an already connected server. prompt sends the input to the model for a single judgment and returns JSON. agent spawns a subagent that can read files, search, and then decide. It is the slowest and is still marked experimental.
How to choose: if the rule does not need words like “judge,” “evaluate,” or “decide,” it is a command hook. “Cannot write outside src/” is a command. “Does this change match the ticket?” is a prompt. Turning every check into a model call means paying a judgment fee for a question that already has a single answer.
How to put it into practice: take the rule you repeat most in chat, write it as a PreToolUse command hook with exit 2 and an alternative in stderr. Add a Stop hook that runs the fastest checks: lint, type checking, tests for changed files. Add a PostToolUse formatter, and you never have to review whitespace again. Put prompt and agent hooks last, only for rules scripts cannot express clearly. Keep humans in the places hooks cannot reach: merge, deploy, migration.
A few typical reactions showed up in the comments. One user said the Stop hook is the one most worth copying first, making “done” equal tests passing. Someone asked whether, when tests are very flaky, the Stop hook will block forever or let it through. Someone else put it bluntly: hooks are hard control; don’t count on it to self-discipline. Others were clear-eyed: hooks can only cover rules a script can check, and requirements like “don’t sound like a robot” still stay in CLAUDE.md. Someone in the comments attached an image.
Valentin has three lines worth taking away:
A rule the model can skip is a suggestion.
A check that cannot fail is decoration.
Every correction you give twice should go into a hook.
发布时间: 2026-11-23 01:51