Why Claude Code Ignores You

A friend was venting about Claude Code the other day. He’d put rules in his CLAUDE.md, clear and specific, and Claude would just ignore them. Not always, but enough that he was losing trust.

I’d been through the same thing. I kept adding to my CLAUDE.md file because it was the easiest way to nudge Claude on how my project works and how I want it to build. Pretty quickly I noticed Claude’s results getting worse, not better, and my CLAUDE.md alone was loading roughly 4,000 tokens into every conversation whether they were relevant or not. Every instruction Claude doesn’t need right now is noise, and all that noise makes it harder to follow the ones it does. Researchers call this context rot.

How CLAUDE.md Actually Works

Claude Code has a 200,000 token context window. That sounds like a lot until you realize how much is already spoken for. Claude Code walks up the directory tree from your working directory, loading CLAUDE.md and CLAUDE.local.md at each level. It also loads .claude/CLAUDE.md and your global ~/.claude/CLAUDE.md. All of it, every time, no matter what you’re asking about. (CLAUDE.md files in subdirectories are the exception. Those load lazily when Claude reads files in that subdirectory.)

And your CLAUDE.md isn’t the only thing competing for space. The system prompt (~4,200 tokens), auto memory, environment info, MCP tool listings, and skill descriptions all load at startup too. Anthropic’s interactive context window walkthrough shows the full breakdown.

I was treating my CLAUDE.md like a wiki instead of a briefing. Anthropic’s guidance says to keep each CLAUDE.md under 200 lines. The more instructions you pack in, the less consistently any single one gets followed.

Context Rot

The diagram above makes this look like a capacity problem. It’s more than that. Even if the context window were infinite, a bloated CLAUDE.md would still make Claude worse.

Chroma tested 18 LLMs on a simple word-recall task and found that accuracy falls off a cliff as you bury the signal in noise. Liu et al. found the same pattern: LLMs lose track of information buried in the middle of their context.

So it’s two problems at once. A bloated CLAUDE.md shrinks your working space because it’s permanent and gets re-read from disk after every compaction. But it also rots the context you have left, because 4,000 tokens of image optimization guidelines are noise when you’re debugging a database query. Less room and worse accuracy in the room you have.

Andrej Karpathy called the discipline of managing this “context engineering”: filling the window with just the right information for the next step, not just as much as you can fit.

The Fix: Link Instead of Inline

I kept wondering why Claude was more consistent on one of my projects than another. Same model, same kinds of tasks. The project with database migrations, auth token handling, RLS rules, a release process, compliance requirements, and a custom UI component system. Plenty of rules and conventions. But the CLAUDE.md was about a third the size of my other project. The only difference was 500 fewer lines of instructions.

The trick is a reference table at the bottom:

## Reference Docs

Read these on-demand when working in the relevant area:

| Doc | Path | When to read |
|-----|------|-------------|
| Database & Migrations | `.claude/docs/database.md` | Adding tables, writing migrations |
| Auth & Token Handling | `.claude/docs/auth.md` | Working with API auth flows |
| Data Lifecycle | `.claude/docs/data-lifecycle.md` | Adding models, modifying webhooks |
| UI Patterns | `.claude/docs/ui-patterns.md` | Building UI components |

Critical rules stay inline, but short, with a link to the full context:

## Critical Rules

- **Never read the access token directly** outside the auth context.
  Use the refresh utility. See [Auth](.claude/docs/auth.md).
- **Every new database table must enable RLS** in the same migration.
  See [Database](.claude/docs/database.md).

The rule fires immediately. The full explanation is one tool call away.

What Goes Where

Claude Code already gives you two levels of instruction loading. CLAUDE.md loads every conversation. .claude/rules/ loads automatically when Claude touches matching file paths. Both are built-in.

The .claude/docs/ reference table from the previous section is the piece I added. It handles guidelines that don’t map to file paths, things like deployment procedures or auth flows. Claude reads them when it sees a relevant task and checks the table.

After doing this across a few projects, my rule of thumb is:

The first two rows are Claude Code’s built-in structure. The third is the pattern that bridges the gap for everything else.

The question I kept asking was: would removing this actually cause Claude to make mistakes? If not, it didn’t need to be inline.

Try It Yourself

Anthropic keeps improving how Claude Code handles context. Auto memory, path-scoped rules, lazy loading in subdirectories. But even with all of that, I’ve found that a lean CLAUDE.md with linked docs is the single most impactful thing you can do for consistency. Claude sometimes pushes back on the split or miscategorizes what should stay inline, but a quick review of what it produces gets you most of the way there.

If your CLAUDE.md has grown past a couple hundred lines, it’s probably worth splitting. Here’s a prompt you can paste into Claude Code that will analyze yours and do the restructuring.

My CLAUDE.md is 140 lines now. Same project, same rules. Claude just follows them more consistently because they’re not competing with 600 lines of noise.