You wrote a careful CLAUDE.md for the repo — coding standards, test commands, deploy notes, the lot. Claude Code starts a new session and immediately violates half of it: wrong package manager, wrong test command, edits a file you explicitly marked as generated. Often the problem is not that Claude is “ignoring” the rules — the file never reached the context at all.
Fastest fix: in a live session, run /memory. As of June 2026 this lists every CLAUDE.md, CLAUDE.local.md, and rules file actually loaded for the session. If your project file is not in that list, Claude cannot see it — and you have a path, casing, or working-directory problem, not a rules problem. Fix that first, before you touch the wording of any rule.
One important nuance, straight from Anthropic’s docs: CLAUDE.md is delivered as a user message after the system prompt. Claude reads it and tries to follow it, but it is context, not enforced configuration. So there are two distinct failures here, and they have different fixes:
- The file did not load (this article’s main focus): path, casing, working directory, exclusion, or a subagent that skips it. Diagnose with
/memory. - The file loaded but Claude still drifts: vague or conflicting instructions, or an action that must be enforced. Fix with sharper wording, or move it to a hook for hard enforcement (if hooks themselves are not firing, see Claude Code settings.json not loading).
Common causes
Ordered by frequency in real deployments.
1. Launched from the wrong working directory
Claude Code reads CLAUDE.md by walking up the directory tree from your current working directory to the filesystem root, reading every CLAUDE.md and CLAUDE.local.md along the way. Files in subdirectories below your cwd are not loaded at launch — they load on demand only when Claude reads a file in that subtree. So if you launch from ~/projects instead of ~/projects/myrepo, the per-project file below you is never pulled in at startup.
How to spot it: pwd before the claude invocation does not match the directory containing CLAUDE.md, or you ran claude in a parent folder with several repos under it.
2. Wrong filename or casing
The file must be exactly CLAUDE.md — uppercase, .md extension. Claude.md, claude.md, CLAUDE.MD, or CLAUDE.markdown are all ignored on case-sensitive filesystems (Linux, most CI). macOS default APFS is case-insensitive, so it works locally and fails in CI.
How to spot it: ls -la CLAUDE.md shows nothing while ls -la | grep -i claude shows the file under a different casing.
3. File is in a location Claude does not load
A project CLAUDE.md can live in two places: ./CLAUDE.md at the repo root, or ./.claude/CLAUDE.md. Both are valid. But a file in docs/CLAUDE.md or any other subdirectory only loads when Claude reads a file in that directory — not at session start. People who move the file “to keep the root clean” often break startup loading.
How to spot it: /memory does not list your file, and it is not at the repo root or in .claude/.
4. The file is being excluded
In monorepos, the claudeMdExcludes setting (in .claude/settings.json, .claude/settings.local.json, or a managed policy) skips specific CLAUDE.md files by path or glob. A teammate’s overly broad pattern like **/CLAUDE.md can silently drop yours. Separately, files loaded via --add-dir are not read unless you set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.
How to spot it: /memory skips a file that clearly exists at a valid path; check claudeMdExcludes in every settings layer.
5. Imports (@path) not resolved
CLAUDE.md supports @path/to/file.md imports, expanded into context at launch. Three gotchas, all current as of June 2026:
- Relative paths resolve relative to the file containing the import, not your working directory.
- Imports inside Markdown code blocks or inline code spans are not evaluated (by design, to avoid collisions). If you wrapped
@docs/x.mdin backticks, it is treated as literal text. - Max import depth is four hops. Files imported beyond that are not pulled in.
- The first time a project uses an external import (e.g.
@~/.claude/...), Claude shows an approval dialog. If you declined once, the imports stay disabled and the dialog never reappears.
How to spot it: your CLAUDE.md is short and mostly @-imports; Claude only knows the literal CLAUDE.md text, not the imported content.
6. Conflicting instructions across layers (not “masking”)
This is the most-misunderstood cause. Global ~/.claude/CLAUDE.md, project CLAUDE.md, and any managed-policy file are not override-vs-overridden — they are all concatenated into context. Load order runs from broadest to most specific (managed policy, then user, then project), and within a directory CLAUDE.local.md is appended after CLAUDE.md, so the project file is read last and tends to win. But if two layers state contradictory rules (“always use yarn” globally vs “use pnpm” in the project), Claude may pick one arbitrarily — it is not guaranteed to honor the more specific one.
Two layers that genuinely take priority over your project file:
- Managed policy
CLAUDE.md(macOS/Library/Application Support/ClaudeCode/CLAUDE.md, Linux/WSL/etc/claude-code/CLAUDE.md, WindowsC:\Program Files\ClaudeCode\CLAUDE.md, or theclaudeMdkey in managed settings). It loads first and cannot be excluded. On a company-managed machine this can override your project intent.
How to spot it: /memory lists both files; Claude’s behavior matches a contradicting directive in another layer. Look for the same key (package manager, commit style) defined in two places.
7. Subagents that skip CLAUDE.md
When the main agent spawns a subagent, context handling depends on the subagent type. As of June 2026, the built-in Explore and Plan subagents deliberately skip CLAUDE.md and git status for speed; most other built-in and custom subagents load it. There is also an open report (anthropics/claude-code #29423) that some Task-tool subagents do not pick up project CLAUDE.md or .claude/rules/. Net effect: a subagent run can ignore project rules even though the main agent honored them.
How to spot it: direct prompts follow CLAUDE.md; prompts that dispatch a subagent (“explore the codebase and plan X”) do not.
Before you start
- Confirm the cwd you launched Claude Code from (
pwd). - Note whether the issue is on the main agent, a subagent, or both.
- Capture one concrete instruction in
CLAUDE.mdthat is being violated — you need a deterministic test case. - Check whether the file is in version control (
git ls-files CLAUDE.md). - Run
claude --version(auto-memory features require v2.1.59 or later, and command names move between versions).
Step-by-step fix
Ordered by how often each one is the actual fix.
Step 1: Run /memory — see exactly what loaded
In the session, type:
/memoryThis lists every loaded CLAUDE.md, CLAUDE.local.md, and rules file, lets you toggle auto memory, and opens any file in your editor. This single command resolves most cases:
What /memory shows | What it means | Go to |
|---|---|---|
| Your project file is not listed | It never loaded — path/casing/cwd/exclusion | Steps 2-4 |
| Your file is listed, plus a conflicting one | Contradiction across layers | Step 5 |
| Listed, but content is shorter than the file | An @-import or nested file did not resolve | Step 6 |
| Listed and correct, but Claude still drifts | Loading is fine — it is a rules/enforcement problem | Step 7 |
You can also ask Claude directly to print the first 200 characters of the loaded CLAUDE.md verbatim and compare to your file. For ongoing diagnosis, the InstructionsLoaded hook logs exactly which instruction files load, when, and why.
Step 2: Fix cwd and relaunch
Exit, cd into the repo root, relaunch:
cd ~/projects/myrepo
ls CLAUDE.md # must exist here (or .claude/CLAUDE.md)
claudeIf you launch through a wrapper (tmux, VS Code task), confirm that wrapper’s cwd, not your terminal’s.
Step 3: Normalize the filename
git mv claude.md CLAUDE.mdOn macOS the case-only rename may fail because the filesystem treats the names as identical; rename via a temp name:
git mv claude.md tmp-claude && git mv tmp-claude CLAUDE.mdCommit the rename so CI (case-sensitive) sees the right name.
Step 4: Move the file to a loaded location / check exclusions
Put CLAUDE.md at the repo root or in .claude/. If /memory still skips it, search every settings layer for an exclusion:
grep -r "claudeMdExcludes" .claude/ ~/.claude/Remove or narrow any glob that matches your file. Remember managed-policy files cannot be excluded.
Step 5: Resolve cross-layer conflicts
Open ~/.claude/CLAUDE.md and remove directives that should be project-scoped — keep the global file for truly cross-project preferences (tone, language) only. A safe global file:
# Global preferences
- Prefer concise commit messages.
- Default response language: English.
- Always read the project CLAUDE.md; project-level instructions take priority over these.If a managed policy file is contradicting you, that is set by IT — you cannot override it from project settings; raise it with whoever owns the managed config.
Step 6: Fix imports, or split via @path
Keep the root file short and lead with the hardest constraints. Anthropic recommends targeting under 200 lines per file: longer files consume more context and measurably reduce how reliably Claude follows them. To keep the top file small, move detail into imports:
# CLAUDE.md
@docs/coding-conventions.md
@docs/test-and-deploy.md
## Hard rules (must read)
- Package manager: pnpm. Never yarn or npm.
- Lint: pnpm run lint:fix before any commit.Then verify each import:
- The
@line is in plain prose, not inside a code block or backticks. - Relative paths are relative to the file that contains them.
- The chain is at most four hops deep.
- The target is not
.gitignoredout of the working tree.
Note: splitting into imports helps organization but does not save context — imported files are expanded into the window at launch just like inline text.
Step 7: Handle subagents and mid-session edits
Two related issues:
Subagents. If a subagent ignores the rules, include them inline in the task prompt so compliance does not depend on inheritance:
Task: research the auth module.
Constraints (from project CLAUDE.md):
- Do not run any package install.
- Test command: pnpm test --filter auth.
- Coding style: follow docs/coding-conventions.md before suggesting changes.Mid-session edits. CLAUDE.md is read at session start. If you edit it during a session, either restart, or run /memory and re-open the file, then paste the changed section into chat and say “this replaces the corresponding section of CLAUDE.md for the rest of this session.” Good news: after a /compact, project-root CLAUDE.md is re-read from disk and re-injected automatically, so compaction does not lose it (nested subdirectory files reload only when Claude next reads that subtree).
How to confirm it’s fixed
- Run
/memory— your projectCLAUDE.md(and any imports) appear in the list. - Ask Claude to recite the first 200 characters of the loaded file; it matches your file exactly.
- Run a prompt that depends on a specific rule (e.g. “install a new dep”) and confirm Claude uses the correct command.
- Dispatch a subagent and verify it honors the same rule, or that you inlined the rule.
- On a Linux box or in CI (case-sensitive), confirm the file still loads.
Long-term prevention
- Commit
CLAUDE.mdand require it in PR templates. - Keep the root file under ~200 lines; push detail into
@-imports or.claude/rules/(path-scoped rules load only when Claude touches matching files). - Add a pre-commit hook that fails if
CLAUDE.mdis renamed to any other casing. - In monorepos, place a
CLAUDE.mdat the workspace root and at each package root; ancestor files concatenate, and the file closest to your cwd is read last. - Use block-level HTML comments (
<!-- maintainer note -->) for human-only notes — Claude Code strips them before injecting context, so they cost no tokens. - Lead with hard constraints; never bury critical rules at the bottom of a long file.
- Periodically run a cold-start probe: open a fresh session, run
/memory, and confirm the project file is loaded.
Common pitfalls
- Editing
CLAUDE.mdand assuming the running session picked it up — it did not, until you restart or re-inject. - Believing “global overrides project.” Layers concatenate; the project file is read last, but a genuine contradiction can still resolve either way.
- Putting team conventions in
~/.claude/CLAUDE.mdso they apply “everywhere,” then wondering why a teammate’s Claude does not know them (that file is machine-local). - Using
Claude.mdorclaude.mdbecause the IDE auto-completed it that way. - Wrapping an
@importin backticks, which turns it into inert literal text. - Assuming imports reduce context — they do not; the whole tree loads at launch.
- Treating a misunderstanding of project architecture as a model failure when it is often just a
CLAUDE.mdthat did not load. - Assuming subagents inherit the file; see subagent result not relayed for related context-handoff issues.
FAQ
Q: How do I tell whether the file loaded or whether Claude is just ignoring it?
Run /memory. If the file is listed, it loaded — the issue is wording or enforcement, so make the rule specific or move it to a hook. If it is not listed, it never reached context — fix the path, casing, or working directory.
Q: Does global ~/.claude/CLAUDE.md override my project file?
No. They are concatenated, with the project file read last (and so weighted higher). The only layer that truly takes priority and cannot be excluded is a managed-policy CLAUDE.md deployed by IT. Contradictions between layers can still resolve arbitrarily, so remove duplicate rules.
Q: Do I need to restart after every CLAUDE.md edit?
For guaranteed pickup, yes. There is no live reload mid-session. As a stopgap, re-inject the changed section into chat. A /compact does re-read the project-root file from disk automatically.
Q: How big is too big?
Anthropic recommends under 200 lines per CLAUDE.md. Note that CLAUDE.md is loaded in full regardless of length — it is not silently truncated. The 200-line / 25KB load cap applies to auto-memory MEMORY.md, not to CLAUDE.md. Past a couple hundred lines you lose adherence and burn context, not content.
Q: What about CLAUDE.local.md?
Same loader; treated as personal, uncommitted overrides. It loads alongside CLAUDE.md and is appended after it in the same directory. Add it to .gitignore. Because a gitignored file lives only in one worktree, for cross-worktree personal rules import from home instead: @~/.claude/my-project-instructions.md.
Q: Why does a subagent ignore CLAUDE.md when the main agent followed it?
The built-in Explore and Plan subagents skip CLAUDE.md by design, and some Task-tool subagents have not picked it up reliably (anthropics/claude-code #29423). Inline the relevant rules in the task prompt so compliance does not depend on inheritance.
Tags: #Claude Code #claudemd #Troubleshooting #configuration #context