Stop treating your CLAUDE.md like a legal contract. It isn't.
.cursor/rules or CLAUDE.md files and act surprised when the agent ignores them. That's a category error. Those files are just advisory context. As the session gets longer and the context window fills up, those instructions lose the "attention contest." The model isn't disobeying you; it's just lost in the noise.If you want actual enforcement, you need to stop using reminders and start using gates. A rule is a suggestion; a hook is a shell command that runs at a fixed point in the agent's lifecycle. It doesn't care about token weight because it lives outside the model's brain.
In the .claude/settings.json, you can configure lifecycle events. For us, PreToolUse is the big one. It fires before a tool call executes. If you want to block a specific action, you write a script that parses the JSON on stdin, checks the command, and if it violates a security invariant, it exits with code 2.
Here is the critical part: when a hook exits with code 2, your stderr becomes direct feedback to the model. It doesn't just error out; the agent actually reads why it was blocked. It’s the difference between a silent failure and a course-correction.
I've been testing a few small, high-value hooks to prevent our devs from breaking things:
1. The main-branch guard (PreToolUse on Bash)
This is my favorite for preventing accidents. It parses the incoming bash command. If it detects a git commit while the current branch is main or master, it kills the process and spits out: Blocked: direct commit to main. Create a branch first.
2. The secret scan (PreToolUse on Bash)
We use this to match git push or git commit commands. It runs a quick regex or a dedicated tool to ensure no high-entropy strings or API keys are being leaked into the history.
3. The test gate (PostToolUse)
Instead of just hoping the agent runs tests, you use this to check the exit code of any test suite run. If the tests fail, the hook can feed that failure back into the prompt immediately, forcing the model to fix the code before it even thinks about moving to the next task.
One warning from a data perspective: hooks run with your user permissions. They are powerful, which means they can be dangerous if you're installing third-party configs blindly. Always audit the script before you let it run in your environment.
If a violation of a rule would force you to rotate a credential or revert a production commit, don't write it in a markdown file. Build a hook.