CLAUDE.md is loaded as context, not as a contract. Here's the actual diagnostic tree for every failure mode — with rewrites you can paste in.
CLAUDE.md is not a locked contract. It's a piece of context that Claude reads and then uses — or doesn't, depending on how the rest of the conversation plays out. When it stops working, there's almost always a specific reason. Here's how to diagnose it.
The most common cause. Claude has finite attention, and within a long context window, position matters. Instructions near the top of a file get more consistent application than instructions near the bottom.
There's no hard cutoff, but reliability degrades noticeably above 2,000 tokens (roughly 1,500 words). If your CLAUDE.md is longer than that, rules near the end are effectively optional.
Fix: Cut the file. Don't hide instructions — remove them. If a rule isn't worth keeping at the top of the file, it may not be worth keeping at all. Target 1,000–1,500 tokens for reliable coverage.
"I prefer concise answers" is a soft signal. "Answers under 150 words unless I ask for more" is an instruction. Claude will honor the second one more consistently than the first.
Most CLAUDE.mds are full of soft language: "try to," "ideally," "when possible." Claude reads these as suggestions and weighs them against other signals — including what it thinks you probably want based on the task. Hard constraints override this.
Fix: Rewrite soft language as direct instructions.
This one surprises people. If Claude makes a long, thorough response and you respond "great, now expand on that" — you've just told Claude that long responses are what you want. Conversational signals override static context signals.
Fix: If Claude starts drifting from your CLAUDE.md rules during a long conversation, a reset prompt works: "Stick to the constraints in my CLAUDE.md. [rule here]. Continue." Don't restart the conversation — just recalibrate.
Conflicting rules produce unpredictable behavior. "Be direct" and "be thorough" conflict. "No hedging" and "always acknowledge uncertainty" conflict. Claude doesn't throw an error — it picks one and applies it inconsistently.
Fix: Audit your file for rules that could be read as opposing. Pick one side of each conflict and remove the other. If both rules are genuinely needed for different tasks, make the context explicit: "When debugging: be direct and brief. When explaining concepts: be thorough, acknowledge uncertainty."
Lines starting with # in a CLAUDE.md get extra weight. That's useful — when used sparingly. If every rule starts with #, none of them get special treatment. The signal loses meaning.
Fix: Reserve # for the two or three rules that absolutely cannot be broken. "# Never modify the payments module directly" earns its emphasis. "# Write clean code" does not.
Claude Code looks for CLAUDE.md at the project root and in parent directories relative to the files you're editing. If you're working in a subdirectory and the CLAUDE.md is in a sibling directory, it may not be in scope.
Fix: Place the primary CLAUDE.md at the repository root. For subdirectory-specific rules, create nested CLAUDE.mds in those directories. Claude Code will read both.
| Symptom | Most likely cause | Fix |
|---|---|---|
| Rules applied sometimes, not always | File too long, position bias | Cut to under 1,500 tokens |
| Rules ignored entirely in one tab, respected in another | Per-tab or per-session reset | Check file location; recalibrate mid-session |
| Claude applies one rule but ignores another | Rule conflict | Audit for contradictions |
| "Soft" instructions (tone, hedging) not applied | Language too weak | Rewrite as hard constraints |
| Rules applied early in conversation, then drift | Conversational override | Use reset prompt mid-session |
Can I verify that Claude has read my CLAUDE.md?
In Claude Code, run /context — it shows what's loaded. If your CLAUDE.md isn't listed, check the file path. If it is listed, the issue is instruction quality or position bias, not loading.
Does CLAUDE.md work in Claude.ai (web)?
In Projects, yes — the project system prompt serves the same function as CLAUDE.md. In individual conversations without a project, you'd need to paste your context manually.
What's the difference between a Project instruction and CLAUDE.md?
Claude.ai Projects use a system-level instruction you set once; CLAUDE.md is a file Claude Code reads from your filesystem. Both achieve the same goal — persistent context — but the mechanism differs. Rules that work in one usually work in both.
If I update my CLAUDE.md, does Claude pick it up immediately?
In Claude Code, yes — it's re-read on each conversation start. In a running conversation, changes won't take effect until you start a new one.
If your CLAUDE.md isn't changing Claude's behavior, the Optimize tab can audit it — flagging vague instructions, rule conflicts, and structural issues that reduce effectiveness. Paste in, get a rewrite. Free, no signup.
Practical guides and prompt patterns — no fluff, unsubscribe any time.