CLAUDE.md Examples: What I Cut and What Became a Hook

In my session transcripts up to 12 October 2026, about 300 agent commands carried my secret scan's override token, and 297 of them came after the scan had already blocked something earlier in the same session. In my logs, once an agent had seen the way past a gate, it kept using it.

That finding changed how I write rules. I cut mine from 10,667 words on 20 July 2026 to 3,382 on 14 October, moved the ones that mattered into hooks, and deleted 14 of the 36 hook scripts I'd written since April. Below are real CLAUDE.md examples from the file my Claude Code agents run on, what enforces each rule, and the data behind the override finding.

What should go in a CLAUDE.md file?#

On 23 August 2026 I audited every instruction in my CLAUDE.md, my rule files, memory, hooks and skills. Each line had to pass three tests:

1. Would the model do this anyway?
2. Is it correcting a weakness the model no longer has?
3. Does it conflict with something else?

By that audit's own count, 316 rules became 58. What stayed fits four kinds:

1. Overrides of a model default, where the default is wrong for me.
2. Facts the model can't read from the code, like where artifacts live.
3. Failures I've seen more than once.
4. Security gates that fail closed.

What went is the more useful list. About 1,100 words were archaeology: essays explaining rules that no longer existed. About 150 words were global commit and branch formats that every project file overrides, so they had never once applied. And about 450 words were rules the tooling already enforced: the list of secrets (a scan hook does that), destructive commands (a block hook does that), and "read a file before editing it" (Claude Code's Edit tool errors if you don't).

Once a hook enforces a rule, the rule's text only costs tokens.

An outside study points the same way. Evaluating AGENTS.md (arXiv, first posted 12 February 2026, revised 29 September 2026) found that context files generally didn't raise task success and added more than 20% to inference cost. The agents did follow the instructions. Long repo overviews just didn't help them.

The rules that survived, and what enforces each#

My rules today are a 939-word CLAUDE.md and eight files in ~/.claude/rules/, 3,382 words in all. Three of the eight have paths: frontmatter, so they load only when Claude touches matching files.

The gap between a rule and its hook can be long. "Never commit secrets" was in my rules from 17 April, and the scan hook arrived on 9 July. "Every outbound message goes through my voice check first" got its rule and its hook on the same day, 22 September. The hook's commit message says the rule had "zero enforcement" until then.

Here's what the first rule looks like in the file:

A gate whose job is to block bad input must also block when the check
itself cannot run. Empty or missing configuration means REFUSE.
 
- Subprocess gates check all three failure modes, not just a non-zero exit:
  if (result.error || result.status === null || result.status !== 0) { refuse }

The mistake I kept correcting in review was a gate that blocked only on the exit code that means "found something". A gate that can't even start has no exit code, so it passed. Claude Code 2.1.295 (8 October 2026) added onFailure: "block", which closes part of that gap for hooks. I tested where it stops working on my own gates. That's the 14 November post.

Reminders die, gates survive#

I keep ~/.claude in git, so every hook I've added or deleted has a date. Since the first commit on 17 April 2026 I've written 36 hook scripts. 22 are still running and 14 are deleted.

By my reading of each deleted script, 11 of the 14 could never block anything. They were banners, reminders, mode trackers, a "remember to write tests" nudge that warned and never stopped a commit, and a memory layer I removed when it was written to 4 times against the 10 I'd set as its bar. The other 3 were an auto-approver, a script that rewrote which model a subagent used, and one real deny gate, for a database tool I'd used a handful of times. That gate went out in the same commit as its tool. No other blocking gate was deleted.

My reading of that: a reminder competes with everything else in the context, and the model can weigh it and move on. A deny gate stops the tool call, so it keeps its job until the tool goes away.

The escape hatch that undid a gate#

Some of my gates have an override, because some blocks are false positives. The secret scan has a skip token for test fixtures with fake keys, and each time it denied a commit, its message ended by printing that token.

My hook logs only record the token from 23 September, and they show it on 205 commit or push attempts between then and 12 October. The session transcripts go back further and count every command that carried it, so I traced it there, across all four of my Claude Code config directories, up to 12 October:

1. About 300 commands carried the token (304 by my script). An earlier draft of this post said 372; I couldn't reproduce that number, so this one comes from a script I kept.
2. 297 of them came after the scan had already denied something earlier in the same session.
3. Of roughly 136 deny messages, 129 came from the check that flags variable assignments like password = .... Only 2 matched a real key shape, and my script couldn't classify the other 5.

The order is what matters: a block, usually on a variable name, then the override for the rest of the session. I read that as the agent learning the way past from the deny message itself. The transcripts show the sequence. They can't show the agent's reasoning.

My GitHub write gate shows the same pattern. It asks the agent to add a confirm token to any mutating gh api call, and agents added it 1,010 times on 40 days between 9 July and 14 October. I can't tell how many of those were justified, because the log doesn't record a reason for any of them.

The fix has two parts: cut the false positives, and stop printing the override in the deny message. As of 14 October the deny message still prints it, so that's the next change to my harness.

How to write your own CLAUDE.md#

1. Add a rule the second time you correct the same behaviour in review. Write the date and the reason next to it.
2. Write the check, not the method. "A gate refuses when its check can't run" can be verified. "Think carefully about edge cases" can't.
3. Next to each rule, write what enforces it. If the answer is "nothing", and breaking it costs a leaked key or a broken main, write the hook.
4. When a hook enforces a rule, delete the rule's text.
5. Don't print a gate's override where the agent can read it. If a block can be a false positive, fix the check.
6. Give a rule paths: frontmatter when it only matters for some files.

Then re-audit after every model release. My committed skills went from 54 on 20 July to 19 on 10 October. By my reading, most of what I cut described a method the newer model no longer needed. The usage side of this setup is in 463 Claude Code sessions, counted, and the review side is in the 30-PR case study.

If you want this layer in your own repos, with gates your team keeps after I leave, that's the Agent Fleet Setup on my services page.