Often when you start putting an AI coding assistant to work, the configuration simply means writing instructions. You put them in a markdown file — `CLAUDE.md`, `agents.md`, or whatever the harness calls it and trust the model to follow them. This approach still has its place, but it has a structural weakness visible once the agent starts working at scale. That’s because instructions are probabilistic. The model reads them, but not always acts on them. In a large codebase with many conventions, some rules will quietly get missed.
One of the responses to this problem is to split configuration into two separate mechanisms, each for a different job.
Rules for judgment and Hooks for guarantees
A rule is guidance directly fed to the language model and it shapes how the model reasons. “Money is stored as integer cents, never floats” is a rule. Rules encode domain knowledge the model needs to produce correct code/response. Rules are the right tool for facts, conventions, and constraints that require understanding.
A hook (a small script that sits between two requests and enforces conditions before passing things along) is wired into the harness so it fires automatically on a specific event. Unlike rules hooks are deterministic: they run regardless of what the model decides. If a hook says “block this action,” the action is blocked, full stop.
The two mechanisms are complementary. Hooks extract process from rules, leaving rules to do what they are good at.
The audit question
A practical way to sort existing rules is to ask one question about each: does this rule name an event, or does it encode a judgment?
“After implementing, run the tests” names an event — there is a moment (implementation done) and an action (run tests). That belongs in a hook, not a rule. As a rule, it can be missed; as a stop hook — a script that fires when the agent hands control back to the user — it runs every time, without exception.
“Never read the `.env` file” also names an event: a pre-read gate. Wired as a pre-tool-use hook, it becomes a security guarantee rather than a suggestion. If the agent tries to read a secrets file, the action is blocked before any sensitive data enters the model’s context (not always like that, for instance hooks are executed as sub-processes in Claude Code, so the harness sees the full prompt). As a rule, it is advice. As a hook, it is a lock.
“Write clean code,” on the other hand, is neither judgment nor event — the model already has that as part of its training. It can be deleted.
There is research behind this intuition. When coding agents were given the ability to evolve their own rules, performance decreased. When they were given the ability to evolve their own hooks instead, performance improved across most task difficulties. Large rule files are a symptom, not a solution.
What hooks can enforce
The most common hook patterns are straightforward once the mechanism is clear.
Stop hooks run when the agent hands control back. A hook that runs the full test suite at that moment — and blocks completion if any test is red — solves the persistent problem of agents declaring “done” while tests are still failing. The hook’s output goes back to the model as context, so it can resume and fix rather than just stop.
Pre-tool-use hooks run before any tool call. This is where security gates live: blocking reads of secrets files, preventing destructive commands, requiring that certain context files have been read before a file is edited. A file-coupling check, for instance, can verify that related modules have been reviewed before a change goes in — preventing edits made without the full context needed to make them safely.
Session-start hooks fire when a new session begins. Injecting a memory or context file here means the agent always starts with the right foundation, regardless of how long the rules file has grown.
What Changes?
The practical shift is moving from “tell the model what to do and hope it complies” to “build a harness that enforces the non-negotiable aspects mechanically.” Rules remain valuable for knowledge and judgment. Hooks take care of the things that need to happen every time, without exception.
As coding agents take on longer autonomous runs, that distinction become more and more important. The longer an agent operates without a human checkpoint, the more a single missed instruction matters. Hooks do not solve every failure mode, but they close the gap between what the configuration says and what the system actually does — and that gap is where most reliability issues live.
Text summarized and optimized using Anthropic’s models and reviewed by a human.