Guide
Claude Code ignoring your CLAUDE.md: causes and how to check
CLAUDE.md is context, not enforced configuration: Claude reads it and tries to follow it, without a guarantee. When an instruction is ignored, the cause is usually that the file did not load, or that the instruction is vague, contradicted or too far down a long file.
Why does Claude Code ignore CLAUDE.md?
Anthropic's documentation is explicit on this point. The content of CLAUDE.md is delivered as a user message after the system prompt, and strict compliance is not guaranteed, especially for vague or conflicting instructions. An instruction that must hold every time therefore needs a different mechanism, described below.
Did the file load?
This is the first thing to check, because no wording helps a file Claude cannot see.
- Run
/contextand look under Memory files. Files that should load at launch are listed there. - A
CLAUDE.mdin a subdirectory will not be listed, because it loads on demand, when Claude works with a file in that folder. ALoadedline with its path appears in the terminal when it does. - The
InstructionsLoadedhook can log which instruction files load, when and why, which helps with path-scoped rules and subdirectory files.
Is the instruction specific enough?
Instructions work best when they are concrete enough to verify.
| Vague | Specific |
|---|---|
| Format code properly | Use 2-space indentation |
| Test your changes | Run npm test before committing |
| Keep files organized | API handlers live in src/api/handlers/ |
Do two instructions disagree?
If two files give different guidance for the same behaviour, Claude may pick one arbitrarily. Conflicts are worth looking for across CLAUDE.md files, nested files in subfolders and .claude/rules/.
An instruction can also compete with guidance Claude Code adds itself. For commit and pull request rules, the documentation recommends turning off the built-in instructions with the includeGitInstructions setting and setting the attribution text with attribution.
Is the file too long?
The documentation recommends under 200 lines per file, because longer files consume more context and reduce adherence. Instructions that matter for only part of the codebase can move to path-scoped rules, which load only when Claude works with matching files. Splitting a file with @path imports helps organisation but does not reduce context, since imported files load with the file that imports them.
On-demand files have a further limit. A subdirectory CLAUDE.md or an on-demand rules file over the per-file limit reaches Claude only in part, so the later instructions are absent until Claude reads the rest. For a 200K context window the limit is 40,000 characters; wc -m prints the count on macOS and Linux.
What if an instruction must always hold?
Use a hook. Hooks run as shell commands at fixed points in the session and apply regardless of what Claude decides, so they suit anything that has to happen before every commit or after every edit. To block an action outright, the documentation points to a PreToolUse hook.
For a whole file that should act at system prompt level, --append-system-prompt is available at launch, though it suits scripts better than interactive use.
Why does Claude Code not read AGENTS.md?
By default Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above it; a personal ~/.claude/CLAUDE.md does not count. It also requires v2.1.277 or later. To check, run /memory and look for its path. A CLAUDE.md that contains the line @AGENTS.md makes both files apply.
Sources, checked on
- Claude Code docs: Troubleshoot memory issues
- Claude Code docs: Write effective instructions
- Claude Code docs: Hooks
Where Coredence fits
A file also stops being followed when it stops being true, and instructions written by hand tend to drift from how you actually work. Coredence reads your own sessions, commits and notes and consolidates them into memories tied to the traces they grew from. When your behaviour contradicts a memory, it asks you which is right instead of overwriting it. The result reaches Claude Code as a skill, loaded in every session.
Coredence runs on macOS 14 or later (Apple silicon) and Windows 10 or later, with no Coredence account. Consolidation needs a model, and you choose it: your Claude Code subscription, your own API key, or a local model through Ollama. On those paths Coredence itself is free to use. It is not open source, and its own paid plans are not on sale yet.
Try it in your browser