# Hook over prose

> CLAUDE.md is advisory text the model re-weighs every turn; a PreToolUse hook that exits 2 is enforced code. A rule you can check shouldn't be a sentence.

URL: https://bartlomiejkrupa.dev/notes/hook-over-prose/
Category: rule | Updated: 2026-10-07
Summary: CLAUDE.md is advisory text the model re-weighs every turn; a PreToolUse hook that exits 2 is enforced code. A rule you can check shouldn't be a sentence.

`CLAUDE.md` is delivered as a system reminder - context, not enforced configuration, in Anthropic's own words. Adherence is probabilistic and decays as the session grows. A `PreToolUse` hook that exits `2` is the opposite: the harness runs it as code and blocks the action regardless of model state or context drift.

## Rule

1. State the constraint as a check (path deny, command matcher, exit code) when you can.
2. Put that check in a hook - not in always-loaded prose.
3. Leave in [CLAUDE.md](/notes/claude-md-universal-only) only what genuinely needs prose: non-guessable commands, architecture decisions, quirks a newcomer cannot infer.
4. Keep the file short enough to survive the relevance filter (Anthropic's docs target under 200 lines; this site's own file stays under 60).

Hooks cost nothing in the context window - they never load as instructions. Take one rule, put it in `CLAUDE.md`, and run the same task repeatedly: it gets violated more often the longer the session runs. Move the identical rule into a `PreToolUse` hook that exits `2` and the violations stop permanently - not because the model improved, but because the model is no longer the thing being asked.

Match on evidence, not on the words describing it: a guard keyed to a command name also fires on a transcript where the user wrote "do NOT run" that command. Which rules deserve a hook at all is a reversibility question - see [two-way door](/notes/two-way-door).

Playbook: [Why agents ignore your CLAUDE.md](/articles/why-agents-ignore-your-claude-md). Starter harness that ships this pattern: [How to set up a minimal Claude Code harness](/articles/claude-code-harness-starter).

Sources:
- How Claude remembers your project: https://code.claude.com/docs/en/memory
- Hooks reference: https://code.claude.com/docs/en/hooks
- Best practices for Claude Code: https://code.claude.com/docs/en/best-practices
- Writing a good CLAUDE.md: https://www.humanlayer.dev/blog/writing-a-good-claude-md