How to Write a Claude.md File Without Killing Performance
Anthropic's own data shows long Claude.md files cause Claude to ignore rules. Here's how to audit and trim yours the right way.
What is a Claude.md file for?
A Claude.md file is the persistent context file Claude Code reads at the start of every session. It’s meant to hold the stuff Claude can’t figure out on its own: team conventions, decisions already made, phrases a client hates, tools that are off limits. It is not supposed to be a running diary of every mistake Claude has ever made. That distinction is exactly where most people go wrong, and it’s why Anthropic has given conflicting-sounding advice about it over the past year.
TL;DR
- Anthropic cut over 80% of Claude Code’s own internal system prompt when the Claude 5 models shipped, and reported no measurable loss on their coding tests, which is a strong signal that most “helpful” instructions are dead weight.
- Anthropic’s documentation recommends keeping Claude.md under 200 lines, because longer files make the model more likely to ignore the rules inside them.
- An external study found that context files written by AI tools made agents perform slightly worse while costing about 20% more to run, meaning bloated files have a real token cost even when they’re not actively harmful.
- The right audit question is “would removing this line cause Claude to make mistakes?”, not “could this line ever be useful,” which is a much lower and much more dangerous bar.
- Deleting the whole file and starting over fixes bloat but throws out real knowledge, like team decisions or client-specific rules Claude has no way to infer from the codebase.
- Running
/doctor prompt auditis a fast first pass that flags instructions written for older models and references to files that no longer exist. - Claude Code now reads agents.md when there’s no Claude.md present, so teams using both conventions can standardize on a single file.
Remy doesn't write the code. It manages the agents who do.
Remy runs the project. The specialists do the work. You work with the PM, not the implementers.
Why does a long Claude.md file hurt performance?
The mechanism isn’t mysterious. Every line in the file competes for the model’s attention alongside your actual prompt, your codebase, and whatever else is in context. Anthropic’s own documentation states plainly that longer Claude.md files make Claude more likely to ignore the rules you’ve written, which defeats the purpose of writing them in the first place. A separate study referenced in discussions about this found that context files generated by AI tools (as opposed to hand written by a person who actually knows the constraints) made agents perform slightly worse and cost around 20% more per run.
That 20% isn’t about any single instruction being wrong. It’s the tax of processing extra tokens on every single call, whether or not those tokens change the output. A file full of generic reminders like “write clean code” or “test your changes” isn’t teaching Claude anything it doesn’t already do. It’s just overhead.
The strongest piece of evidence here is what Anthropic did to its own product. When the Claude 5 models launched, the team cut more than 80% of Claude Code’s internal system prompt and saw no measurable drop in coding benchmark performance. If the company building the model is willing to delete most of its own prompt and lose nothing, that’s a strong hint that most of what’s sitting in your Claude.md is similarly disposable.
Should you delete your Claude.md and start fresh?
Not entirely, and this is where a lot of advice has overcorrected. One school of thought says to wipe the file every six months and rebuild it from scratch. The logic is sound: files accumulate cruft, nobody goes back and prunes them, and eventually you’re carrying instructions written for a model that’s two generations old. But full deletion treats a quality problem as a quantity problem. You lose the lines that were actually doing work, not just the dead ones, and you have no way of knowing which was which until something breaks.
The rules worth keeping are the ones Claude has no way to derive from your files or training data: a team decision that overrides a common default, a list of banned phrases for a specific client, a note that a particular directory is legacy code and shouldn’t be touched. These aren’t things Claude can infer by reading your repo. Everything else, especially generic coding advice or instructions that describe behavior modern models already default to, is a candidate for the cut.
How do you actually audit a Claude.md file?
Anthropic’s own test for each line is a single question: would removing this cause Claude to make a mistake? If the answer is no, or if you’re not sure, that’s a sign the line isn’t earning its place.
A practical process looks like this:
- Run
/doctor prompt auditfirst. It flags instructions written for older model behavior and references to files or paths that no longer exist in your project, which is usually the easiest set of lines to cut with zero risk. - Go through everything that’s left line by line and apply the removal test. Delete anything describing behavior that current models already do by default (planning before acting, checking their own work, not touching unrelated files).
- Keep anything that encodes a decision, constraint, or piece of domain knowledge Claude can’t see anywhere else: pricing rules, client preferences, architectural decisions your team made for reasons not visible in the code.
- If you maintain both a Claude.md and an agents.md, know that Claude Code now reads agents.md automatically when no Claude.md is present, so there’s no need to maintain two separate files covering the same ground.
This is slower than either extreme (never touching the file, or nuking it completely), but it’s the only approach that actually separates signal from noise instead of guessing.
Does this apply to plugins and skill frameworks too?
The same logic extends past the Claude.md file itself. Popular add-ons like Superpowers were built to give Claude a structured method for planning, building, and testing, largely because older models skipped steps without that scaffolding. Since newer models like Opus 5.5 handle more of that reasoning natively, there’s an open question about whether these frameworks still add value or just add tokens.
One informal test ran nine popular skill packs, Superpowers included, hundreds of times against a dummy placebo file of equivalent length. Only two of the nine outperformed the placebo. That’s not necessarily a mark against the frameworks themselves. They were designed to patch gaps in models that have since gotten better at avoiding those exact failure modes on their own. The practical move is the same as with Claude.md: run your actual workflows with and without the plugin, compare real outputs, and keep only what demonstrably changes the result.
What should replace the instructions you cut?
Most of what gets pulled from a bloated Claude.md belongs in the prompt instead, scoped to the specific task rather than loaded on every single session. A tight brief that states what “done” looks like, how it’ll be checked, what’s out of scope, and what Claude shouldn’t touch, does more work in one message than a dozen standing rules sitting in a file Claude reads every time regardless of relevance. Context that’s always true (a client’s banned phrases, a team’s naming convention) belongs in Claude.md. Context that’s specific to one job belongs in the prompt.
Frequently Asked Questions
How long should a Claude.md file be?
Anthropic’s documentation recommends keeping it under 200 lines. Beyond that length, the company’s guidance says Claude becomes more likely to ignore some of the instructions inside the file, which undermines the reason for writing them.
What’s the difference between Claude.md and agents.md?
They serve the same function as a persistent context file. Claude Code will read agents.md automatically if no Claude.md file exists in the project, so you only need to maintain one of the two.
Should I add a line to Claude.md every time Claude makes a mistake?
Not automatically. That approach causes files to grow indefinitely with narrow, one-off fixes. Apply the removal test instead: only keep a new line if Claude would make the same mistake again without it, and the information isn’t something it could reasonably infer from your codebase.
Is deleting Claude.md and starting over a good strategy?
It solves bloat but risks losing rules that were genuinely doing work, like team-specific decisions or client constraints Claude can’t infer on its own. An audit that removes lines individually, rather than wiping the whole file, preserves that knowledge while still cutting the dead weight.
What does /doctor prompt audit actually do?
Other agents ship a demo. Remy ships an app.
Real backend. Real database. Real auth. Real plumbing. Remy has it all.
It scans your Claude.md for instructions written for older model behavior and references to files or paths that no longer exist in the project, giving you a fast first pass of low-risk deletions before you go through the remaining lines manually.
