Your CLAUDE.md Is Probably Too Long

Posted on Oct 20 • Originally published at irian.to

CLAUDE.md is how Claude Code finds instructions. At launch, Claude Code walks up the directory tree from your current working directory and loads every CLAUDE.md along the way. Run it in foo/bar/ and it loads both foo/bar/CLAUDE.md and foo/CLAUDE.md. CLAUDE.md files in subdirectories load later though, the first time Claude reads, writes, or edits a file in that subdirectory.

If you're in a monorepo and another team's CLAUDE.md keeps sneaking in, the claudeMdExcludes setting skips specific files.

Every CLAUDE.md that loads costs you context.

In the antipatterns post, I said CLAUDE.md is like the staples in your fridge: milk, eggs, butter. Claude loads it at the start of every session, so whatever is in it takes up space in every conversation. It even gets re-read from disk and re-injected after /compact. You can't get rid of it. It's like spam mail: no matter how many you unsubscribe from, they just keep showing up.

That's the whole point of CLAUDE.md. It's also the problem.

The Claude Code docs call it "the over-specified CLAUDE.md":

If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise.

Anthropic's guidance is to target under 200 lines per CLAUDE.md file: "Longer files consume more context and reduce adherence." The claude-code-best-practice repo repeats the 200-line target (it also points to HumanLayer, who keep theirs around 60).

Here's the counterintuitive part. When Claude ignores a rule, my gut feeling is to add something. Then add another rule. Then add a louder rule like IMPORTANT: ALWAYS RUN THE TESTS... which makes the file even longer, amplifying the problem.

Anthropic used to suggest exactly that kind of emphasis. Their 2025 best-practices post mentioned tuning instructions "adding emphasis with 'IMPORTANT' or 'YOU MUST'". The current docs are more conservative: add emphasis to one line, because "if you emphasize many lines, none of them stands out." It's like you're in a room where half the people are shouting. You can't hear anything.

If Claude ignores a rule, your CLAUDE.md is probably too long, not too short.

Reading the how to write an effective Claude docs, here's what Anthropic suggests including in CLAUDE.md, and what to leave out:

The left column is stuff Claude can't know. The right column is stuff Claude already knows, or can find out in two seconds with grep. Claude can read your package.json. It doesn't need you to tell it you use React.

Would removing this cause Claude to make mistakes?

If not, cut it. If Claude already does something right without being told, the line is dead weight. Delete it, or turn it into a hook if it really must happen every time.

A good CLAUDE.md looks boringly short. An example from Anthropic:

# Bash commands - npm run build: Build the project - npm run typecheck: Run the typechecker # Code style - Use ES modules (import/export) syntax, not CommonJS (require) - Destructure imports when possible (eg. import { foo } from 'bar') # Workflow - Be sure to typecheck when you're done making a series of code changes - Prefer running single tests, and not the whole test suite, for performance Enter fullscreen mode Exit fullscreen mode What if I miss anything? When I started using Claude (over a year ago, time flies!), I found a number of CLAUDE.md example files online. I didn't know what I was doing, so I naturally copy-pasted the most comprehensive (aka verbose) CLAUDE.md files available out there.

They would say something like, "Follow SOLID principles, keep it DRY, etc." All good engineering practice.

My CLAUDE.md quickly ballooned into a few hundred lines of monstrosity. All because I was afraid that if I didn't write them down, Claude would start outputting garbage code.

Fast forward to 2026, now with Opus 5.5 and Fable 5.1 available. Does Claude even need to be told to follow SOLID principles? I think it's smart enough to apply those principles. Why treat Claude like a dumb-yet-very-smart assistant? People trust it to one-shot a Mario Kart game, and yet somehow it doesn't practice SOLID principles? I think not.

Don't worry if you're missing something. It's not like Claude is going to start outputting garbage if you forget to put a line in. Claude is smart (a lot smarter than me!). Don't fear missing out on a line in your CLAUDE.md.

Experiment to see if a missing line makes a difference. Prompt Claude to build something. Then remove some "obvious" good engineering lines, like your "follow SOLID principles". Start a new session and give Claude the same prompt. Compare the output!

Don't copy the most verbose, highly rated CLAUDE.md repos out there. Pick the one that resonates with you most. Even better, fill it out yourself! Or ask Claude to write your own CLAUDE.md!

Vague instructions waste lines twice: once because they take up space, and again because Claude can't act on them.

Nobody disagrees with "Format code properly", and nobody can follow it. Which format? Says who? Claude will just guess, which is what it was doing before you added the line.

A concrete rule is verifiable. Either the indentation is 2 spaces or it isn't. You can tell whether Claude followed it, and Claude can tell too.

What if everything in your CLAUDE.md really is useful? Then don't put it all in one file. You have a few options. Some are better than others.

Put instructions in.claude/rules/, one markdown file per topic, and scope them with a paths field:

--- paths: - " src/api/**/*.ts" --- # API Development Rules - All API endpoints must include input validation - Use the standard error response format - Include OpenAPI documentation comments Enter fullscreen mode Exit fullscreen mode The above example is from Anthropic docs. This rule only loads when Claude reads, writes, or edits a matching file. If you're working on the frontend all day, Claude will leave your API rules alone.

Note that a rule without paths loads at launch, just like CLAUDE.md. Make sure to scope your rules!

CLAUDE.md can pull in other files with @path/to/file:

See @README for project overview and @package.json for available npm commands. # Additional Instructions - git workflow @docs/git-instructions.md Enter fullscreen mode Exit fullscreen mode When I first read "if your instructions are growing large, split them using imports," I was confused. If my CLAUDE.md is 199 lines and I import another 100, isn't that just a 299-line CLAUDE.md with extra steps?

Yes. The docs say so now: imports "help you organize a long file but don't reduce its context cost, because imported files also load at launch." Imports are for tidiness and sharing. They don't help with length. Path-scoped rules do.

You can have CLAUDE.md files at several levels:

As eesel puts it: "Put detailed rules next to the code they govern when that makes the scope clearer, rather than making one enormous root file."

Two more places to move stuff out of CLAUDE.md:

Block-level HTML comments ( <!-- like this --> ) are stripped before CLAUDE.md is injected. You can leave notes for the humans maintaining the file without spending any of Claude's context on them.

Treat CLAUDE.md like code: review it when things go wrong, prune it regularly, and test changes by observing whether Claude's behavior actually shifts.

Speaking of contradictions, if two rules disagree, Claude may just pick one. The more files you have, the more likely that is. Another reason to keep things short.

Finally, don't copy the internet's CLAUDE.md. There are a lot of "ultimate CLAUDE.md" files out there.

From Every's piece on compound engineering:

Your context should reflect your codebase, your patterns, and your hard-won lessons. Ten specific rules you follow beat 100 generic ones. And when rules stop serving you, delete them.

Someone else's CLAUDE.md fixes someone else's mistakes. Read them for ideas. Write your own.

When's the last time you checked your CLAUDE.md file?

Diwank wrote about Julep in Field Notes From Shipping Real Code With Claude:

Think of CLAUDE.md as a constitution for your codebase.

A constitution doesn't list every law. It sets the big principles and leaves the details for later. CLAUDE.md works the same way. Keep the decisions that shape the whole codebase, and the reasons behind them. Claude can see that you use Postgres by reading your code. It can't see why you picked it.

Some corrections only matter in one tiny corner. Maybe Claude keeps breaking an API contract, or one file has a convention nobody would guess. A line in CLAUDE.md loads into every session, even when Claude never goes near that file.

A good idea from Julep isn't in CLAUDE.md at all. It's anchor comments. Have specially prefixed comments in the code itself.

# AIDEV-NOTE: API Contract Boundary - v2.3.1 # ANY changes require version bump and migration plan # See: docs/api-versioning.md @router.get ( " /users/{user_id}/feed " ) async def get_user_feed ( user_id: UUID ) -> FeedResponse:... Enter fullscreen mode Exit fullscreen mode Julep's CLAUDE.md just tells Claude the convention: use AIDEV-NOTE:, AIDEV-TODO:, or AIDEV-QUESTION:, grep for existing anchors before scanning files, update them when the code changes, and never remove an AIDEV-NOTE without asking.

That's a few lines in CLAUDE.md that replace what could have been hundreds. Instead of describing every fragile corner of the codebase up front, the knowledge lives right next to the code it's about, and Claude only reads it when it's working there. Diwank calls them street signs: "Think of your codebase as a city and anchor comments as street signs." Same idea as path-scoped rules, just inside the code.

For each line in CLAUDE.md: ├── Would removing it cause Claude to make mistakes? │ └── No → delete it ├── Could Claude learn it by reading the code? │ └── Yes → delete it ├── Is it vague ("write clean code", "keep things organized")? │ └── Yes → make it concrete, or delete it ├── Does it only matter for part of the codebase? │ └── Yes → path-scoped rule or a nested CLAUDE.md ├── Is it a workflow you only need sometimes? │ └── Yes → skill ├── Must it happen every single time, no exceptions? │ └── Yes → hook └── Otherwise → keep it in CLAUDE.md Enter fullscreen mode Exit fullscreen mode Then run /context and check that what loaded is what you think loaded.