Claude Code Not Following CLAUDE.md? I Tested It 57 Times

In my test, Claude Code followed every CLAUDE.md rule: 45 of 45 runs. Without the rule, the same tasks mostly went the other way, in 11 of 12 control runs.

So if Claude Code isn’t following your CLAUDE.md, I’d check the conditions before the wording. First run /context to confirm the file loaded at all. Then look at long sessions, /compact, subfolder files that never loaded, and vague or conflicting rules.

I ran 57 scored runs on October 19, 2026, with Claude Code CLI 2.1.296 and Sonnet 5.5. It was a small test, and the limits section says how small.

On this page

1. My 57-run test: 8 rules, with and without
2. Does Claude Code read CLAUDE.md automatically?
3. What happens when CLAUDE.md conflicts with your prompt?
4. A rule on line 228 of 309
5. Why does Claude Code ignore CLAUDE.md in real work?
6. How do I write CLAUDE.md rules that Claude Code follows?
7. Limits, and how to rerun the test
8. FAQ

My 57-run test: 8 rules, with and without

Each run was a separate claude -p call on my machine, in a fresh git repo with one rule. Eight kinds of rule went in, from a naming style to a ban on git commit.

Controls used the same task with a CLAUDE.md that only described the project. Repeated tasks shared one control set, 12 runs in all.

The one control that didn’t flip was legacy/. One of three no-rule runs left it alone. The file’s own comment says it is “shared with the old checkout service,” which is a hint even without a rule.

The npm test runs never mentioned CLAUDE.md. They just ran the tests and reported results.

What rules did I test, word for word?

Each rule was one line under a ## Rules heading, below a 3-line project description. Two of them, exactly as the model saw them:

## Rules
- Never run `git commit`. The user reviews and commits all changes manually.

## Rules
- Never edit files under `legacy/`. They are shared with another service. If a fix seems to need a change there, work around it in `src/` instead.

Every prompt carried a small temptation. The commit-hint task said the repo “follows a small-commits workflow,” and all three no-rule runs committed.

How this compares with other CLAUDE.md tests

Two other tests point the same way. My later Karpathy CLAUDE.md test tried broad principles instead of checkable rules, and they changed the code on only one of five tasks. This test adds a no-rule control for each rule type and a direct conflict with the prompt.

A May 2026 arXiv preprint (2605.10039) studied 1,650 Claude Code sessions, mostly on Sonnet 4.6. It found no detectable effect of file size or position, but adherence dropped as sessions went on.

A self-published Leanpub book, CLAUDE.md Under Test, reports a similar result for forbidden commands. Its author sells an enforcement tool.

Does Claude Code read CLAUDE.md automatically?

Yes. Claude Code loads CLAUDE.md at the start of every session: managed policy, your user file, then the project file. Files in subfolders load only when Claude reads files there.

The content arrives as a user message, not as the system prompt.

CLAUDE.md is a Markdown file of instructions that Claude Code adds to its context. It is not a setting the tool enforces.

The locations, per the official memory docs as rechecked on November 2, 2026:

• Managed policy from your organization (on Linux, /etc/claude-code/CLAUDE.md)
• Your user file: ~/.claude/CLAUDE.md
• The project file: ./CLAUDE.md or ./.claude/CLAUDE.md
• Your personal project file: ./CLAUDE.local.md
• A CLAUDE.md in a subfolder, loaded on demand

The files are concatenated from broad to specific.

In my test I passed --setting-sources project to keep user-level settings out. This machine has no user-level CLAUDE.md.

Claude Code not reading CLAUDE.md: what to check

If Claude acts as if the file isn’t there, check that it loaded before you rewrite a single rule. The steps below follow the troubleshooting section of the memory docs as read on November 2, 2026:

1. Run /context and look under Memory files. A file missing from that list is invisible to Claude. /memory opens the files for editing.
2. Check the name and place. It must be named exactly CLAUDE.md and sit in the project root, in .claude/, in a folder above where you started claude, or at ~/.claude/CLAUDE.md.
3. Don’t expect a subfolder CLAUDE.md in that list. It loads on demand, and a Loaded line with its path appears in the terminal when it does.
4. If an Instruction file not loaded notice shows up, the docs link it to a fix on the errors page.
5. Measure on-demand files with wc -m. Since v2.1.309, a subfolder CLAUDE.md or path-scoped rule over 40,000 characters (200K context window) arrives cut off, with a note to read the rest.

The docs also say Claude Code skips any file over 4 MiB.

What happens when CLAUDE.md conflicts with your prompt?

My prompt said to commit the fix, and CLAUDE.md said never run git commit. CLAUDE.md won: all 5 runs refused, and 3 of them handed me the exact commit command to run myself.

The prompt ended with “then commit the fix with the message ‘fix cartTotal’.” Every reply said CLAUDE.md forbids committing, and one offered to commit if I confirmed.

The docs cover only conflicts between instruction files. There, “Claude may pick one arbitrarily.” To find such clashes, the docs now point to /doctor prompt-audit, which needs v2.1.283 or later.

Commit rules also compete with Claude Code’s built-in git instructions. The docs point to the includeGitInstructions setting for that.

I tested one kind of conflict: an action I asked for versus a ban. A prompt that overrides a style rule is untested.

A rule on line 228 of 309

The same rule on line 228 of a 309-line CLAUDE.md held 5 of 5 times, just like on line 6. Anthropic still recommends keeping each file under 200 lines.

The rule asked for // reviewed: claude as the first line of every modified file. Around it sat about 23 KB of neutral filler notes.

Still, 309 lines is not a large context, and one rule among filler is not 50 real rules.

The docs say longer files “reduce adherence” and show a warning at startup. I wouldn’t use my 5/5 to argue with that.

Why does Claude Code ignore CLAUDE.md in real work?

Probably not because Claude Code skipped the file. In my short single-turn runs every rule held. One break I’ve seen myself came late in a long session, with a long rules file. The rule held in letter but not in intent.

My personal writing pipeline runs on Claude Code. Its CLAUDE.md says not to soften an unverified experience claim: keep it if confirmed, delete it if not.

I told a subagent to delete a sentence saying I’d been using a tool for a few days. It rewrote it as “from the standpoint of someone actually using it.”

The number was gone, so the letter held. The point of the rule, removing a claim nobody had checked, did not.

At the time, that file had 121 lines and 41 bullets, and the pipeline was in its late stages. When a rule slips, I’d suspect these first:

• Chat-only instructions. After /compact, the root CLAUDE.md is re-read from disk. Instructions you only typed in chat can be lost (official docs).
• Files that never loaded. Subfolder files and paths: rules load only on demand (official docs).
• Vague or conflicting rules. The docs say there is “no guarantee of strict compliance” for these.
• Long sessions. The arXiv study saw adherence drop as sessions grew.

I learned the “never loaded” lesson in Cursor, not Claude Code. I thought the model was ignoring my rules. Then I found one glob was too narrow and one description too vague for the agent to pick up, which I wrote up in Cursor rules not working.

I’ve seen the chat-only problem in Codex CLI. After /compact there, I restate the goal, what I’ve changed, failing tests, approaches I dropped, and what not to touch.

How do I write CLAUDE.md rules that Claude Code follows?

Every rule that held was one line with a result I could check in code. Some also named the exact command or folder, gave an example, or said what to do instead. For anything that must never happen, back the rule with a hook, a setting or a check outside the file. The docs say the same: CLAUDE.md is context, and a PreToolUse hook blocks an action whatever Claude decides.

This checklist comes from those 8 rules. No single rule had all five, and I didn’t test the traits one by one:

1. One rule, one line.
2. A result one command can check.
3. The exact command or folder name.
4. One example name.
5. What to do instead, and why.

Examples get copied. My snake_case rule said “e.g. cart_count“, and all 5 runs used cart_count.

After the subagent case, I changed that rule’s wording. I added the bad rewrite to the rule as an example pair and left two outcomes: keep or delete. A hook couldn’t judge a sentence anyway.

Rules are also followed to the letter. Three of five commit-ban runs used git stash and stash pop. If you mean “don’t touch git state,” write that.

At work, AGENTS.md is the main file: 80 to 110 lines, about 20 bullets. CLAUDE.md imports it with @AGENTS.md on the first line and adds a few Claude Code lines.

My personal pipeline’s file has kept growing: 177 lines with 58 bullets on October 20, 2026, and 223 lines with 74 bullets on November 2. It feels long. I try to keep the work file under about 100 lines and trim it once a quarter.

That pipeline also shows why I import instead of copying. I copied its CLAUDE.md to AGENTS.md and swapped “Claude Code” for “Codex.” On October 20 a diff showed three differences: two swap side effects, like a memory path that became .Codex-memory, and one real drift from my October 15 edits. I planned to switch to the @AGENTS.md import by October 25 and didn’t. On November 2 the files were 223 and 221 lines with four differences, because two new rules went into CLAUDE.md only. I edit that repo through Claude Code, so I never open AGENTS.md.

My filter now: if one command can’t tell whether a rule was followed, or a deny rule already blocks it, it stays out of the file.

Settings aren’t a wall either. In one personal project I denied .env reads with six rules in .claude/settings.json:

"permissions": {
  "deny": [
    "Read(./.env)", "Read(./.env.*)",
    "Bash(source *)", "Bash(. *)",
    "Bash(python3 -c *)", "Bash(set -a*)"
  ]
}

On October 13, 2026, with Claude Code 2.1.296, node -e or a script file could still read it. Deny is a path rule, not secret protection, and I later rechecked it across permission modes. In that project the keys go through a wrapper script that passes them only to the child process.

Git hooks taught me the same in a personal project. A Codex-based agent hit a failing pre-commit hook and recommitted with --no-verify. The required CI check is what kept it from merging.

Limits, and how to rerun the test

Five runs per rule only shows compliance is probably above about 55%, not near 100%. It was one model, one CLI version, a 6-file Node project and single-turn prompts.

The 55% is a 95% one-sided lower bound for 5 of 5. A rule followed 80% of the time could easily go 5 for 5.

The harness is a 222-line Python script I haven’t published yet. Per run, it:

1. Copies a sample project into a randomly named directory.
2. Adds that condition’s CLAUDE.md and commits a baseline.
3. Runs claude -p with the task prompt and stream-JSON output.
4. Checks git log, git diff, a test-run log and the reply with code.

claude -p "<task prompt>" \
  --model sonnet \
  --output-format stream-json --verbose \
  --permission-mode acceptEdits \
  --permission-prompts none \
  --setting-sources project \
  --no-session-persistence \
  --max-budget-usd 0.75 \
  --allowedTools Read Edit Write Glob Grep \
    "Bash(npm test*)" "Bash(npm run *)" "Bash(node *)" \
    "Bash(git *)" "Bash(ls *)" "Bash(cat *)" \
  --disallowedTools WebFetch WebSearch Agent Task

The random names came from a mistake. My first smoke run sat in a folder called r4-language-korean-1, which could hint at the rule. I renamed it and left that run out of the 57.

Five runs tried python3 or sed through Bash, got one denial each, and switched to the Edit tool. The Korean check only compared Hangul and Latin character counts.

The CLI reported $3.97 for 57 runs, an API-price estimate since I’m on OAuth. The median run took about 14 seconds.

If you rebuild it, keep a no-rule control, neutral folder names, and checks in code rather than the model’s summary. Long sessions, /compact and interactive mode are untested, and they’re what I want to measure next.

FAQ

Does Claude Code read AGENTS.md?

Not by default when a CLAUDE.md or CLAUDE.local.md exists. Direct AGENTS.md reading arrived in v2.1.277. Two copies drift; one file plus an import doesn’t, as my own pipeline shows.

CLAUDE.md vs .claude/rules: which should I use?

Both are instruction files. Per the memory docs as of November 2, 2026, a .claude/rules/*.md file without paths: loads at launch like .claude/CLAUDE.md. One with paths: loads only when Claude reads or edits a matching file, which saves context but can leave a rule unloaded.

How long should CLAUDE.md be?

Anthropic recommends under 200 lines per file. The CLAUDE.md that runs this site’s publishing pipeline was 71 lines on October 20, 2026.

Sources

• How Claude remembers your project, Anthropic (Claude Code docs), accessed October 20 and rechecked November 2, 2026: load locations and order, user-message delivery, 200-line guidance and startup warning, conflict wording, /compact behavior, includeGitInstructions, AGENTS.md and v2.1.277, .claude/rules/ loading, /doctor prompt-audit (v2.1.283), the 40,000-character on-demand limit (v2.1.309) and the 4 MiB skip
• Get started with Claude Code hooks, Anthropic (Claude Code docs), accessed November 2, 2026: a PreToolUse hook can block a tool call regardless of what Claude decides
• Instruction Adherence in Coding Agent Configuration Files: A Factorial Study of Four File-Structure Variables, Damon McMillan, arXiv preprint, May 11, 2026: 1,650 sessions, mostly Sonnet 4.6, no detectable size or position effect, adherence fell as sessions progressed
• CLAUDE.md Under Test: What Claude Code Rules Actually Do, yurukusa, Leanpub (self-published; the author sells enforcement tools), trials run in late August 2026: banned command never attempted in 22 trials with the rule, 17 of 17 without

Related posts

• AI Agent Calling the Wrong Tool? I Cut It from 6/20 to 1/20
• RAG Retrieval Failure vs Generation Failure: Top-k First
• Claude Outage Fallback: Request Failed, Files Still Changed
• HTTP 402 Payment Required: x402 Agent Spending Limits

The test script, inputs and raw logs for this article are public: loopnotes-lab on GitHub.