Why Claude Code isn't following your CLAUDE.md file (it's probably never loaded)

You wrote a CLAUDE.md rule — “always use the repo’s logger, never console.log,” “this directory is generated, don’t hand-edit it” — and Claude Code just… doesn’t follow it. No error. It’s not that it read the rule and decided to override it; it’s acting like the rule was never there. If you searched “claude code ignoring CLAUDE.md,” “claude code not reading my rules,” or “claude.md not working,” this is almost always the same handful of loading gaps, not the model being careless.

The mechanism: most of these rules were never loaded

Claude Code builds its memory for a session by walking up from your current directory to the filesystem root, collecting every CLAUDE.md it passes, then adding your user-level file at ~/.claude/CLAUDE.md. That part happens automatically at startup, and it’s the part most people picture when they think “Claude Code reads CLAUDE.md.”

What catches people out is CLAUDE.md files that live in subdirectories of the project — a packages/api/CLAUDE.md, a src/payments/CLAUDE.md. Those aren’t loaded at startup at all. They’re pulled in lazily, only once Claude actually reads or edits a file inside that subtree. Early in a session — before it’s touched anything in payments/ — a rule sitting in payments/CLAUDE.md is functionally absent. Ask Claude to explain the payments flow from memory and it’ll act like the rule doesn’t exist, because for that turn, it doesn’t. This is documented, intentional behavior (it keeps large monorepos from front-loading every subdirectory’s context on every session), but it reads exactly like a bug from the user’s side.

CLAUDE.local.md — the gitignored, personal-override variant — has a narrower version of the same trap: it’s only ever loaded at the project root. A CLAUDE.local.md dropped into a subdirectory, expecting the same lazy-load treatment as a subdirectory CLAUDE.md, is just never read.

The other common gap is simpler: the file Claude Code loaded isn’t the file you edited. If you started the session from a different working directory than you think — a subfolder, a symlinked checkout, a worktree — the “root” it walked up from is relative to that location, not the path you have open in your editor tab.

How to tell which one you’ve got

1. Run /memory in the session. It opens a menu listing every CLAUDE.md and CLAUDE.local.md actually loaded right now, and lets you jump straight to editing any of them. If the file you edited isn’t on that list, nothing after this matters until it is.
2. Or run /context and check the Memory files section. Same information, shown alongside the rest of what’s occupying the context window — useful if you also want to see how much room the loaded memory is taking up.
3. If the rule is in a subdirectory file and it’s missing early in the session, don’t assume it’s broken — ask Claude to read a file in that subtree first, then check /memory again. If it appears now, this was lazy loading, not a failure.
4. If a CLAUDE.local.md in a subdirectory never appears, that’s the root-only restriction, not a bug — it will never load from anywhere but the project root.
5. If nothing from the project shows up in /memory at all, check where the session actually started — pwd in your shell before you ran claude, not where your editor thinks you are.

The fix

For a subdirectory rule you need available from the start of a session, not just after Claude happens to touch that area, move it up: either put the instruction in the root CLAUDE.md, or explicitly reference the subdirectory file from the root one so it gets read early instead of waiting on lazy discovery.

For CLAUDE.local.md files, keep personal overrides at the project root only — there’s no working nested equivalent, so a subdirectory one is dead weight, not a smaller-scope override.

For the wrong-directory case, cd into the actual project root (or the specific subtree you want) before launching claude, rather than relying on it to find the right file from wherever your terminal happened to be.

Verify it actually loaded

Run /memory again after making the change and confirm the specific file — not just “a” CLAUDE.md — is on the list, then ask Claude a question that only the new rule would let it answer correctly (e.g., “what logger should I use in this directory”). A file appearing in /memory and Claude actually applying the rule in its next response are two different checks; do both before you trust it.