We're deep into the "AI-assisted" fad/lifestyle now, and one pattern I heard early on hasn't paid off as much as I'd like: every time Claude does something "wrong," tell Claude to add a correction to CLAUDE.md.

CLAUDE.md is the instruction file Claude Code loads into every conversation in your project. Adding corrections works in theory, but after months on a project, your CLAUDE.md is 600 lines long and may or may not be accurate anymore. The way to tell is that Claude starts violating rules because it's overloaded. The file stopped working as instructions and became a changelog of past mistakes, which causes more mistakes that compound.

This post covers why a long CLAUDE.md stops working, what belongs in it, where everything else goes, and a three-question test for every line.

Why Does a Long CLAUDE.md Stop Working?

LLMs read (and charge us for) "tokens," which are chunks of text. Everything we send in a session, CLAUDE.md included, fills the context window, and the more tokens in that window, the more likely the LLM is to "hallucinate" and skip instructions. Your goal is to send it a targeted batch of tokens.

Rules accumulate and contradict one another unless you prune them. A rule that applies to everything sits right next to a rule that helped with a single task, so the "everything" rule loses signal. You'll also have generic rules like "write clean code" or "follow best practices" that take up context space but change no behavior (what's best practice to you might be garbage to the LLM).

What Should Go in CLAUDE.md?

Follow one rule:

CLAUDE.md is for what is true in every conversation, written in as few words as possible.

Start with four categories:

1. Build and test commands: make develop to run the dev environment, .claude/support-scripts/phpunit/run.sh to run tests
2. Invariants and "rakes": directory "x" is generated, so never edit it
3. House styles: naming, formatting, and prose rules
4. Project structure: where the major pieces live, not every file in your project

The invariants category turns a bloated entry into one line:

<!-- Before: a bloated rule written after one incident -->
When working on the build process, remember that in the past there were
issues where files were edited in the generated output directory and then
lost, which caused confusion, so please be careful and make sure you are
always editing the source files instead of the generated ones, because the
generated ones get overwritten every time the build runs.

<!-- After -->
`build/` is generated. Never edit it. Source lives in `src/`.

Where Should Everything Else Go?

Apply the single responsibility principle and split rules across five destinations:

Destination	What goes there	When Claude loads it
Directory-level CLAUDE.md (tests/CLAUDE.md)	Rules for one part of the codebase, like test-only conventions	When it works with files in that directory
Skills	Procedures you want Claude to pick up without being asked	Description always; full instructions when a task calls for it
Commands	Task-specific procedures you trigger by name, like "/create-pull-request", "/add-database-column", and "/review-pull-request"	Only when you run them
.ai/docs/	Reference materials the agent maintains and can read on demand	When the agent reads them
Hooks and wrapper scripts	Rules that should be enforced, not requested, as an AI guardrail	Never: they run outside the context window

Two more options affect the size of the file. CLAUDE.local.md holds your personal preferences without committing them for the whole team. @path/to/file imports pull another file into CLAUDE.md, but imported files still load every session, so they organize the file without shrinking the context.

How Do You Decide If a Line Belongs in CLAUDE.md?

I run a three-question test on every line in CLAUDE.md:

1. Is it true for every conversation?
2. If I removed it, would the agent's behavior change?
3. Could a deterministic script enforce it?

A "yes" on question 3 means move it to a deterministic script. That cuts your token usage and makes the rule impossible for the LLM to bypass (because it will).

A "no" on question 1 or 2 means move it or delete it.

Don't do this without thinking and testing the results, because a shorter file isn't better by default. Deleting a real invariant to hit a "target" line count can make everything slower and more error-prone.

When I ran this test on UnleashedPodcasts's CLAUDE.md, it went from 600 lines to 150. 15 rules moved into skills and commands, 25 became hook scripts, and 50 got deleted. The only noticeable change was a reduction in token usage.

How to Trim Your CLAUDE.md

Think of your CLAUDE.md as the briefing you'd give a new teammate on day one, because every new session starts from that briefing. Give the LLM enough to get working without overwhelming it.

Don't go crazy and blow up your CLAUDE.md file. There's a reason each line was added, and you can't nuke them all and hope for the best. Instead:

1. Find the three longest rules in your CLAUDE.md.
2. Run each one through the three-question test.
3. Move it, script it, or delete it based on the answers.
4. Check Claude's output. If it got worse, try something different.
5. Repeat tomorrow with the next three.
6. Run every new rule through the test before it goes in, so the file stops growing by default.

AI notice:

The outline for this post was generated via AI, then I wrote the prose and ran it through Grammarly.