[DOC] CLAUDE.md discovery - documentation is inconsistent

Linked to:
#707
#705

I regularly put multiple repositories in a directory with a CLAUDE.md that has a simple rule to list the repositories in the current directory, ask which one to load, and then load a context there. That context can be named anything.

See also https://github.com/ChristopherA/Claude-Code-CLI-Toolkit which has a different context for every branch of a repo.

@ChristopherA Nice! I'll definitely check it out. Still, it's a custom toolkit, doesn't answer/resolve the questions/issues about Claude Code itself

I guess one of my concerns is having the predefined CLAUDE.md, et al, do too much or lock you into not being able to customize for specific needs (like I do with a context per branch, but maybe you need some other organization).

Instead I’d like have more use of things that Claude Code can do better than I can. For instance, I’d like to see the /compact output be available (see https://github.com/anthropics/claude-code/issues/667 ) for my use.

So back to your root issue, which is that these special files are not well documented, I’d almost argue we shouldn’t predetermine them. For instance, currently # text gets appended to CLAUDE.md, but I don’t want it there, I want it applied to my current context file. If Claude Code doesn’t know where that is on first use, it should ask me, while offering a useful default, but not requiring it.

Thank you for the feedback! Great questions - will update our docs to make it more clear.

https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview#determine-memory-type is the best resource for CLAUDE.md locations

What happens with conflicting information? Is there a precedence order?

All CLAUDE.md's described here are included when you first launch Claude. When setting up your CLAUDE.md's you need to take care to not include conflicting instructions.

Does Claude really traverse the directory tree all the way from CWD to $HOME?

Claude traverses from CWD to / (i.e. to root, not $HOME)

When are memories "loaded" up? It says some are on launch, some are "on demand"?

Claude can read any file under CWD (including nested CLAUDE.md's) on demand, but only the CLAUDE.md's outlined here are loaded automatically on launch.

Does Claude notice manual changes to CLAUDE.md files(?). If so, is it only in a new session?

Not currently - new sessions will pick up changes on launch.

What's the difference between CLAUDE.local.md and .claude/CLAUDE.md? Docs suggest they're both for personal, non-checked-in memories.

$cwd/CLAUDE.local.md is for project-specific instructions (similar to $cwd/CLAUDE.md, but not checked in so you can use it for project-specific instructions that are only relevant to you), ~/.claude/CLAUDE.md applies to all projects.

what about monorepos, etc.? Should I put a CLAUDE.md file in every sub-module, for example?

Yes, that is a convenient way to have instructions for sub-modules and for the entire repository at the same time. If you have repo/CLAUDE.md and repo/module/CLAUDE.md, then when you launch claude from repo/module it will get both instruction files loaded.

Can Claude access "cousin" directories? If i'm in foo/bar for the bar module in the foo repo, will it read foo/baz/CLAUDE.md if I ask it about foo/baz? (Is it even allowed to look there?)

Claude can read cousin directories if you specifically prompt it to, but it is not automatic like reading CLAUDE.md's on launch.

Does claude -p also respect CLAUDE.md files or no?

yes, claude -p works the same way

@levpopov thanks for the clarifications

Claude can read any file under CWD (including nested CLAUDE.md's) on demand, but only the CLAUDE.md's outlined here are loaded automatically on launch.

fwiw this seems to conflict with

Claude traverses from CWD to / (i.e. to root, not $HOME)

...and the subsequent section in the docs, unless I'm missing something?

it seems that a parent CLAUDE.md _is_ included in the context window. from claude — we get the file in our current worktree and the one in a parent dir

⏺ Yes, the full contents of all three CLAUDE.md files are in my context window:

  1. User's private global instructions (/Users/maximilian/.claude/CLAUDE.md)
  2. Project instructions from main repo (/Users/maximilian/workspace/xarray/CLAUDE.md)
  3. Project instructions from current worktree (/Users/maximilian/workspace/xarray/.worktrees/traceback/CLAUDE.md)

Can the discovery of slash commands also follow a similar pattern?

Does `claude -c` re-load CLAUDE.md ?

@alexx-ftw it's supposed to be i believe, yes - you can try asking Claude or also look at the logfile - when you run -c it creates a new jsonl file but it copies over the old convo as well - so you could maybe tell something from that, but don't rush to conclusion. Probably there's a few factors in play, like whether CLAUDE.md changed, and how long the conversation has been.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.