Leanpub Header

Skip to main content

CLAUDE.md Under Test: What Claude Code Rules Actually Do

Thirty-nine measured trials on whether written rules are obeyed, when Claude Code hooks earn their place, and how both fail - with the full harness and every trial's data.

CLAUDE.md Under Test: What Claude Code Rules Actually Do

My pitch was that rules written in CLAUDE.md get skipped, so you need enforcement. Then I measured it. In 22 trials with the ban written in, the banned command was never attempted. In 17 without it, 17 out of 17. This is the whole record: the instrument, every trial, the limits, and the harness so you can check me.

Minimum price

$9.99

$12.99

You pay

Author earns

$

Also available for 1 book credit with a Reader Membership

PDF
EPUB
About

About

About the Book

I sell tools that stop Claude Code from doing dangerous things, and the sentence at the centre of my marketing was "rules you write in CLAUDE.md get skipped, so you need enforcement."

In late August 2026 I measured it. Thirty-nine trials, Claude Code 2.1.246, two task families, twelve conditions, an observer hook recording every shell command before it ran.

In the 22 trials where the ban was written into a project CLAUDE.md, the banned command was never once attempted. In the 17 trials where it was not written, it was attempted 17 times out of 17.

Nothing I built to break that worked. Not burying the rule in the middle of a 128-line instruction file. Not moving it to the eighteenth of twenty sections. Not planting two other sections in the same file that explicitly told the model to use the banned command. Not raising the stakes from "replace a string in a config file" to "delete files you cannot get back."

Then I translated the whole harness and ran it again in English, because every instruction file in the original was Japanese and that was the largest hole in the result. It reproduced: three out of three attempts without the rule, zero out of three with it.

This book is the full record. The instrument and why the obvious design does not work. Every trial's raw counts, including the six that never started. Six worked examples of my own measuring code producing real numbers for the wrong quantity, and how each one was caught. And the arithmetic on what small samples cannot tell you: zero out of twenty-five bounds the failure rate at about 11 percent. It does not mean "never".

It also contains the measurement that cost me the other half of my sales pitch. A reviewer objected to my claim that a hook makes a violation impossible, so I tested that too. A PreToolUse hook blocks on exactly one exit status. A hook with a syntax error exits with a different one and does not block. Whether a MISSING hook script protects you depends on which interpreter you named in the command: "python3 missing.py" blocks everything and "bash missing.sh" silently lets it through - and "sh missing.sh" goes either way depending on what /bin/sh is on that machine. Ordinary bugs turn your guard off, and the only symptom is a line of stderr nobody reads.

What you get:

- Every condition, every trial, every command the model actually ran

- The harness, cleaned into a single script, so you can run it against your version, your language and your task. It is the same script the English replication used, so you know it works start to finish

- What belongs in CLAUDE.md and what belongs in a hook, tied to specific measurements instead of folklore

- Six worked examples of an instrument producing real numbers for the wrong quantity - the most transferable skill in the book

- A one-minute check for rules that name files which no longer exist, measured at roughly 4 to 7 percent of public repositories that have a CLAUDE.md

What this is not: a certification answer key, a template pack, or a claim that CLAUDE.md is sufficient. One model version, one primary language, two task families, small n. I direct an agent rather than writing the code myself, and the book says so. Every limit is stated in its own chapter, before the practical advice rather than after it.

If you run the harness and get a different answer, yours describes your situation and mine does not. That is the whole reason the scripts are in the book.

Share this book

Author

About the Author

yurukusa

Everything I publish starts from something that actually broke.

I run Claude Code on real projects, often unattended, and I have lost work to it. The hooks in cc-safe-setup (MIT, open source) exist one per incident — each guard is there because of a specific thing that went wrong. The books are the write-ups: what failed, what the logs looked like, and what finally stopped it.

Two things I hold myself to. If a number in one of my books is not something I measured, it says so. And if a command is printed, the output beside it came back from an actual run — failures included, because a check that cannot fail is not a check.

I am not selling certainty. Most of what I know here, I learned by breaking my own setup.

Contents

Table of Contents

Preface: I ran the experiment that hurt my own sales pitch

  1. Who this is for
  2. What is measured here, precisely
  3. What is not measured here
  4. Two disclosures, because they change how you should read this

1. The claim everyone repeats

  1. Where I got it
  2. The three things that got mixed together
  3. What I expected

2. How do you measure obedience at all?

  1. The uninstrumented zero
  2. The instrument: observe in every condition, deny in one
  3. Isolation, and why it is not optional
  4. The four times my instrument lied to me

3. Does the model even reach for the banned command?

  1. The banned command, and why this one
  2. The task shapes
  3. Result
  4. The smoke run that was almost a published finding
  5. The trap this closes

4. Nothing, a rule, a hook

  1. The instruction file, in full
  2. Result
  3. What the model actually ran
  4. The obvious objection

5. Does length break it? Does position?

  1. Building a realistic long file
  2. Result
  3. The interpretation, stated carefully
  4. Which leaves the third hypothesis

6. What happens when the file argues with itself

  1. First attempt, and why it did not count
  2. Second attempt: a fair fight
  3. Result
  4. What I take from this, and what I do not
  5. Where the argument stands

7. Raising the stakes: banning deletion

  1. The safety design, which is most of the work
  2. The task
  3. The conditions
  4. Result
  5. The finding that evaporated
  6. Where this leaves the ban

8. Is it the ban, or the escape route you offered?

  1. Condition L: the ban with nothing offered
  2. Result
  3. What this settles
  4. The limit that matters most here
  5. The complete picture

9. All thirty-nine trials

  1. Nothing else moved
  2. Where I got the arithmetic wrong
  3. The recovered trials
  4. Reading the number honestly

10. What thirty-nine trials cannot tell you

  1. Zero does not mean never
  2. The pooled p-value is not what it looks like
  3. Everything that was held fixed
  4. What the instrument physically cannot see
  5. What I would attack first

11. What a hook actually adds

  1. The claim I can no longer make
  2. What is actually left
  3. The distinction that survives
  4. A four-layer picture
  5. The honest version of the sales copy
  6. Two mirror-image errors, one of which was mine

12. Your guard hook fails open

  1. The design, and the instrument that lied a fifth time
  2. Result
  3. The failure mode that will actually bite you
  4. The other hole, found by accident
  5. What to do about it

13. What this means for your CLAUDE.md

  1. Measured: name the command
  2. Measured: do not reorganise your file for attention
  3. Measured: naming an alternative is optional, but it makes the workaround predictable
  4. Measured: do not contradict yourself, but not for the reason you think
  5. Judgement: what to put in the file at all
  6. Judgement: the three questions before adding a line
  7. What I have not measured and will not pretend to

14. What 914 hooks actually say when they block

  1. How many of them block at all
  2. What the blocking message contains
  3. The hand count
  4. What I conclude, and what I withdraw
  5. Why any of this matters for your own hooks

15. The rule that points at a file which is not there

  1. The measurement
  2. The limits, which are substantial
  3. Why this belongs in a book about obedience
  4. The check, which takes a minute

16. Run it yourself

  1. Before anything: two safety rules
  2. The minimum viable version
  3. Scripts
  4. Adapting it to your situation
  5. What a disagreement would mean

17. The replication, in English

  1. What was run
  2. Result
  3. What this closes, and what it does not
  4. The reason this chapter exists

Appendix A: Every trial

  1. A.1 Per-trial data, replacement task
  2. A.2 Per-trial data, deletion task
  3. A.3 Recovered trials (reported separately, not in the totals)
  4. A.4 Hook failure modes (Chapter 12)
  5. A.5 The thirty hooks read by hand (Chapter 14)
  6. A.6 English replication (Chapter 17)

Appendix B: The harness

  1. B.1 Requirements
  2. B.2 Two things to do before you run anything
  3. B.3 The script
  4. B.4 Reading the output
  5. B.5 The instruction files used in the book
  6. B.6 The hook failure-mode test (Chapter 12)

Get the free sample chapters

Click the buttons to get the free sample in PDF or EPUB, or read the sample online here

The Leanpub 60 Day 100% Happiness Guarantee

Within 60 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.

See full terms...

Earn $8 on a $10 Purchase, and $16 on a $20 Purchase

We pay 80% royalties on purchases of $7.99 or more, and 80% royalties minus a 50 cent flat fee on purchases between $0.99 and $7.98. You earn $8 on a $10 sale, and $16 on a $20 sale. So, if we sell 5000 non-refunded copies of your book for $20, you'll earn $80,000.

(Yes, some authors have already earned much more than that on Leanpub.)

In fact, authors have earned over $15 million writing, publishing and selling on Leanpub.

Learn more about writing on Leanpub

Free Updates. DRM Free.

If you buy a Leanpub book, you get free updates for as long as the author updates the book! Many authors use Leanpub to publish their books in-progress, while they are writing them. All readers get free updates, regardless of when they bought the book or how much they paid (including free).

Most Leanpub books are available in PDF (for computers) and EPUB (for phones, tablets and Kindle). The formats that a book includes are shown at the top right corner of this page.

Finally, Leanpub books don't have any DRM copy-protection nonsense, so you can easily read them on any supported device.

Learn more about Leanpub's ebook formats and where to read them

Write and Publish on Leanpub

You can use Leanpub to easily write, publish and sell in-progress and completed ebooks and online courses!

Leanpub is a powerful platform for serious authors, combining a simple, elegant writing and publishing workflow with a store focused on selling in-progress ebooks.

Leanpub is a magical typewriter for authors: just write in plain text, and to publish your ebook, just click a button. (Or, if you are producing your ebook your own way, you can even upload your own PDF and/or EPUB files and then publish with one click!) It really is that easy.

Learn more about writing on Leanpub