What is the difference between global and project CLAUDE.md?

~/.claude/CLAUDE.md   the earlier of the two
./CLAUDE.md           loaded after, so read last

Both enter context; a managed policy file, if your org deploys one, loads before either.

Answer

Both files load in the same session and are concatenated into context rather than overriding each other. The user file at ~/.claude/CLAUDE.md comes first, the project file after it. There is no precedence rule for contradictions — if two instructions disagree, Claude may pick either one, so the fix is to remove the conflict rather than rely on ordering.

What it does

Both files load. Neither replaces the other.

~/.claude/CLAUDE.md   your preferences, every project
./CLAUDE.md           the project's instructions, shared with the team

All discovered files are concatenated into context in load order: broadest scope first, then narrower. Across the directory tree, content runs from the filesystem root down to your working directory, so instructions closer to where you launched Claude are read last. Within a directory, CLAUDE.local.md is appended after CLAUDE.md.

That ordering is about recency, not authority. There is no documented rule that a later instruction beats an earlier one. When two files contradict each other, Claude may pick either.

When to use it

Split by audience, and the conflict question mostly disappears.

Your global file is for things true of you regardless of project: how you like to be addressed, your preferred tooling, personal shortcuts.

The project file is for things true of the project regardless of who is working on it: build commands, layout, conventions the team agreed on.

An instruction that would embarrass you in a code review — a personal preference imposed on a shared repository — belongs in the global file or in CLAUDE.local.md, not in ./CLAUDE.md.

When not to use it

Do not use the global file to override a project convention you disagree with. The result is not an override; it is a contradiction, resolved arbitrarily. If the project convention is wrong, change the project file.

Example

See what is loaded right now:

/context

Both files, if both exist, appear under Memory files.

Browse and edit them:

/memory

In a monorepo where other teams' files get picked up on the way down the tree, exclude them in .claude/settings.local.json:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Managed policy files cannot be excluded this way — that is the point of them.

Common mistakes

Expecting the project file to override the global one. It is read later, not given priority. Contradictions stay contradictions.

Putting personal preferences in the shared file. They reach everyone who clones the repository.

Letting both files grow the same instruction. Duplicates drift. When they drift far enough, they become a conflict nobody wrote on purpose.

Debugging adherence without checking what loaded. Run /context before assuming the instruction was ignored — it may never have been in context. See why Claude Code ignores CLAUDE.md.