[DOC] CLAUDE.md discovery - documentation is inconsistent

Description

There is conflicting information on the docs website about how/where Claude Code can find CLAUDE.md files in the directory tree. (This is an issue that has come up in a few Issues lately.)

Here it says:

How Claude looks up memories

Claude Code reads memories recursively: starting in the cwd, Claude Code recurses up to / and reads any CLAUDE.md or CLAUDE.local.md files it finds. This is especially convenient when working in large repositories where you run Claude Code in foo/bar/, and have memories in both foo/CLAUDE.md and foo/bar/CLAUDE.md.

TL/DR: Claude recurses up the directory tree starting from where you open your session

(No mention is made of a boundary point.)

Here

You can add CLAUDE.md files to any of:

The folder you run Claude in: Automatically added to conversations you start in that folder
Child directories: Claude pulls these in on demand
~/.claude/CLAUDE.md: User-specific preferences that you don’t want to check into source control

So one source says Claude traverses up (the entire directory tree?? I kind of doubt it(?)) and the other source says it can look down and also at $HOME.

• What's the fact of the matter?
• What happens with conflicting information? Is there a precedence order?
• Does Claude really traverse the directory tree all the way from CWD to $HOME?
• When are memories "loaded" up? It says some are on launch, some are "on demand"?
• Does Claude notice manual changes to CLAUDE.md files(?). If so, is it only in a new session?
• What's the difference between CLAUDE.local.md and .claude/CLAUDE.md? Docs suggest they're both for personal, non-checked-in memories. I figured .claude/ was for storing docs and commands and stuff, but then I don't see the distinction between these two alternative CLAUDE files. (EDIT: Come to think of it, if .claude/commands holds slash-commands that might be team-wide, e.g. part of CI/CD or something, then it's not right to think of claude/ as a User-preference thing.)
• I think there's an implicit assumption that a Claude Code workspace is supposed to correspond to a git repo. That's reasonable, but wasn't obvious to me, and isn't documented. And what about monorepos, etc.? Should I put a CLAUDE.md file in every sub-module, for example?
• 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?)
• Does claude -p also respect CLAUDE.md files or no? Does it follow the same rules?

Too much guesswork going on here, IMO! I hope as the team moves out of beta, these rules will become more documented and codified. I love this tool, I hope it continues to improve, and I'd love more transparency/observability about these aspects, otherwise I don't see how it can be incorporated into a production workflow, CI/CD, etc.