My CLAUDE.md, and the failure behind each rule

Every line in my CLAUDE.md is there because something went wrong. Here are the rules, what broke, and what an instruction file costs you on every step.

My global CLAUDE.md is 80 lines and about 1,100 words. Every Claude Code session on my machine reads it before it reads my request, together with a short card of rules for the kind of task it is doing. Most of those rules carry a date, because each one was written the day something went wrong.

This post goes through the rules that earned their place, the failure behind each one, and one thing people rarely say about instruction files: they are not free.

An instruction file costs you on every step

Claude Code sends the whole conversation again on every step: the system prompt, the tool list, your CLAUDE.md, everything said so far. A long CLAUDE.md is paid for again and again, not once.

I measured what a fresh session on my machine had loaded before it read the first word of the task. It was 71,000 to 76,000 tokens, 38 % of the 200,000-token window. Most of it was not my CLAUDE.md at all. It was tool definitions (about 26,000 tokens), the list of skills (about 11,000) and the list of agent types (about 11,000). One tool the sessions never used was 12,000 tokens on its own.

So now a session starts with only what its task needs. A writing task does not load the design tools. A small task gets a short card of rules instead of the long memory file. The rule for the file itself is simple: if a line has not prevented a mistake, it goes.

The rules, and what broke

Run only the tests you changed

Per task: run ONLY the test files you added or changed, on this PC. No full suite.

At first every session ran the whole suite after every small change. At the worst point my two small test clusters took about 240 runs a day and everything queued. Now a session runs the tests it touched, and one full check runs per batch of finished work.

Writing the rule did not end it. In one 30-hour stretch, sessions skipped the guard that enforces it 361 times. About 200 of those quoted their own task description, which told them to re-run "the tests this task changes". The sessions were following an order. The orders were wrong, so the fix belonged in the task template, not in the sessions.

A check must list every failure at once

A check that stops at its first red step hides the rest. Use the non-stop form so ONE run lists every failure.

One fix took seven check runs in a row: each run stopped at the first failure, the session fixed it, and the next run showed the next one. Now checks run to the end and the session fixes everything in the log before it runs again.

Read a file once

Read each file once. Find the lines with grep -n, then read only that range. Never cat a file over about 150 lines.

Because every step re-sends the conversation, a 2,000-line file read twice is paid for on every step after that. Early on I burned through two 5-hour usage limits in one day. Reading only the lines you need is the cheapest change I made.

Quote IDs only from command output

Quote a commit or run id only from command output, never from memory.

A model will write a plausible commit hash from memory. It looks right and it points at nothing, or at something else. So a session runs the command, then quotes what it printed.

This is also the rule I tried hardest to turn into code, and failed. A hook that flagged every hash not seen in the session's own output fired 307 times in a week. In a sample of 19, none were real mistakes: they were hashes from a merge command's output, from another session's report, or local branches. It stays a sentence in CLAUDE.md, not a block.

cut does not do what you think on a line without =

Never cut, cat, head or grep a credentials file.

A session wanted only the names from a credentials file and ran cut -d= -f1. One line was user:password, with no =. When cut cannot find the delimiter it prints the whole line, so the password went into the session log. Now sessions read names through a tool that never prints values, and a hook refuses the obvious forms.

Name the document before you draw

Design work names the document it draws in, and checks it before the first draw.

Three times the first drawing of a new screen landed in the wrong design file, or in the right file with the wrong colours. Each task now names its file, and the session opens it and checks the palette before it draws anything.

Record finished work where the next session looks

When your work finishes a planned part, mark it done in the plan.

One check found 32 planned parts that were already built but still marked open, and 4 of 12 new sessions had started work that was already finished. A session cannot know what another one did unless it is written where it looks first.

One handoff, complete, replaces the rest

A handoff replaces all earlier ones. A successor reads only the newest.

When a session gets near the end of its context, it writes what it did, what it learned with file and line, and what comes next. The next session reads that one file and nothing else. It does not open the earlier handoffs or re-check facts the last one already states, so a handoff has to be complete on its own.

Ask, unless nobody can answer

Ask, don't assume. When running unattended, pick the most reasonable reading, proceed, and record the assumption.

This one is about both sides. A session that asks a question with nobody there to answer waits forever. A session that guesses silently builds the wrong thing. Writing the guess down lets me correct it in a minute.

What I would tell you to put in yours

  • Start with an empty file. Add a line the day a session makes a mistake you never want to see again.
  • Put the date and the reason next to the rule. Without the reason, the next model treats it as a preference, and so do you when you edit the file six months later.
  • Write the rule as an action ("read only the range"), not a value ("be efficient").
  • When a rule is broken often, look at who told the session to break it before you blame the model.
  • When a rule can be checked by a script, it may belong in a hook. My next post is about the hooks, and about why I run each new one in warn mode for a week first.

The long version of how the sessions work together is in My AI agent crew.

More posts

All posts →
  1. 21 Nov 2026

    Same agent, rebuilt workspace, a quarter of the bill: what EnvOpt showsA new arXiv paper leaves the model and the harness alone and lets another AI rebuild the workspace the agent works in. On 200 test tasks, the same Claude Haiku 4.5 agent cost $42.36 before and $11.55 after, and passed more tasks.

    AI · 7 min
  2. 21 Nov 2026

    CLAUDE.md vs AGENTS.md: which one Claude Code reads, and why I keep only oneWhen a repository has both files, Claude Code reads CLAUDE.md and leaves AGENTS.md alone unless you import it. I found five of my repositories set up the wrong way round: the real instructions in AGENTS.md, and a CLAUDE.md that only pointed at it.

    How I build · 5 min
  3. 20 Nov 2026

    Running several Claude Code agents at once: worktrees, handoffs and one check per phaseWhat broke when I put many Claude Code agents on the same repositories, and the four rules that stayed: one worktree per agent, small file-disjoint jobs, a rewritten handoff, and one full check per phase.

    How I build · 5 min