Most developers building with Claude Code have a CLAUDE.md that runs 500, 800, sometimes over 1,000 lines. Detailed instructions. Coding standards. Architecture explanations. Formatting rules. Edge case handling. The works.
Boris Cherny, the engineer who actually built Claude Code at Anthropic, uses about 100 lines.
That gap is not an accident. It’s a philosophy.
What Most People Get Wrong About CLAUDE.md
The common assumption is that more instruction equals better output. Feed Claude enough context about how you work, and it will behave exactly how you want.
It sounds logical. It’s mostly wrong.
Claude already knows how to write code. It knows design patterns, test conventions, error handling strategies, and most language-specific best practices. Writing 800 lines to tell it things it already knows is not instruction. It’s noise. If you want a full breakdown of what Claude already handles well, our Claude Code best practices guide covers it in detail.
Noise competes with signal. The more irrelevant content Claude has to process, the harder it is for the relevant rules to surface at the right moment.
Boris’s philosophy flips the model entirely.
His Actual Approach: A Correction Log, Not a Manual
Here is the key quote from Boris’s own documentation: “Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time.”
Read that carefully. He is not anticipating problems. He is recording observed mistakes.
CLAUDE.md is not a proactive instruction set. It is an institutional memory of specific failures. The file grows only when Claude actually gets something wrong, and only with the rule that would have prevented that specific mistake.
His setup is, in his words, “surprisingly vanilla. Claude Code works great out of the box, so I personally don’t customize it much.”
That is a remarkable statement from the person who built the tool.
What His 100 Lines Actually Contains
Boris’s CLAUDE.md is built around three core principles:
Simplicity first. Make every change as small and targeted as possible. Minimal code impact.
No shortcuts. Find root causes. No temporary fixes.
Minimal footprint. Changes should only touch what is necessary to avoid introducing new bugs.
Beyond those principles, the file contains workflow-specific rules. Things like: use bun, not npm. Run typecheck, then tests, then lint before opening a PR. Specific command sequences that reflect how his team actually works.
Notice what is absent. No guidance on token budgets. No error handling philosophy. No communication templates. No conflict resolution procedures between competing principles. No explanation of the codebase architecture.
All the things most people include. None of them are there.
Why Less Instruction Produces Better Results
Three reasons this works.
Claude already has strong defaults. The model has been trained on vast amounts of code and follows standard best practices without being told. Most CLAUDE.md files are re-explaining things Claude already does well.
Specificity beats volume. A rule like “use bun not npm” is actionable. A 20-line section on code quality philosophy is not. The shorter your CLAUDE.md, the more weight each rule carries. For more examples of high-signal Claude instructions, see 32 Claude Code hacks that actually move the needle.
Reactive beats proactive. You cannot predict in advance every mistake Claude will make in your specific codebase with your specific stack. Boris does not try to. He waits for a mistake to happen, then adds the precise rule that would have prevented it. The file earns its lines.
The Right Mental Model
Think of CLAUDE.md not as a configuration file but as a living correction log.
Every line should answer the question: “What specific mistake did Claude make that this rule prevents?”
If you cannot answer that for a line in your file, the line probably should not be there.
Start with 20 lines. Add when Claude gets something wrong. Delete when a rule stops being relevant. Let the file evolve from actual usage.
Boris’s 100 lines represents years of real-world feedback compressed into the minimum set of rules that actually change Claude’s behavior in meaningful ways.
Your 1,000 lines probably represents a lot of anticipation that Claude does not need.
What to Do This Week
Open your CLAUDE.md. For each section, ask: “Did Claude actually make this mistake, or was I just being cautious?”
Cut everything in the second category. Add a rule only next time Claude gets something wrong.
Give it two weeks. You will almost certainly end up with a shorter file and better results.
That is the counter-intuitive truth Boris figured out by building the thing: Claude Code works best when you get out of its way.
If you want to go deeper on how top developers set up their entire Claude Code environment, the full setup guide is a good next read. And if you are still thinking about how AI fits into your broader workflow, start with agentic engineering.
Get one practical AI workflow every week. No fluff. Just the systems, tools, and techniques that actually ship.