Why does Claude ignore my CLAUDE.md?

Is CLAUDE.md enforced at all?

No, and Anthropic says so plainly. The memory docs state that Claude “treats them as context, not enforced configuration.” The troubleshooting section is more exact: CLAUDE.md content “is delivered as a user message after the system prompt, not as part of the system prompt itself,” and “there's no guarantee of strict compliance, especially for vague or conflicting instructions.”

So a line like “NEVER commit unless asked” is a request. Issue #34774 is a user whose CLAUDE.md said exactly that, and whose session committed anyway. The tracker has several more like it (#47101, #95718). The pattern in all of them is the same: the rule loaded, Claude could recite it, and a competing pressure in the task won.

Is my CLAUDE.md even loaded?

Check this before you rewrite anything. Run /context and look under Memory files. If the file is not listed, Claude cannot see it. The common ways a file goes missing:

• It lives in a subdirectory. Files above the working directory load at launch. A CLAUDE.md in a subdirectory loads only when Claude reads a file in that directory.
• It is a path-scoped rule. A rule in .claude/rules/ with paths: frontmatter “trigger[s] when Claude reads files matching the pattern, not on every tool use.” Issue #95083 (opened 2026-09-17) reports that reading or editing the file through Bash (cat, sed -i) does not load the rule at all.
• The frontmatter does not parse. Broken YAML makes Claude Code load the rule as if it had no paths. claude --debug shows the error.
• It was compacted away. The project root CLAUDE.md is re-read after /compact. Nested files and path-scoped rules come back only when Claude next reads a file they apply to. Instructions you only typed in chat do not come back at all.
• It is an AGENTS.md. By default Claude reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above. See does Claude Code read AGENTS.md.

For the stubborn cases, the docs suggest an InstructionsLoaded hook, which logs which instruction files loaded, when, and why.

Why does Claude follow the rule at first and then stop?

Because compliance falls as the session gets longer. Damon McMillan's arXiv:2605.10039 ran 1,650 Claude Code CLI sessions and varied four things about the instruction file: its size, where an instruction sat, how the files were laid out, and contradictions in adjacent files. None produced a detectable effect on compliance. What did show up, and was not a planned hypothesis, is time: each additional function the agent wrote in a session came with about 5.6 percent lower odds of following the rule.

Two practical readings. Moving a rule to the top of the file, or bolding it, is unlikely to save it. And a fresh session for a fresh task is a real fix, not a superstition.

Claude Code ignores instructions when two rules disagree

Every CLAUDE.md on the path is concatenated, not overridden. Your ~/.claude/CLAUDE.md, the project file, a nested file, and every unscoped rule all land in the same context. The docs are blunt about the result: “if two rules contradict each other, Claude may pick one arbitrarily.” A user rule and a project rule that conflict get the same treatment.

Anthropic's July post on context engineering for Claude 5 models names the cost: with overlapping and conflicting messages, “Claude must think more carefully” before deciding what to do. A contradiction is not neutral. It spends reasoning on your instructions instead of your task.

CLAUDE.md not working after a refactor

A rule that names src/billing/webhooks/ after someone moved it to payments/webhooks/ is now a rule that disagrees with the code Claude can see. The code wins, usually, and it looks like Claude ignored you. The same goes for a decision your team reversed in #eng-payments last month while the old one still sits in the file. Nothing in a markdown file expires, so these pile up. That is the subject of context rot and stale rules.

Is my CLAUDE.md too long?

Possibly. The docs target under 200 lines per file and say longer files “consume more context and reduce adherence.” The mechanism is ordinary: a rule about CSS is a distractor during a webhook change, and Chroma's context rot study found that even one distractor lowers accuracy. Every rule that does not apply to this task makes the ones that do a little harder to act on. More on sizing in how long should CLAUDE.md be.

Causes, checks, and fixes

How do I make Claude always follow a rule?

You move it out of the prompt. The docs draw the line themselves: for anything that must hold every time, use a hook, because hooks “execute as shell commands at fixed lifecycle events and apply regardless of what Claude decides to do.” A PreToolUse hook that exits with code 2 blocks the tool call and hands its stderr back to Claude:

# .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/no-force-push.sh" }
        ]
      }
    ]
  }
}

# .claude/hooks/no-force-push.sh
#!/bin/sh
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -qE 'git push.*(--force|[[:space:]]-f([[:space:]]|$))'; then
  echo "Force push is off in this repo. Open a PR instead." >&2
  exit 2
fi
exit 0

For a hard allow or deny on a command, the hooks guide points to permissions.deny in settings, since a hook's own pattern matching is best effort. Either way, the rule now lives somewhere Claude cannot talk its way past.

Everything else stays prose, and prose works best when there is little of it and all of it applies. Three habits carry most of the weight: write rules concrete enough to check (“Run npm test before committing”, not “test your changes”), scope rules to the paths they are about, and delete a rule the day it stops being true. Which mechanism suits which rule is laid out in CLAUDE.md vs skills vs hooks.

How do I know if Claude used my CLAUDE.md?

You mostly do not. A file loads on every turn, so “it was in context” tells you nothing. Asking Claude to name the rules it applied gets you a citation, which is useful evidence: the rule was in play. It is not proof the rule was obeyed, and an uncited rule may still have shaped the answer. Two counts per rule, how often it was sent and how often an answer referred back to it, are the honest version. That is the argument of served vs cited.