Your agent's instructions file is a suggestion. A hook is a contract.
Every coding agent now reads an instructions file. CLAUDE.md , AGENTS.md , .cursorrules , whatever yours is called. Mine is long. It has been long for months, because every time something went wrong I did the obvious thing and wrote a sentence about it. Here is what I eventually noticed. The agent follows those sentences most of the time. Not always. And the times it doesn't are not random:…
When you write an instructions file for a coding agent, it's merely a suggestion. A hook, on the other hand, is a contract that the agent must follow. The author found that their long instructions file often went unheeded. The agent only follows those rules when the context is simple, the task is uninteresting, and the rule is salient. However, it's precisely during the moments when the file is lengthy, the task is intriguing, and the rule is the least noticeable in a 30k-token context that the agent needs the rule most.
By moving the critical rules into PreToolUse hooks, the agent becomes less bothersome to supervise. The mechanics of a PreToolUse hook are straightforward: it's a program that gets called by a tool with its JSON input. The hook decides whether to proceed with the tool or block its execution. The key difference between a hook and an instructions file is that the call never happens in the case of a hook.
The model is discouraged from the action, and instead, the hook returns a refusal. The reason is then communicated back to the model, which enables it to self-correct, avoiding a costly round trip through the agent's attention.
The hook is effective, and its reasoning is communicated clearly. For instance, a hook that blocks mass deletes from the production database prevents any accidental data loss. Another hook that blocks local type-checking saves valuable CPU resources. A hook that blocks multi-line comments prevents the quiet shifting of timestamps and the silent ramping of feature flags. These rules, which are grouped based on what they protect, ensure that the agent doesn't violate certain critical guidelines.
These hooks, while effective, come with a price. False positives occur, and they're the cost of implementing such strict rules. The author has to edit the hooks to accommodate rare exceptions, but this is still cheaper than the alternative – an agent that blindly carries out its tasks without oversight. Hooks are crucial for the few rules where 'usually' isn't sufficient. The author initially implemented hooks due to their lack of trust in the model, but this perspective has since changed.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
