CLAUDE.md: What Loads, What Does Not, and Why Yours Gets Ignored

Steps

1. 01

   The four places a CLAUDE.md can live, and who sees each

   There is no single CLAUDE.md. There are four locations with different reach, and confusing them is the first cause of "it did not apply". ~/.claude/CLAUDE.md is your user file and loads in every project on the machine. CLAUDE.md at the root of a repository is the project file, is meant to be committed, and applies to everyone who clones it. CLAUDE.local.md is the personal, uncommitted counterpart — and note that CLAUDE.local.md files in ancestor directories also load in every project underneath them, which is a common surprise. A CLAUDE.md inside a subdirectory is the fourth, and it behaves differently from all three: see the next step.

   ~/.claude/CLAUDE.md        # you, everywhere
   <repo>/CLAUDE.md           # the project, committed, everyone
   <repo>/CLAUDE.local.md     # you, this repo, not committed
   <repo>/packages/api/CLAUDE.md   # conditional — see below

   Copy
2. 02

   The number one reason a CLAUDE.md is ignored: it is in a subdirectory

   A CLAUDE.md in a nested directory does not load at the start of the session. It loads only when Claude Code works with files under that directory. That is by design — it is how a monorepo keeps per-package conventions out of every unrelated session — but it produces exactly the symptom people report as "Claude ignores my CLAUDE.md": you put the rules next to the code they describe, opened a session at the repo root, asked a general question, and nothing applied. If a rule must always be in context, it belongs in the root CLAUDE.md, not in packages/whatever/CLAUDE.md. The same conditional loading applies to a .claude/rules/*.md file that carries paths frontmatter.

   # always in context
   <repo>/CLAUDE.md
   
   # in context only while Claude is working under packages/api/
   <repo>/packages/api/CLAUDE.md
   
   # in context only for files matching its `paths` frontmatter
   <repo>/.claude/rules/testing.md

   Copy
3. 03

   Reason two: a flag switched memory off for that session

   Two flags disable CLAUDE.md loading outright, and both are things people reach for while debugging something else — so the memory file stops applying at exactly the moment they are least likely to suspect it. --safe-mode starts a session with CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents all disabled. --bare goes further: minimal mode skips hooks, LSP, plugin sync, auto-memory, keychain reads and, in its own words, CLAUDE.md auto-discovery. If you are in safe mode, Claude Code will tell you so when you open a memory file — but it will not remind you on every turn.

   # both of these mean: no CLAUDE.md this session
   claude --safe-mode
   claude --bare
   
   # back to normal
   claude

   Copy
4. 04

   Reason three: the session is not where you think it is

   CLAUDE.md loading is anchored to the session working directory, and that directory can move. The /cd slash command moves the session — it changes the working directory and write access, and it loads project configuration, CLAUDE.md and settings included, from the new location. --add-dir adds directories the tools may touch, and the help text for --bare names those as "CLAUDE.md dirs", so which directories are in scope is part of what determines which memory files apply. If a session started in a parent directory or was moved, the CLAUDE.md you edited may simply not be in scope any more.

   # check where you are before blaming the file
   claude
   > /status
   
   # moving the session also moves which CLAUDE.md applies
   > /cd packages/api

   Copy
5. 05

   Reason four: it is too long to be worth reading

   CLAUDE.md content is resident in context on every single turn — it is not fetched on demand. That has a consequence people rarely connect to the symptom: a CLAUDE.md padded with things a fresh session could work out for itself in two tool calls (ls, cat, reading the manifest, running --help) costs tokens every turn and dilutes the handful of lines that actually matter. Claude Code’s own guidance for writing an initial CLAUDE.md is explicit about not including obvious instructions. If your file is long and your rules are being missed, deleting two thirds of it is a more reliable fix than adding emphasis.

   # instead of pasting a long API reference into CLAUDE.md:
   @docs/api-reference.md
   
   # @path imports pull content in on demand
   # rather than making it resident every turn

   Copy
6. 06

   Write it and edit it with the built-in commands, not by hand

   /init generates a first CLAUDE.md for the repository you are in, and it will ask whether you want a project CLAUDE.md, a personal CLAUDE.local.md, or both — that choice is the same scope decision as step one, made at the moment it matters. /memory opens the memory files for editing and shows which ones are in play. Using them beats hand-creating the file because you find out immediately which scope you actually wrote to.

   claude
   > /init      # generate one for this repo
   > /memory    # edit the memory files that are loaded

   Copy

Troubleshooting

I wrote CLAUDE.md and Claude clearly is not following it

Check scope before wording. First: is the file at the repository root, or in a subdirectory? A subdirectory CLAUDE.md loads only while Claude is working with files under that directory, so a general question asked at the repo root will never see it. Second: are you in --safe-mode or --bare? Both disable memory entirely. Third: run /memory, which opens the memory files that are actually in play — if yours is not listed, the problem is location, not content. Only after those three is it worth rewriting the rules.

It worked yesterday and stopped today, with no edit to the file

Something about the session changed, not the file. The usual causes are: the session was started from a different directory, /cd moved it, or a flag you added while debugging something else (--safe-mode, --bare) is still in your shell history and got re-run. /status shows the session state; starting a plain claude in the repository root is the fastest way to confirm.

My CLAUDE.md is long and specific and the important rules still get missed

Length is working against you. CLAUDE.md is resident in context every turn, so every line a fresh session could have discovered on its own (the directory layout, what the package scripts do, generic advice like "write tests") competes with the lines that carry real information. Move long references out with @path imports so they load on demand, move package-specific conventions into that package’s own CLAUDE.md, and delete anything reconstructible with ls, cat or --help.

Rules meant for one package are affecting everything

You put them in the root file. Move them to <package>/CLAUDE.md, which loads only when Claude works under that directory, or into .claude/rules/<name>.md with paths frontmatter that scopes them to matching files. The trade-off is the one in the first troubleshooting entry — scoped files are quiet by design, so do not use them for a rule that must always apply.

Teammates get different behaviour from the same repository

Two files in the same repository have different reach. CLAUDE.md is committed and shared; CLAUDE.local.md is not. If a rule only exists in someone’s CLAUDE.local.md, or in their ~/.claude/CLAUDE.md, nobody else has it. Ancestor-directory CLAUDE.local.md files are the sneaky version of this — they load in every project underneath them, so one developer can carry a machine-wide rule into a repository without anyone else seeing it.