A CLAUDE.md that grew by accretion stops working. Here's how to audit it, cut it down, and turn accumulated rules into instructions that reliably change output.
Every CLAUDE.md starts lean and drifts heavy. You add a rule when Claude gets something wrong. Then another. Six months later, you have 60 rules in a 3,000-word file and Claude's behavior is less consistent than when you started.
This isn't failure — it's the natural lifecycle. Optimization is the maintenance step most people skip.
You need to optimize when:
Read every rule in your CLAUDE.md and ask: has this been violated in the last 30 days? If the answer is no, the rule might be working — or it might be dead. Test by removing it temporarily and watching behavior.
Dead rules take up tokens without doing work. Every rule that doesn't change output is a rule that's making your file longer and your important rules less effective.
Every instruction written as preference is a candidate for rewriting or removal.
Weak patterns to find and eliminate:
Soft language doesn't fail loudly — it just quietly doesn't work. Rewrite every "try to" as a direct instruction or cut it.
Most CLAUDE.mds have 5–10 rules that are really the same rule written multiple times:
Be concise.
Don't write long paragraphs.
Avoid over-explaining.
Keep answers short.
Don't pad your response.
That's one rule (be concise) written five ways. Merge it:
Be concise: answers under 200 words unless I ask for more. No padding, no over-explanation.
One clear rule is easier for Claude to apply than five overlapping instructions.
The rules at the top of your CLAUDE.md get consistent application. The rules at the bottom are more like suggestions. If you have a rule that keeps getting violated, check where it is in the file — then move it up.
Priority order for your CLAUDE.md:
A description tells Claude what you value. A constraint tells Claude what to do. Most CLAUDE.mds have too many descriptions and not enough constraints.
Description: "I work with technical audiences who value precision."
Constraint: "Assume the reader knows what a mutex is. No analogies. No beginner framing."
The second one is actionable. The first one is context that Claude interprets — and may interpret differently than you intend.
Go through every descriptive paragraph in your file and ask: what specific behavior does this require? Write that behavior as an instruction. Cut the description.
Conflicting rules produce inconsistent behavior. Claude doesn't fail when it sees a conflict — it picks one rule and applies it, then picks the other one next time. The result looks like random variation.
Common conflict patterns:
If you genuinely need different behavior in different contexts, make the trigger explicit: "When I ask a technical question: assume expertise. When I ask a writing question: write for a general reader."
After rewriting your CLAUDE.md, start a new conversation — not a continuation. Give Claude a representative task for each major rule you changed. Evaluate the output before prompting anything.
Rules that worked in the old file may need adjustment in the new structure. The test is always: does this new conversation reflect what I wrote?
Some things commonly appear in CLAUDE.mds and consistently do nothing:
If a rule doesn't change what Claude does — if Claude would do it anyway — the rule wastes tokens.
How often should I optimize my CLAUDE.md?
When behavior starts drifting — Claude following some rules and not others, corrections repeating mid-conversation. For active projects, once a month is reasonable. For stable workflows, once a quarter.
Is there a tool to audit my CLAUDE.md?
CoworKit's Optimize tab will analyze your existing file and return a rewritten version with dead rules flagged, soft language replaced, and conflicts resolved. Paste in, get a tightened version back. Free, no signup.
Can I just start over with a fresh CLAUDE.md?
Sometimes that's faster. If your file has grown beyond 2,500 tokens and behavior is inconsistent, starting fresh with a template and adding back only what you know works may be more efficient than auditing the existing file.
What's the right length after optimization?
Under 1,000 tokens for most workflows. Under 1,500 for complex ones. If you can't get it below 1,500, you probably have rules that can still be cut or merged.
If your CLAUDE.md has grown unwieldy, the Optimize tab will audit it for you — returning a rewritten version with dead rules removed, soft language replaced with constraints, and the file trimmed to what actually changes behavior. Paste in, get back a lean file. Free, no signup.
Practical guides and prompt patterns — no fluff, unsubscribe any time.