Your CLAUDE.md File Is Too Long: The Context Diet That Cut Mine 87%

Last updated: August 6, 2026

TL;DR

Anthropic removed roughly 80% of Claude Code's own system prompt for the Claude 5 models, and within a week the internet had compressed that into "delete your CLAUDE.md." I didn't delete mine. I put it on a diet instead: my monorepo's CLAUDE.md went from 1,204 lines to 151 this week, with the deep-dives moved into skills that load on demand and every incident-earned warning kept word for word. The framework I used has four buckets and one test, and the numbers below are from real repos, not a thought experiment.

Why everyone is suddenly telling you to delete your CLAUDE.md

I watched this one build over about a week. Thariq from Anthropic's Claude Code team posted on X that they'd removed about 80% of the Claude Code system prompt for the newest models and lost nothing. Then the Boris Cherny clips started circulating with the summary "delete your CLAUDE.md," and the r/ClaudeCode thread asking "but why? what's the point of it then" sat near the top of the subreddit for days.

Here's the thing the hot take skips. Anthropic's context engineering guidance says context is a finite resource and newer models want curation, not accumulation. Fair. And true of my file – most of my 1,204 lines existed because some model, at some point, got something wrong once. I wrote a rule so it wouldn't happen again. The model got better. The rule stayed. Multiply by two years.

But buried in those same 1,204 lines were maybe 20 that had nothing to do with model quality. Lines like "this env var has an intentional typo, do not fix it." No model improvement makes that discoverable. Delete the file and you delete those too.

What changed with Claude 5

The old CLAUDE.md idioms were workarounds. Repeat everything important. ALL-CAPS the rules. Front-load every detail. That was rational when models needed it. Claude 5 models read the repo well enough to find derivable facts themselves, and – this is the part that changed my file the most – they apply judgment when you explain why a rule exists instead of just shouting it.

The economics are what finally got me to act. Every line in CLAUDE.md gets paid for on every session, relevant or not. A skill gets paid for only when a task touches it. Once I saw the pricing that way, the question for each line stopped being "is this true?" and became "does this earn a seat in every single session?" Most lines don't.

The four-bucket triage

I went through the file section by section. Everything landed in one of four buckets.

Delete – anything the model can derive by reading the repo. My directory tree. The tech-stack table. The list of npm commands that any model finds in package.json in two seconds. Code-pattern examples that were worse references than the actual code sitting next to them. All of it, gone.

Relocate – real knowledge at the wrong altitude. My testing strategy was 161 lines of genuinely useful detail that mattered for maybe 1 in 10 sessions. That's not CLAUDE.md content; that's a skill. Same for the R2 storage setup, the blog CTA logic, the brand intel notes. Each one moved out, leaving a one-line pointer behind.

Rewrite – style preferences dressed up as law. "ALWAYS check packages/ first before writing ANY code" became "Shared code lives in packages/ – app-local copies drift and break the other apps." One sentence, with the reason. The reason does more work than the capitals ever did, because it lets the model handle cases I never thought to write down.

Keep – and this is the bucket that makes the whole exercise safe. Three questions, in order: Was this rule purchased with a real incident? Is violating it irreversible or high-blast-radius? Is it invisible from the code? Any yes and the line stays, stays loud, and keeps its citation. Relocating these is fine. Deleting them is the one mistake you can't undo.

The results: 1,204 lines down to 151

The baseline was worse than I remembered. 1,204 lines, all loaded into every session, 22 of them ALL-CAPS rules. Reading it end to end – which I clearly hadn't done in a while – turned up the duplication this pattern breeds. My database sync workflow was explained twice. One migration check was explained three times. A warning about an archived app appeared in three separate sections, because every time it felt important I'd apparently added it again.

After the triage: 151 lines. Four new skills carry the relocated content – testing strategy at 161 lines, R2 storage at 46, blog CTA at 39, brand intel at 34. The PR removed 1,125 lines and added 383, and most of the additions are the skill files. Always-loaded context dropped about 7×.

The warnings all survived. The archived app that looks live. The never-run-migrations-against-prod rule. My favorite line in the whole file: an env var spelled ENPOINT, on purpose, which any well-intentioned cleanup would "fix" and silently break.

My second repo told the other half of the story. Its CLAUDE.md went from 90 lines to 84. Six lines. There was nothing to cut because I wrote it recently, and apparently I'd already absorbed the style – gotchas and pointers, nothing derivable. AGENTS.md in both repos needed zero changes for the same reason. The diet isn't a new philosophy. It's retrofitting your oldest context files to the style your newest ones already use.

What belongs in a CLAUDE.md file now

Four kinds of content made the cut in mine:

1. Non-obvious operational knowledge – the stuff you can't learn from the code. Which external API returns 200 for content it will later fail to publish. Rate limits. Service quirks.
2. Incident-earned warnings, kept loud – the KEEP bucket, each with the issue or postmortem that paid for it.
3. One-line pointers to the relocated deep-dives.
4. Cross-repo context – where the schema actually lives, which env file is canonical.

The test I used for everything else: if I can answer a line's question with one search of the repo, the line is dead weight.

Where the relocated content goes

Claude Code gives you three places to put what you cut, and they do different jobs:

• Skills (.claude/skills/<name>/SKILL.md) load when a task touches their area. The frontmatter description is the routing signal – write it as "use when...", not a table of contents.
• Rules (.claude/rules/) are modular instruction files with path-specific targeting, so a rule activates only for the files it governs. Rules answer "how work is done here"; skills answer "how to do this kind of task." The Claude Code memory docs cover both.
• Docs plus a pointer (docs/<topic>.md) for reference material humans also read – runbooks, ADRs, onboarding.

One more distinction, since it comes up every time: CLAUDE.md and AGENTS.md aren't competing. AGENTS.md is the cross-tool standard for durable process – how work flows, what gets reviewed, how commits land. CLAUDE.md is Claude-specific repo facts and traps. I wrote up that split in my AGENTS.md deep-dive, and this week reinforced it: both my AGENTS.md files came through the diet untouched.

What not to cut

Four ways I could have botched this, and watched for:

• Deleting instead of relocating. The goal is less always-loaded context, not less knowledge. Derivable content gets cut. Real content moves.
• Skill sprawl. Twenty micro-skills is the same disease in a different organ. Group by task area, and if a skill turns out to be relevant every session, it belongs back in CLAUDE.md.
• Sanding off the voice. A warning that explains why teaches the model judgment. Keep the reasons. Cut the repetition.
• Uniform de-capsing. Not every ALL-CAPS line is bloat. Some lines have earned the right to shout. Run the three-question test before you touch any of them.

Run the diet on your own repo

1. Measure first: wc -l CLAUDE.md AGENTS.md, and count the shouting: grep -cE "CRITICAL|IMPORTANT|NEVER|ALWAYS|MUST" CLAUDE.md.
2. Read the whole file once and mark every fact that appears more than once. That reread is uncomfortable and worth it.
3. Triage every section: delete, relocate, rewrite, or keep.
4. Build the destinations before cutting – every relocated section needs a live skill or docs file first.
5. Smoke test in a fresh session: ask about something you moved ("how do I add a database table here?") and confirm the model finds it through the pointer or the code.
6. Ship it through review like code. A bad merge here degrades every future session, which makes it some of the highest-leverage review time you'll spend.

My two runs landed at 87% and 7% reductions – the second file was already lean. Anthropic's own run was ~80%. Somewhere in that range is your number.

Frequently asked questions

What is a CLAUDE.md file? CLAUDE.md is a markdown file in your repo root (or ~/.claude/ for global preferences) that Claude Code loads at the start of every session. It carries project context: conventions, commands, warnings, and pointers. Think of it as standing instructions the agent reads before your first prompt.

How long should a CLAUDE.md file be? As short as it can be while keeping every non-derivable fact. My repos landed at 151 and 84 lines. Older guidance said "under 300–400 lines"; with Claude 5 models the better rule is that every line must earn its per-session cost, because detail can load on demand instead.

Should I delete my CLAUDE.md file? No. Delete the derivable content, relocate the deep-dives, and keep the incident-earned warnings. A model can rediscover your directory structure; it cannot rediscover that your prod database must never receive a migration or that an env var's typo is intentional.

What did Anthropic actually change for Claude 5? Anthropic removed roughly 80% of Claude Code's own system prompt for the Claude 5 models, reporting no performance loss. The newer models derive facts from code, handle ambiguity, and apply judgment, which makes repeated rigid instructions mostly noise that crowds out genuinely critical context.

What is the difference between CLAUDE.md and AGENTS.md? AGENTS.md is the cross-tool standard for durable process: how work flows, what gets reviewed, how commits land. CLAUDE.md carries Claude-specific repo facts, gotchas, and operational knowledge. Keep process in AGENTS.md, keep repo-specific traps in CLAUDE.md, and state each fact in exactly one place.

Does Claude Code read AGENTS.md? Yes. Claude Code reads AGENTS.md alongside CLAUDE.md, and a common pattern is a one-line @AGENTS.md include at the top of CLAUDE.md so both load together. In my diet runs, AGENTS.md needed no trimming – it was already written in the lean, judgment-first style.

What are Claude Code rules (.claude/rules)? Rules are modular markdown instruction files in .claude/rules/, supporting path-specific targeting so a rule activates only for the files it governs. They're one of the three progressive-disclosure surfaces – rules for "how work is done here," skills for task expertise, docs for human-readable reference.

What belongs in CLAUDE.md versus a skill? CLAUDE.md keeps what every session needs: operational gotchas, incident-earned warnings, and pointers. A skill holds expertise only some tasks need – a testing strategy, a subsystem's architecture, a deploy runbook. The budget rule decides: CLAUDE.md lines cost every session; skills cost only when relevant.

How do I know if a rule should stay in CLAUDE.md? Ask three questions. Was it purchased with a real incident? Is violating it irreversible or high-blast-radius? Is it invisible from the code? Any yes means it stays, stays emphatic, and keeps its citation. Everything else gets deleted, relocated, or rewritten as one sentence with the reason.

Does a long CLAUDE.md make Claude Code worse? It costs you twice. Every line consumes context budget on every session, and low-value lines dilute the critical ones – Anthropic's context engineering guidance calls context a finite resource with diminishing returns. A 1,204-line file buries the 20 lines that actually prevent incidents.

So no, don't delete your CLAUDE.md. The discourse is directionally right and literally wrong. The file was never the problem – the accumulation pattern was. Mine is 151 lines now, and for the first time in two years I can read the whole thing and defend every line in it.

If you're building with Claude Code and want to compare notes on what survived your own diet, the WotAI community is where I share these runs first: https://skool.com/wotai