I recently published an article on why Boris Cherny, the engineer who built Claude Code, uses a CLAUDE.md of about 100 lines while most developers write 800 or more.
I felt good writing it. Then I opened my own global CLAUDE.md.
It was over 500 lines.
I had spent a day explaining a philosophy I was not living. So I did the obvious thing. I applied the advice to myself and watched what happened.
Table of Contents
The Confession
Your global CLAUDE.md lives at ~/.claude/CLAUDE.md. It loads into every single Claude Code session, in every project, on every machine you work on. Whatever you put there is the tax you pay on all of it.
Mine had grown the way these files always grow. A formatting preference here. A coding standard there. A section on how to handle errors. A block explaining my tone. Notes on testing. A list of things to never do. None of it added in bad faith. Each line felt reasonable the day I wrote it.
Five hundred lines is what reasonable looks like after a few months of “just one more rule.”
What a 500-Line CLAUDE.md Actually Costs
Here is the part most people do not feel because it is invisible.
Every line of your CLAUDE.md is sent as input on every call. Not once per session. Every call. A long file is not a one-time setup cost. It is a recurring charge against your context window and your bill, paid continuously, in the background, forever.
That has two consequences.
The first is money. A bloated instruction file quietly inflates the token count of every interaction you have. You do not see it. You just pay it.
The second is worse. Quality degrades as your context window fills. The model does not get dumber in a vague, hand-wavy sense. It gets measurably worse at staying on track once the window is heavily loaded. Starting every session with 500 lines of instructions means starting every session already part of the way toward that cliff.
Read that back. The file I wrote to make Claude work better was making it work worse. From the first message. In every project.
The Cut
I did not rewrite the file. I interrogated it.
Boris’s approach gives you exactly one test. For every line, ask: “What specific mistake did Claude make that this rule prevents?”
If you can name the mistake, the line stays. If you cannot, it was never instruction. It was anxiety written down.
I went through all 500-plus lines with that single question. The results were not close.
The error handling philosophy: Claude already does this well. Cut. The tone guidance: it was duplicating defaults the model already has. Cut. The coding standards: standard best practice the model follows without being told. Cut. The long list of things to never do: most of them Claude was never going to do anyway. Cut.
What survived were the rules tied to a real, observed failure. The handful of things Claude actually gets wrong on my specific setup, with my specific tools, in a way no default would catch.
Eighteen lines.
Before and After
The change was immediate and obvious.
Sessions start lighter. Every conversation now begins with 18 lines of context instead of 500-plus, so I have more of the window available for the actual work before quality starts to slide.
Sessions stay sharp longer. Because I am starting further from the degradation cliff, I get more done before I feel the model drift. I restart fewer sessions. The mid-task “this is going sideways, start fresh” moment happens noticeably less often.
Sessions cost less. Every call carries a smaller instruction payload. Across a full day of work, that adds up to real money I was burning to send Claude things it already knew.
None of this required a clever trick. It required deleting things.
The Part I Did Not Expect
I assumed I was trading a little quality for speed and cost. Trimming the instructions felt like it should make Claude a bit less aligned with how I work.
The opposite happened.
The output got better.
When the file was long, every rule competed with 499 others for the model’s attention. The signal was buried in noise. Now there are 18 lines, and each one carries real weight. The rules that genuinely matter are no longer fighting for airtime against a paragraph about my preferred comment style.
Less instruction, applied more reliably, beat more instruction applied weakly. Boris was right, and I had to delete 96 percent of my own file to feel it.
What To Do This Week
Open your ~/.claude/CLAUDE.md. Then open the CLAUDE.md in your current project.
Go section by section. For each one, ask the only question that matters: “Did Claude actually make this mistake, or was I just being cautious?”
Cut everything in the second category. Be ruthless. The model already knows how to write good code. It does not need you to re-explain best practice. It needs the short list of things that are specific to you and that it genuinely gets wrong.
Then stop writing the file proactively. Add a line only the next time Claude makes a real mistake, and only the line that would have prevented it. Let the file earn every line through actual use.
Give it two weeks. I would bet on the same result I got: a shorter file, faster sessions, lower cost, and output that is better, not worse.
The theory is convincing on its own. But I needed to cut 500 lines to 18 before I actually believed it. Now I do.
This is the practical follow-up to Why the Creator of Claude Code Uses a 100-Line CLAUDE.md, which covers the philosophy behind the correction-log approach. For the wider picture on working this way, start with agentic engineering, and for more high-signal setup ideas see 32 Claude Code hacks that actually move the needle.
Get one practical AI workflow every week. No fluff. Just the systems, tools, and techniques that actually ship.