Why Your CLAUDE.md Is Making Claude Worse (And How to Fix It)

Last Wednesday at 11pm, my phone buzzed.

A friend sent me a screenshot of Claude Code's error log with one sentence: "I'm going to smash my keyboard."

He'd asked Claude to add pagination to his project. Simple, right? Instead, the thing not only added pagination but refactored the entire API error handling layer and renamed every database query to match some new convention it invented. Ran the code. Explosion. Errors everywhere. He asked me: "I wrote a CLAUDE.md file and everything. Why does it listen less the more I write?"

I asked him to send me the file.

Four hundred lines. Four. Hundred.

Project vision. Tech stack overview. Team values. Code style preferences. Even a section that said "I hope you can write elegant code." Mate, you've written a corporate culture handbook, not instructions for an AI. My friend got defensive: "I thought if I was thorough, it'd understand the project better."

Honestly? I've been there.

When I first started using Claude Code last year, I made exactly the same mistake. I figured CLAUDE.md was just a place to dump project documentation so the AI had more context. The more I stuffed in, the more Claude drifted. Change a button colour? It'd refactor the state management. Optimise a query? Here's an entirely new ORM strategy.

Then I figured out something deeply counterintuitive: CLAUDE.md is for agents, not humans.

Think about it. Humans skim. We jump to headings, scan for keywords, grab what we need. Claude doesn't do that. Every time it starts up, it loads your entire CLAUDE.md into its context window. Front to back. Every single word eats tokens. Every extra line dilutes its attention.

I'm not joking.

Anthropic's own developer docs suggest keeping CLAUDE.md at a reasonable length — rule compliance can hit 90%+ when you do. Stuff too much in, and compliance drops. Not gradually. It falls off a cliff. You spend hours writing 200 extra lines of rules, and it listens less. The irony is painful.

So step one: cut the fat.

I've got a hard rule now. The CLAUDE.md in my project root? Max 80 lines. If it's over, I start deleting. Three types of content get the axe immediately.

Restatements of the obvious. "This project uses React 18 + TypeScript" — Claude reads your package.json in one second flat. Why are you telling it? Wishful thinking. "Code should be elegant." "Focus on user experience." Lovely sentiments for humans. Meaningless to an AI. What's elegant? What does "focus on UX" actually mean? It can't interpret that. And glossaries. You've got some internal jargon like "flash-push" meaning rapid deployment, so you explain it in CLAUDE.md. Claude probably never needs this, but it chews through it every single time.

Once you strip all that out, something magical happens. The file shrinks, and Claude suddenly behaves.

Useless words. Delete them.

But where do the actually-important rules go?

That's step two: split them up.

These days, alongside my root CLAUDE.md, I've got a .claude/rules/ directory. Inside, I break things down by topic: code-style.md, testing.md, api-conventions.md. These load by default at startup, sure. But the real power move is path-scoped rules.

Here's an example. I've got a backend project where API handler conventions only apply to files under src/api/. Before, I'd cram those rules into the root CLAUDE.md, and Claude would have to digest them even when editing frontend code. Pure waste. Now I add a bit of frontmatter at the top of the rule file:

paths: src/api/**/*.ts

This rule only loads when Claude's working on API files. Frontend edits? Completely out of context. Saves tokens. Cuts noise. Proper lovely.

I only discovered this mechanism about two months ago. Someone in the community mentioned it, I tried it out.

Game changer.

Made me realise how much of my earlier CLAUDE.md was just... noise.

There's also this thing called Auto Memory, and it's genuinely clever. Claude takes notes while it works. Your project's build commands, your preferred code style, the pitfalls it's hit and how it fixed them — all automatically written into CLAUDE.md. You'll open the file a few days later and find stuff you never wrote. Don't panic. That's Claude's own notes.

Type /memory to view and edit these auto-memories. I check mine every week or two, delete the outdated bits, keep the useful ones. Think of CLAUDE.md as the onboarding doc you write for Claude. Auto Memory is Claude's own working notes. The two together? Claude's understanding of your project deepens over time. It's really, really good.

Speaking of onboarding — bit of a tangent, but this is funny — I actually got asked about CLAUDE.md in a job interview recently. My answer went something like:

"CLAUDE.md gets loaded entirely into context on every startup. Too many rules dilute the model's attention. My approach: keep root CLAUDE.md under 80 lines, split module-specific rules into .claude/rules/ with path-scoped loading, use /init to bootstrap and /memory to maintain. Rule compliance noticeably improved."

Interviewer nodded. I think I passed that round.

Right, back to it.

/init is brilliant. Run it in your project root, and Claude scans your code, reads your README, infers your tech stack, and generates a CLAUDE.md draft. But that's just the starting point. The real value — this approach, I should probably call it a strategy — comes from iteration. Claude messes up once, you add one rule. Three months later, that file is your most valuable AI asset.

My current CLAUDE.md has a rule born from pure pain: Claude once rewrote an entire CSS file while tweaking a button style. The rule I added? "When modifying styles, only touch the relevant selector blocks. Never rewrite the entire file." What's that rule worth? About two hours of my life I spent debugging.

A few principles I always follow when writing CLAUDE.md. These trump every trick.

Be specific and verifiable. Don't write "code should be concise." Write "functions must not exceed 50 lines. If longer, split into two." Don't write "be mindful of performance." Write "lists with more than 100 items must use virtual scrolling." Claude needs rules it can check, not principles it has to interpret. Give it a ruler, not philosophy.

Explain the why. Add a reason after every rule. Not "use camelCase naming" but "use camelCase naming because the backend API returns camelCase fields — consistency prevents conversion bugs." When Claude understands the why, it makes better decisions even in situations your rules don't cover. Sit with that for a second. It's exactly like mentoring a junior developer.

Keep updating. CLAUDE.md isn't write-once-and-forget. Projects change. Teams change. The pitfalls Claude hits change. I open mine at least once a week, delete what's no longer relevant, add what's new. Last week I removed "use axios for HTTP requests" because the project had fully migrated to fetch.

One last trap I see people fall into — and past me is absolutely guilty of this — is stuffing everything into a single CLAUDE.md until it's bloated beyond usefulness. Here's what I've learnt: some content works better as a Skill than as persistent memory. If something is a whole workflow, something you only need for specific types of tasks, don't let it hog context permanently. Make it a Skill. Call it when needed. Skip it when not.

Really solid feature, that.

Oh, one more thing. Karpathy shared a set of rules a while back — four core principles: think before coding, prioritise simplicity, make precise changes, goal-driven execution. These rules have different names across tools. Codex calls it AGENTS.md. Claude Code calls it CLAUDE.md. The principle is identical. If your team uses both Claude Code and Copilot, you don't need to maintain two files. Just add @AGENTS.md in your CLAUDE.md to pull the other one in, then append Claude-specific rules below.

Configuration, at the end of the day, is iterated. Not designed.

Key Takeaways:

• Keep root CLAUDE.md under 80 lines. Every extra line dilutes Claude's attention. Cut restatements, wishful thinking, and glossaries.
• Split rules by path scope. Use .claude/rules/ with frontmatter paths: to load rules only when relevant. Saves tokens, reduces noise.
• Use /init to bootstrap, /memory to maintain. Let Claude generate a draft, then iterate. Check auto-memories weekly.
• Be specific and explain why. "Functions under 50 lines" beats "code should be concise." Claude needs measurable rules with reasons.
• Consider Skills for workflows. Don't let task-specific procedures hog context permanently.

How many lines is your CLAUDE.md right now? Drop a comment — I'm genuinely curious how bloated we've all let ours get.

claudecode #aiengineering #promptengineering #devtools #anthropic