Andrew Parra ES

Guides · Claude Code system

A CLAUDE.md that changes behavior

Write a short CLAUDE.md made of things Claude can't guess and can be checked (how to ship, the rules, the current state, your preferences), test it against no file at all, and move anything that must always happen into a hook.

Reading time
7 min read
Updated
Nov 19, 2026
Part of
the 66-guide pack

Every Claude Code session starts blank. CLAUDE.md is the note it reads first: what the project is, how to ship it, what never to do. I have one in every repo, and they've all grown the same shape.

The trouble is that a CLAUDE.md feels useful whether it is or not. You write twenty lines, the session goes fine, and you credit the file. The measured tests I've collected say most lines in most files change nothing. A few lines change a lot.

Sorting a CLAUDE.md line by line

1
How to shipnpm test, push, curl /healthz keep
2
Money is integer centsClaude can't guess it from the code keep
3
NEVER read .envmust hold every time move to a hook
4
Release checklist, 10 stepsused now and then move to a skill
5
Write clean codesame result with or without delete

Same task, three runs each (Example scores of 6 checks)

no CLAUDE.md        4  4  3
your short file     6  6  6
A line stays only if Claude gets something wrong without it; must-always rules go to hooks, occasional procedures to skills.

1. Start from what the tests found

Three results shape how I write these files now. All three are creators' own figures, read from their videos and not re-run by me.

Your own rules beat length. One creator gave Claude a small feature (a discount-code box) with four versions of CLAUDE.md, three runs each, and scored every run against six browser checks. No file scored 4, 4 and 3. The file /init generates, which describes the code and none of his rules, scored 4, 4 and 4. His 19-line file with seven house rules scored 6 of 6 every time. A 217-line template with the same seven rules buried in section 10 also scored 6 of 6. The difference was the rules Claude couldn't guess from the code: round the discount down to the cent, keep the code after a page refresh, don't add features nobody asked for. Without them, the same mistakes showed up in all six runs.

Most generic lines do nothing. Another creator tested the viral four-line CLAUDE.md over 42 runs. One line changed behavior every time: "Don't assume. Don't hide confusion. Surface tradeoffs." With it, 5 of 5 runs ended with a list of choices the user might want to change; without it, 0 of 5. "Minimum code" cut code size by about a fifth but also dropped money formatting from 2 of 3 runs to 0 of 3. Two lines changed nothing measurable. He calls it a pointer, not a measurement, at 2 to 5 runs per cell.

The file costs tokens every request. In a 27-run test on one large repo, a /init CLAUDE.md raised tokens per question with every answer already correct. A research paper on context files found the same pattern on coding benchmarks: no general gain in success, and higher cost.

So a line earns its place only if Claude would get something wrong without it.

2. Write the sections that carry facts Claude can't guess

These are the sections my files have settled on. Each one holds something the code doesn't say.

# my-app: working notes for Claude

Read this first. README.md has the architecture; this file is how to work
here and what state things are in.

## Where this fits
One of several projects. It reads the billing service only through its
public API. Never import that repo's code or keys.

## How to ship
1. Edit, then `npm test` (must pass) and `npm run build`.
2. Push `main`; the host deploys in about a minute.
3. Confirm with `curl -s https://<your-app>/healthz`, then report what changed.

## Rules (do not relax)
- Keys live only in the host's env vars. Never type, print or commit one.
- Money is integer cents. A missing cost is "incomplete", never zero.
- Ask before anything irreversible: deleting data, changing plans, spending.

## State as of 2026-11-19
- Waiting on me: set PAYMENTS_WEBHOOK_SECRET on the host.
- Blocked: export job fails on files over 50 MB (see issue #12).

## My preferences
- Bottom line first, short. I read on my phone.
- Ship, verify, then tell me what changed in a few lines.

Why each one is there:

  • Where this fits stops a session from "helpfully" sharing code or keys with a sibling project.
  • How to ship is the most checked section. Each step is a command, and "done" has a test attached. Anthropic's docs ask for lines that can be checked, like "Run npm test before committing", and this is where they live.
  • Rules (do not relax) is short and specific to the project. Shared rules come in through an import (see below). "Do not relax" is in the heading because sessions will propose loosening a rule to finish a task.
  • State as of a date tells the next session what's blocked and what's waiting on me. My Spread project splits it further, into "Blocked on Andrew (ask him, don't guess)" and "Next steps once it runs (in order)".
  • Preferences is about the reader, not the code. It's the reason my sessions end with three lines instead of three screens.

3. Pull shared rules in with an import

Rules that apply to every project don't belong in any one CLAUDE.md. Claude Code expands @path imports, and the docs confirm imports can nest up to four levels.

## Shared rules (read first)
@../parent-hub/RULES.md

Every one of my project files starts this way. The guide on a single rules file covers the drift check that keeps the copies honest.

4. Keep out what doesn't change behavior

The docs suggest keeping each file under about 200 lines. Here's what I take out to stay there:

  • Descriptions of the code. Claude can read the code. The /init file in the test above described the project well and still scored no better than no file.
  • Generic advice. "Write clean code" and "be careful" are the lines that tested as doing nothing.
  • Procedures you run sometimes. A ten-step release checklist goes in a skill, which loads only when it's needed. Anthropic's cost guide says the same.
  • Anything that must happen every time. CLAUDE.md is context. Claude reads it and decides. A must-never rule goes in a hook or a deny rule (see the hooks guide). If you catch yourself writing a line in capitals, it belongs there.
  • Secrets, IDs and private URLs. The file is committed, and every session prints parts of it.

5. Record who decided, and when

A rule with no reason invites a session to "fix" it. Where a rule is a decision, I tag it:

- Contact email stays the public one on the contact page (decided 2026-10-16).
- No analytics and no cookies. Adding any needs my OK, a consent prompt
  and a privacy-page update.

The date tells a future session the rule is deliberate. If you keep a log, it also says where to look for the reasoning. In my repos the full quote goes in the hub log and the rule stays one line.

6. Test it the way the creators did

You don't need 42 runs to learn something. Pick one small task that touches your rules and run it three times each way.

# fresh copy each run; only the project's settings load
for variant in none mine; do
  for run in 1 2 3; do
    rm -rf /tmp/try && cp -r . /tmp/try && cd /tmp/try
    [ "$variant" = none ] && rm -f CLAUDE.md
    claude -p "Add a discount code box to the cart page" --setting-sources project > "/tmp/out-$variant-$run.txt"
    npm test > "/tmp/test-$variant-$run.txt" 2>&1; echo "$variant $run exit=$?"
    cd - >/dev/null
  done
done

Score each run with a check you wrote before you looked at the output. If a rule scores the same with and without the file, delete the line or move it to a hook. If a line helps, keep it word for word. Rewording a line that works is how you lose it.

7. Keep it current with one habit

When Claude makes a mistake you've corrected before, end the correction with "update CLAUDE.md so this doesn't happen again", then read the diff. One creator guide recommends this, and it's how most of the useful lines in my files got there: rounding rules, a file that must keep its line endings, a folder never to touch.

Read the diff each time. Claude will happily write a generic line ("be careful with money"). Rewrite it as something checkable ("money is integer cents").

What to watch

  • The state section goes stale. My hub repo's CLAUDE.md still says "State as of" a date six weeks back. Everything after that date lives in the hub log. A stale state section is worse than none, because the session trusts it. Date it, and prune it when you log.
  • Change logs creep in. One of my busiest repos keeps a running record of every fix in its CLAUDE.md, one entry per change, and it's far past the 200-line guideline. The useful part for the next session is the rule each fix produced. The story behind it belongs in a log.
  • /clear drops chat rules. In one creator's 21-run test, two rules typed at the start of a chat were lost after /clear in 3 of 3 runs. In CLAUDE.md, they survived. If you keep repeating a rule in chat, it goes in the file.

Checklist

  • The file opens with "Read this first" and says what the README covers instead.
  • How to ship is numbered commands, ending with a check and a report.
  • Rules are project-specific, checkable and headed "do not relax"; shared rules come in by @import.
  • State carries a date and lists what's blocked and what's waiting on you.
  • No code descriptions, generic advice, occasional procedures or secrets; the file is under about 200 lines.
  • Every must-never rule also exists as a hook or deny rule.
  • You ran one task three times with and without the file, and cut the lines that changed nothing.

Want the rest?

This is one of 66 guides. The full pack is pay what you want, from a coffee up.