Ten rules for a CLAUDE.md that actually gets read, stays effective, and doesn't degrade over time.
A CLAUDE.md doesn't fail at creation — it fails gradually. You add sections when Claude gets something wrong. You add more sections when it gets something else wrong. Six months later, you have a 3,000-word file with 40 rules that contradict each other, and Claude's behavior is worse than before.
Good CLAUDE.md hygiene prevents this. Here are the ten rules that matter.
Not a soft limit — a hard constraint on reliable behavior. Claude loads CLAUDE.md as context before your conversation. Files over 2,000 tokens start to cause position bias: rules near the end get proportionally less attention than rules near the top.
If your file is long, cut it. Not by removing rules — by making each rule shorter. "No bullet points unless I ask. No hedging. Active voice only." is three rules in one line.
The first thing your CLAUDE.md should tell Claude is what you make and who it's for. Not your career history. Not company context. Not a vision statement.
"I'm a freelance developer writing Node.js services for fintech clients. My outputs are production code, technical documentation, and client-facing summaries." That's a brief Claude can use from word one.
Lines that begin with # in a CLAUDE.md get extra weight. Use this for your most important constraints — the ones that, if ignored, break everything. Don't use it for everything or it loses effect.
# NEVER use async/await in synchronous contexts
# Database queries go in /db/ — never in route handlers
Descriptions tell Claude what you do. Constraints tell Claude what it must and must not do. Most CLAUDE.mds are too heavy on description.
Description (weak): "I write for a technical audience that values precision."
Constraint (strong): "No analogies for technical concepts. If the reader doesn't know what a mutex is, they're not your audience. Assume they do."
Constraints change behavior. Descriptions suggest it.
Compound rules dilute each other. "Be concise, use simple language, and avoid jargon unless necessary" is three rules with a loophole. Write them separately:
Be concise: no sentence over 25 words.
No jargon without a definition on first use.
Avoid passive voice.
Claude applies rules sequentially. Separate rules get separate attention.
The most powerful CLAUDE.md line is often: "Don't do X." Claude defaults to conservative, thorough, hedged responses — because that's what most users reward. If you don't want that, say so explicitly.
"Don't hedge." "Don't add a disclaimer at the end." "Don't suggest I consult a professional." "Don't ask for clarification — make a choice and tell me what you chose." These instructions work because they counter Claude's trained defaults directly.
If you do the same task repeatedly — debugging a specific codebase, drafting a specific report format, reviewing a specific type of document — include a section that names it and gives the brief for it.
Don't make Claude re-discover context on every conversation. "When I say 'review this PR', check for: missing error handling, untested edge cases, and any call into the payments module without a transaction wrapper." That instruction, written once, holds forever.
Claude Code reads CLAUDE.md files at multiple directory levels. The root file sets project-wide rules. Sub-directory files handle module-specific conventions.
Use this for monorepos where the backend, frontend, and shared library have different standards. Your root CLAUDE.md sets the defaults; /backend/CLAUDE.md overrides the sections that don't apply.
A CLAUDE.md that grows and never shrinks is collecting dead rules. Every rule you add should stay only as long as it's needed.
When you notice Claude respecting a constraint perfectly and consistently, the instruction might be internalized — or it might just be working. Either way, test removing it. If behavior holds, the rule was redundant. If behavior degrades, put it back.
Treat the file like code: if it's not earning its lines, it gets removed.
After adding a rule, start a new conversation — not a continuation of an existing one. Give Claude a task that should trigger the new rule. Evaluate the output before prompting anything.
If the rule isn't applied, rewrite it to be more direct. If it's applied but wrong, clarify. Most rules that "don't work" are either buried too deep in the file or phrased as suggestion rather than instruction.
How long is too long?
1,500 tokens is the working limit for reliable recall across the full file. That's roughly 1,100 words or 5–6 substantive sections. If you're over this, cut — don't just prioritize.
Does section order matter?
Yes. Claude reads CLAUDE.md top to bottom, and position bias applies: earlier sections get more consistent application. Put your highest-priority rules first. Don't bury the "always do X" instruction on page 3.
Can I use markdown formatting inside CLAUDE.md?
Yes, and you should. Headers, bold text, and code blocks all work. The # shortcut for emphasis is the most important formatting choice — use it for constraints that cannot be violated.
What happens if two rules conflict?
Claude tries to satisfy both, usually by applying the later rule as a modifier. If you have genuinely conflicting rules, one of them is wrong. Find it and remove it.
Is there a CLAUDE.md linter?
Not a dedicated one. CoworKit's Optimize tab analyzes your existing CLAUDE.md and flags redundant rules, vague instructions, and structural issues. Paste in, get a tightened rewrite.
If your CLAUDE.md has grown bloated or inconsistent, the Optimize tab at CoworKit will audit it and return a version with conflicting rules resolved, vague language replaced with constraints, and the file trimmed to what actually changes behavior. Free, no signup.
Practical guides and prompt patterns — no fluff, unsubscribe any time.