The Doctor for Your claude.md

Why a long claude.md makes Claude worse

Claude reads your claude.md every single time it answers you, not once at the start of a session but on every message. So the file is an induction pack that gets re-read before every reply, and if thirty of its forty pages describe things the new starter could see by looking round the office, the stack it can read from package.json, the folders it can list, the commands it can find, then the three rules that actually mattered are buried in the middle and get skimmed with the rest. That is the rule you wrote that keeps getting ignored. It is not Claude, it is the file, and the longer you have made it the worse it gets.

Anthropic have built a doctor for it. The /doctor command has been in Claude Code since July 2026, it goes through everything your setup loads, finds what is costing you memory without earning it, shows you the trim and asks before it touches a thing. Here is where to run it, what it reads, what it looks for, and what to let it take.

Step One, Run It Inside a Session

Open a terminal in the project folder, start Claude Code with claude, and type the command at the prompt. It has to be inside a session, because the version you can run from the shell without starting Claude, claude doctor, only checks the install and never looks at your files. The full checkup, the one that reads your claude.md and can fix things, is the slash command.

Step Two, What It Reads

It is not just the file at the top of the project. It reads every claude.md the project loads, and it treats the ones you committed differently from the two that are yours alone. The committed files get the trim, and your own two get checked against them for repeats and for two rules that disagree.

1. claude.md at the project rootTrimmed. Anything Claude could read from the code itself is proposed for the cut.
2. .claude/claude.mdTrimmed the same way. Both of these load on every message, so they matter most.
3. claude.md in a nested folderScanned as well. These only load when Claude works under that folder, which is where folder only rules belong.
4. .claude/rules/*.mdScanned with the checked in files.
5. ~/.claude/claude.md and claude.local.mdYour own two, never committed. Checked for lines that repeat the project files and for two rules that disagree, and these are the only ones it edits for that.

Step Three, The Six Things It Looks For

Every check runs every time, and where one finds nothing it says so in a line and moves on. It also checks the install itself, leftover copies, path problems, a settings file that will not parse, and any hook you have set to run automatically that is dragging each turn out, but those are the boring ones, and these six are the ones that change how Claude answers you.

1. 1
   Anything it could have worked out from the codeThe stack, the folder layout, the commands already in package.json. Claude can read all of that, and a line telling it again is a page of the induction pack it skims.
2. 2
   Anything it could have worked out from the documentsA paragraph in the root file restating what a doc in the folder already says. It reads the folder, so the restatement is cost without value.
3. 3
   Anything you have said twiceThe same rule in two files, or two rules that cannot both be true. It flags the pair and proposes which one stays.
4. 4
   Rules that only matter in one folderGuidance that only applies under one directory, sat in the root file where every message pays for it. It moves to a claude.md in that folder.
5. 5
   Guidance that should be a skillLong instructions for one kind of job, loaded every time whether that job is happening or not. It offers to move them into a skill that loads only when needed.
6. 6
   Skills and connectors you pay for in memory but never useEvery skill, connector and plugin costs memory on every message. It lists what you have not touched against what each one costs, so you can prune.

Step Four, Say Yes, or Pick

You get a plain summary first, then a table with a row for each file, skill and connector it has something to say about, and then one question with three answers. Clean up everything, let me pick, or keep everything. Pick the middle one and it walks you through the changes group by group rather than line by line, so you can take the trim and leave the rest. Nothing changes until you answer, and everything it changes is shown to you.

The one honest bit. Say yes to the trim, but read the plan when it offers to move rules into skills or into nested files. That is usually the right call, and it changes when Claude sees those rules, from every message to only when the job or the folder comes up. And the doctor judges whether a line is derivable or repeated, never whether it is right, so a wrong rule that is stated once and cleanly will sail straight through.

Before You Say Yes, Four Habits That Keep the Damage at Zero

Chances are it works brilliantly first time. But these files are the standard operating procedures for how your business runs, and the doctor is a very good junior proposing an edit to them, so treat the trim the way you would treat any edit to your SOPs.

1. Save a copy firstIf the project is in git, commit before you run it, so the whole trim is one change you can undo in a line. If it is not, copy the folder. Thirty seconds, and it turns a risk into a choice.
2. Read the diff, not the summaryThe summary says what kind of thing it cut. The diff shows the lines. Read the lines, because a rule that looked derivable to the doctor may be there precisely because Claude kept getting it wrong.
3. Keep the always-on rules where they areAnything that must hold in every session, whatever the job, stays in the root file even if the doctor offers to move it. Tell it so and it leaves them.
4. Run it again in a monthFiles grow back. A trim is a habit, not an event, and the second run is quicker because the first one taught you what you tend to add.

What to Keep, and What to Let It Take

The test for every line is whether Claude could have worked it out by reading the project. If it could, the line is costing you on every message and buying nothing. If it could not, the line is the point of the file.

Keep

1. How you like to workExplain before you act, push back when I am wrong, tell me what you changed. Claude cannot read your preferences from the code.
2. The don'tsNever commit the env file, never touch the generated folder, never send anything. Rules, not descriptions.
3. The gotchasThe thing Claude keeps getting wrong in this repo, and the things it genuinely cannot guess.
4. Commands that are not written down anywhere elseIf it is in package.json, cut it. If it only lives in your head, keep it.

Let it take

1. The stackClaude reads package.json before you have finished typing.
2. The folder layoutIt can list the folders. A paragraph describing them is the thirty pages.
3. Anything that restates the codeA comment on what a function does belongs in the function.
4. The same rule twiceOne copy, in the file that loads when the rule matters.
5. Rules for one folderThey move to that folder and stop costing every other message.

If your claude.md started from a template, the one on the three tiers page is built round this split already, the computer file for how you work, the project file for what Claude cannot guess, the folder file for the rules that only apply there.

If You Cannot Run the Doctor

On an older Claude Code, or if you want the audit without the changes, hand Claude the job yourself. This asks for the same cut list the doctor builds and stops before touching anything.

Go Deeper

1. The three tiers of claude.mdWhich file each rule belongs in, with a template for all three.
2. Why you hit your limit so fastWhat every message re-reads, and why a fat setup costs you on all of them.
3. A skill is a correction you keptWhere the guidance goes when the doctor moves it out of the root file.