I Told Engineers to Delete Their CLAUDE.md. Then I Kept Mine for Two More Months.

The advice was simple. The models got smarter, so your CLAUDE.md should get smaller.

I said it on stage in August. I said it on LinkedIn. I said it to anyone at a meetup who complained that Claude Code was ignoring their rules.

Then I went home and kept adding to mine.

How a CLAUDE.md Grows

Nobody writes a 2,000-line instructions file on purpose. It happens one fix at a time.

Claude runs a command you don't like, so you add a line banning it. It picks the wrong package manager, so you add another. It uses a pattern from an older version of your framework, so you add a paragraph. Every line makes sense on the day you write it.

Mine had banned commands, script preferences, framework rules, and a custom start script that launched Claude with its own system prompt on top. I'd built a small bureaucracy and called it configuration.

The problem is that nobody ever reviews the file. Rules written for last year's model stay in there, telling today's model things it already knows. Or worse, things that are no longer true.

The 2,500-Line File

What finally pushed me was helping another engineer on a large project. Claude kept doing odd things. It second-guessed itself, ignored some instructions and over-applied others.

Her CLAUDE.md was about 2,500 lines long. It contradicted itself in several places, and all of it got loaded on every single task. She was paying tokens for Claude to read a rulebook that argued with itself, then wondering why it seemed confused.

She deleted it. Her problems went away.

I'd just watched someone else live with the consequences of my own bad habit. So in late October I finally took my own advice.

What Happened When I Deleted Mine

I removed the project file, cleaned out the system-level CLAUDE.md on my development box, and retired the custom start script.

Then I waited for things to break.

They didn't.

• Claude feels snappier, especially around bun commands, which is exactly where my rules used to be thickest.
• It does less cross-checking before it acts. Fewer detours to verify something against my instructions.
• Nothing regressed. The dev server starts, the project checks run, the work gets done.

That's the uncomfortable bit. A lot of what I thought was guidance was just friction.

The Bloat I Didn't Know I Had

Deleting the file fixed the obvious problem. Running /doctor showed me the less obvious one.

I had duplicate agent files, installed once through a package and once locally. I had skills I'd tried once months ago and forgotten about, including a set of marketing skills I installed out of curiosity and never touched again.

Then the sneaky one. Skills and MCP servers you add in Claude on the desktop or the web sync across to Claude Code on the same account. So every connector I'd added for some unrelated experiment was quietly turning up in my coding sessions too.

Why does that matter? Claude has to scan the description of every skill and every tool it has, on every run, to work out what's relevant. More descriptions means more to read, more chances to pick the wrong thing, and more tokens spent before any real work starts.

Fixing the Sync Problem

There's no toggle to stop one specific MCP server from syncing. You can switch syncing off completely, but if you rely on some of those connectors, that's far too blunt.

The fix I landed on: disable the servers, plugins and skills you don't need in the machine-level config, not the project config. A project-level disable only covers that one project. Machine level covers everything, which is what you want for things you never use when coding.

A Short Checklist

If Claude Code "got worse" for you or your team, go through this before you blame the model:

1. Read your CLAUDE.md and ask, rule by rule, whether today's model actually needs it. Better still, delete the whole thing for a week and see what you miss.
2. Run /doctor and look at what's installed. Duplicates and forgotten experiments are common.
3. Check which skills and MCP servers came across from the desktop or web app.
4. Disable what you don't use, at machine level.
5. Keep whatever is left short enough that a person could read it in two minutes.

The Lesson I Keep Relearning

Every time the models get better, some of the scaffolding we built around the old ones turns into dead weight. The rules that saved you six months ago can be the reason you're stuck today.

Knowing that is easy. Actually going back and cleaning up is the hard part.

When did you last read your own CLAUDE.md from top to bottom?

If you want the bigger picture, I've written about what agentic software engineering looks like in practice and how to build production agents with Claude Code. I also post workflows like this most weeks on LinkedIn.