AI AI Tools Guidebook
Troubleshooting

Claude Code Project CLAUDE.md Not Loading Into Context

Claude Code starts a session but ignores your project CLAUDE.md — conventions, commands, and instructions never reach the model. Diagnose path, scope, and merge precedence.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

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. It is not that Claude is ignoring the instructions; it is that the file never made it into the context at all. Project CLAUDE.md loading has a few non-obvious failure modes: wrong filename casing, file in a subdirectory the CLI cannot reach from the launch cwd, conflicting user-level CLAUDE.md masking it, or a stale cache from a prior session that needs a reload.

Common causes

Ordered by frequency in real deployments.

1. Launched from the wrong working directory

Claude Code looks for CLAUDE.md starting at the current working directory and walks up to the user home. If you launch from ~/projects instead of ~/projects/myrepo, the per-project file is never seen — only the global one is.

How to spot it: pwd before claude invocation does not match the directory containing CLAUDE.md. Or you have multiple repos open and ran claude in a parent folder.

2. Wrong filename or casing

The file must be exactly CLAUDE.md — uppercase, no extension swap. Claude.md, claude.md, CLAUDE.MD, or CLAUDE.markdown are all ignored on case-sensitive filesystems (Linux, most CI). macOS default HFS+/APFS is case-insensitive so it works locally, 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. User-level CLAUDE.md masking the project one

Global ~/.claude/CLAUDE.md is loaded too, and in some versions it merges with or overrides project-level instructions if there are conflicting directives. A blanket “always use yarn” in the global file beats the project file’s “use pnpm”.

How to spot it: Both files exist; the model’s behavior matches the global file’s directives, not the project file. Conflict on specific keys like package manager or commit style.

4. File exceeds size cap and gets silently truncated

CLAUDE.md has a soft size limit (commonly 10-15k tokens). Beyond that the tail gets dropped before injection. If your important rules are at the bottom, they vanish.

How to spot it: Rules at the top of CLAUDE.md are honored; rules at the bottom are not. wc -c CLAUDE.md is over 40,000 bytes.

5. Imports / @path references not resolved

CLAUDE.md supports @./docs/conventions.md style imports. If the referenced file is missing, in .gitignore, or outside the project root, the import fails silently and that block is empty.

How to spot it: Your CLAUDE.md is short and just imports several files; the model only knows the literal CLAUDE.md content, not the imported files.

6. Subagent / Task tool spawned without CLAUDE.md context

When the main agent spawns a subagent via the Task tool, the subagent gets a fresh context. Some configurations do not auto-propagate CLAUDE.md to subagents, so subagent runs ignore project rules even when the main agent honored them.

How to spot it: Direct prompts to Claude Code follow CLAUDE.md; prompts that explicitly spawn a subagent (“dispatch a task to research X”) do not.

Before you start

  • Confirm the cwd you launched Claude Code from.
  • Note whether the issue is on the main agent, a subagent, or both.
  • Capture one concrete instruction in CLAUDE.md that is being violated — you need a deterministic test case.
  • Check whether the file is in version control (git ls-files CLAUDE.md).

Information to collect

  • pwd at session start.
  • ls -la CLAUDE.md and wc -c CLAUDE.md.
  • Existence and contents of ~/.claude/CLAUDE.md (the global file).
  • Any @-imports inside CLAUDE.md and whether those target files exist.
  • Claude Code version (claude --version).
  • Whether you are on macOS (case-insensitive default) or Linux/CI (case-sensitive).

Step-by-step fix

Ordered by how often each one is the actual fix.

Step 1: Verify the file is found at all

Ask Claude directly:

What is the exact content of the project CLAUDE.md you have loaded? Print the first 200 characters verbatim, no paraphrasing.

If it prints something different from your file, or says “I do not see a project CLAUDE.md”, the load is the problem — not the rules.

Step 2: Fix cwd and relaunch

Exit, cd into the repo root, relaunch:

cd ~/projects/myrepo
ls CLAUDE.md   # must exist here
claude

If launching from a parent shell wrapper (tmux, VS Code task), confirm that wrapper’s cwd, not your terminal’s cwd.

Step 3: Normalize the filename

mv claude.md CLAUDE.md  2>/dev/null
mv Claude.md CLAUDE.md  2>/dev/null
git mv claude.md CLAUDE.md

Commit the rename. On macOS the git mv may need --force because of case-insensitivity.

Step 4: Resolve global vs project conflict

Open ~/.claude/CLAUDE.md and remove or comment out directives that should be project-scoped. Keep the global file for truly cross-project preferences (tone, language) only.

A safe global file looks like:

# Global preferences
- Prefer concise commit messages.
- Default response language: English.
- Always read the project CLAUDE.md first; project-level instructions override these.

Step 5: Trim CLAUDE.md or split via imports

If over 10k tokens, move sections out:

# CLAUDE.md
@./docs/coding-conventions.md
@./docs/test-and-deploy.md
@./docs/architecture-notes.md

## Hard rules (must read)
- Package manager: pnpm. Never yarn or npm.
- Lint: pnpm run lint:fix before any commit.

Keep the top of CLAUDE.md to the hardest constraints. Verify each @ target exists and is not gitignored.

Step 6: Force-propagate to subagents

When you dispatch a Task tool subagent, include the rules inline in the task prompt:

Task: Research the auth module.
Constraints (from project CLAUDE.md):
- Do not run any package install.
- Test command: pnpm test --filter auth.
- Coding style: see @./docs/coding-conventions.md before suggesting changes.

This makes rule-following independent of whether subagent inheritance is working.

Step 7: Force-reload after editing CLAUDE.md mid-session

CLAUDE.md is read at session start. If you edit it during a session, Claude is still operating on the old copy. Either restart the session, or paste the updated section into the chat and say “this replaces the corresponding section of CLAUDE.md for the rest of this session”.

Verify

  • After relaunch, ask Claude to recite the first 200 characters of CLAUDE.md — match must be exact.
  • Run a prompt that depends on a specific CLAUDE.md rule (e.g., “install a new dep”) and confirm Claude uses the correct command.
  • Spawn a subagent and verify it honors the same rule.
  • Check on a Linux box / in CI to confirm casing works there too.

Long-term prevention

  • Keep CLAUDE.md committed to the repo and require it in PR templates.
  • Use @-imports to keep the root file under 200 lines; long detail belongs in docs/.
  • Add a pre-commit hook that fails if CLAUDE.md is renamed to any other casing.
  • For multi-repo monorepos, place a CLAUDE.md at the workspace root AND at each package root; the closest one wins.
  • Document in CLAUDE.md itself: “If you do not see this rule, the file failed to load — stop and ask.”
  • Avoid putting critical rules at the bottom of a long file; lead with hard constraints.
  • Periodically run a cold-start probe: open a fresh session and ask Claude to confirm it sees the project file.

Common pitfalls

  • Editing CLAUDE.md and assuming the running session picked it up — it did not.
  • Putting team conventions in ~/.claude/CLAUDE.md so they apply “everywhere”, then wondering why a new teammate’s Claude does not know them.
  • Using Claude.md or claude.md because the IDE auto-completed it that way.
  • Relying solely on @-imports without realizing the import target is .gitignored.
  • Stuffing 30k tokens of historical context into CLAUDE.md and losing the actual rules to truncation.
  • Forgetting that a misunderstanding of project architecture is often just a CLAUDE.md miss, not a model failure.
  • Assuming subagents inherit the file; see subagent result not relayed for related context-handoff issues.

FAQ

Q: I see Claude reading CLAUDE.md in the tool calls but it still ignores the rules. Why?

Reading is not the same as treating it as authoritative. Add an explicit line at the top: “These rules are non-negotiable. Confirm you read them before any tool call.” Then test compliance on a concrete rule.

Q: Do I need to restart after every CLAUDE.md edit?

Yes for guaranteed pickup. Or paste the changed section into the conversation as a directive. There is no live-reload.

Q: Can I have a different CLAUDE.md per branch?

Yes — it lives in the repo, so branch-scoped versions work. Be careful with subagents spawned in worktrees; see Claude Code settings.json not loading for related path-resolution issues.

Q: How big is too big?

Past 8-10k tokens you start losing the tail. Past 15k tokens you lose effectiveness even on what is loaded — too much for the model to weight consistently.

Q: What about CLAUDE.local.md?

Same loader, treated as personal overrides not committed to git. Add it to .gitignore. Useful for personal preferences without polluting the team file.

Tags: #Claude Code #claudemd #Troubleshooting #configuration #context

Related Articles