I gave Claude Code a 7-line rules file. It followed every rule, including the one I wrote badly.
Twelve runs, one task, and a checker that counted. Most rules in a CLAUDE.md file turned out not to be needed, because Claude copied the code around it. The ones that mattered were the ones it couldn't guess, and one of mine was ambiguous.
6 of 8 rules followed with no file at all
Level: Beginner. About 20 minutes. Needs Node 20+ and a Claude Code login.
Everyone tells you to write a CLAUDE.md file for Claude Code. A file of standing rules that it reads at the start of every session. The advice is everywhere and it sounds obviously right.
I wanted to know what it actually changes. Not what it feels like it changes. So I ran the same task twelve times, counted, and found out that most of what I put in the file wasn't doing anything.
The test
I made a tiny pricing module with two existing functions (addTax and formatPrice) and a couple of tests. Then I gave Claude Code the same job every time:
Add applyDiscount(priceCents, percent) to src/pricing.js. It returns the discounted price. Reject bad input. Add tests.
To judge the result, I wrote a small script that checks the code against each rule, so I wasn't deciding by eye. I tested the script first on a hand-written correct answer, and it passed everything.
I ran it with no rules file, and with a rules file. Here's the file:
Some of these rules describe things Claude could work out by looking at the code around it: money in cents, percentages as whole numbers, a doc comment on every function, tests in test/. Others it couldn't know: the error message prefix, and a store policy for rounding. I wanted to see which kind of rule needed the file.
What happened
I ran each setup four times. Here's the scoreboard:
Read the first column first. With no rules file at all, Claude Code got six of the eight rules right, every time. It kept money in cents, used whole-number percentages, wrote a doc comment, put tests in test/ with the built-in test runner, added no dependencies, and left no console.log. It didn't need to be told. It read the neighbouring code and copied it.
The two it missed, in all four runs, were the two it couldn't possibly guess: the error message prefix ERR_INVALID_INPUT: and the rounding policy.
With the rules file, the error prefix went from 0 of 4 to 4 of 4. That's the file working exactly as advertised.
The rule I wrote badly
Now look at the rounding row. With my first version of the file, Claude still got rounding wrong in all four runs. That puzzled me for a minute, because the rule was right there in the file.
My wording was: "Discounts round UP to the next whole cent." Here's what Claude wrote, and what I meant:
It rounded the discount up, which makes the price go down. I meant the price should round up. Both readings fit my sentence. Claude picked one, followed it carefully in every run, and my checker counted it as a miss.
So I rewrote the rule: "The discounted PRICE is rounded UP to the next whole cent (we never undercharge). Example: 999 cents with 15% off is 849.15, which becomes 850." Then it got it right four times out of four.
Two things in that rewrite did the work: the capitals on PRICE, and the worked example with real numbers. A single number in a rule is worth a paragraph of description.
Two mistakes in my own test
I'd rather you hear these from me.
First, my checker only knew my interpretation of the rounding rule. That's why the ambiguous wording showed up as a failure, and it's how I found the problem. A checker is only as clear as the rule it checks.
Second, when I re-ran the fixed version, I accidentally started the new runs from the code of an earlier run, so Claude found a finished function waiting for it and two of the four runs said "nothing to add." I noticed, threw those four runs away, reset the code to a clean start, and ran them again. The numbers above are from the clean runs.
What it costs
The rules file isn't free. Claude Code reported an average of about 34 seconds, 6.8 turns and 31 cents without it, against about 50 seconds, 10 turns and 41 cents with the fixed version. I didn't dig into why the runs got longer, so I can't tell you whether the extra turns were useful. I'm on a Pro plan, so I wasn't billed per run.
What I'd put in a CLAUDE.md
- Only rules Claude can't see in your code. Error formats, business policies, the thing your team argued about for a week. Anything it can copy from the code around it, it already does.
- Add a worked example to any rule with numbers or edge cases. It removes the ambiguity.
- Read your own rules as if you were a stranger. Could this sentence mean two things? Mine did.
- Keep it short. Anthropic's startup guide says the root file is read at the start of every session and should hold standing rules, with on-demand procedures better placed in skills. It doesn't give a length. Mine was seven lines and worked.
- Don't use it for anything dangerous. A rule in a text file is a request. If something must never happen, enforce it with a hook, which I cover in a separate guide.
What this test can't tell you
- One task, in a tiny project, with twelve runs. Your real codebase has a lot more going on.
- Because my project already showed Claude the style to follow, a rules file looked less useful than it would in a messy codebase. If your code is inconsistent, the file probably matters more.
- It's one model on one day. I didn't test how long a file can get before rules start getting ignored.
Sources
- https://claude.com/resources/articles/claude-code-guide-for-startups
Editorial note: We ran the steps in this guide ourselves and the screenshots come from those runs. Your results may differ with your plan, model or settings, so check anything important. Cover illustrations are AI-generated. Discovia is independent and not affiliated with Anthropic.
New guides and tools
Hands-on Claude guides, straight to your inbox
Step-by-step walkthroughs of what's new in Claude and Anthropic's tools, with real screenshots and honest results, including what didn't work. No hype, no jargon, no noise.
By subscribing, you agree to receive newsletter and marketing emails, and accept our Terms of Use and Privacy Policy. You can unsubscribe anytime.
Claude Code Lab
Tests of Claude Code features: hooks, skills, rules files and workflows, with the numbers.
More Claude Code guides →

