Direct answer

Why is Claude Code not following my CLAUDE.md?

The file may not have loaded from the path you expect.
Critical text may sit beyond a runtime-specific loading boundary.
The rules may be conflicting, incomplete, or impossible to verify.
Check loading first, then inspect the rules themselves.

Diagnose the causes in this order

Do not begin by rewriting the whole file. Each step below separates a loading problem from a rule-quality problem and gives you evidence that changes the next action.

Claude Code is reading a different path, or the session never loaded this file

A correct-looking file proves only what is on disk. It does not prove what a running session received.

Check

pwd -P
find .. -name CLAUDE.md -type f -print
ls -l CLAUDE.md
shasum -a 256 CLAUDE.md

Then start a new read-only session from the intended project directory and ask:

List the instruction files you loaded, then state the five most important rules from CLAUDE.md. Do not edit files.

Fix

Move or link the rule file to the path your runtime actually loads, start a fresh session, and repeat the recitation check. Record the verified path and hash. Do not treat an existing chat as proof that a changed file was reloaded.

The file may be larger than the runtime will combine or load

Loading and truncation behavior is runtime-specific. The browser auditor uses 32 KiB only as a static reference value, not as a verified universal Claude Code limit.

Check

wc -c CLAUDE.md
sed -n '1,80p' CLAUDE.md
tail -n 80 CLAUDE.md

Compare the byte count with the current runtime documentation or configuration you actually use. In the fresh-session check, ask for a rule that appears near the end of the file.

Fix

Keep critical rules near the beginning, remove repeated prose, and split reference material away from the operating contract when your runtime supports that structure. If the runtime exposes a documented size setting, configure it deliberately and re-run the fresh-session check.

The file has headings or policy claims but no executable instruction

A heading with no body gives the agent nothing actionable. A sentence such as “checks are automatic” can describe a control that does not exist.

Check

grep -nE '^#{1,6}[[:space:]]+' CLAUDE.md
grep -nEi '\b(always|automatically|now)\b|\b(is|are|gets?) (checked|verified|validated|enforced)\b' CLAUDE.md
grep -rn '<rule-id>' automation/ scripts/ tests/

For every important heading, inspect the lines below it. For every claim about enforcement, identify the script, hook, test, or human step that performs it.

Fix

Write a trigger, a concrete action, and an observable result. Replace present-tense claims with checkable commands or name the manual owner. If no execution path exists, describe the text honestly as guidance rather than enforcement.

The rules do not define verification or a terminal state

Without a reproducible check, “done” is self-certification. The rule file needs evidence and explicit outcomes.

Check

grep -nEi '\b(verify|validate|test|lint|typecheck|check|exit code)\b' CLAUDE.md
grep -nEi 'DONE:|FAILED:|HUMAN_ACTION_REQUIRED:|acceptance criteria|completion (criteria|marker|means)' CLAUDE.md

Fix

Name the exact command or observable check that must run after an edit, require its exit code or result, and define what completed, failed, and human-blocked work look like. Map each important rule to evidence.

Duplicate, conflicting, or hollow checks make compliance ambiguous

Repeated rules drift. Strong positive and negative directives can overlap. Placeholder values can satisfy an existence check without supplying useful evidence.

Check

sort CLAUDE.md | uniq -d
grep -nEi '\b(always|must|required to|never|must not|do not)\b' CLAUDE.md
grep -nE '\b(N/A|TODO|TBD|UNKNOWN)\b|=[[:space:]]*[?]' CLAUDE.md

Fix

Keep one canonical version of each rule. Add conditions and precedence where directives overlap. Validate the shape of required values instead of accepting a placeholder; for example, require a numeric value or a terminal error state.

The file changed after you verified it

Rules files are production configuration. An unrelated edit can silently remove a rule while the task still appears successful.

Check

git status --short -- CLAUDE.md
git diff -- CLAUDE.md
shasum -a 256 CLAUDE.md

Fix

Record the hash after a verified edit and compare it after any session that touched files. Review unexpected diffs before trusting later behavior, then repeat the fresh read-only recitation check.

Run the static checks together

To run these checks in one paste, use the CLAUDE.md Auditor. It checks ten static patterns, including size risk, empty sections, missing verification, missing completion criteria, unverifiable control claims, unsafe prohibitions, generic tool markers, duplicate instructions, contradictions, and placeholders. It cannot prove runtime loading, so keep the fresh-session check in your diagnosis.

Short answers

Why is Claude Code ignoring my CLAUDE.md?

The file may not have loaded from the path you expect, its critical text may sit beyond a runtime-specific loading boundary, or the rules may be conflicting, incomplete, or impossible to verify. Check loading first, then inspect the rules themselves.

Can a static audit prove that Claude Code loaded the file?

No. Static analysis can find risky text patterns, but runtime loading requires a fresh-session check against the exact file path.

Should I put critical CLAUDE.md rules near the top?

Yes. Keeping critical rules early reduces the impact of runtime-specific truncation and makes the operating contract easier to inspect.