Where should CLAUDE.md be located?

~/.claude/CLAUDE.md    you, every project
./CLAUDE.md            project, shared with the team
./.claude/CLAUDE.md    the same scope, either location works
./CLAUDE.local.md      you, this project only

Load order, broadest scope first. Managed policy files load before all of these.

Answer

A project file goes at ./CLAUDE.md or ./.claude/CLAUDE.md. Personal preferences across projects go in ~/.claude/CLAUDE.md, and personal notes for one project in ./CLAUDE.local.md. Files at or above your working directory load in full at launch; files in subdirectories load only when Claude reads something there.

What it does

CLAUDE.md can live in four places. They differ in who the instructions apply to, not in what they can say.

Managed policy   organisation-wide, deployed by IT
~/.claude/CLAUDE.md   you, in every project
./CLAUDE.md or ./.claude/CLAUDE.md   the project, shared through git
./CLAUDE.local.md   you, in this project only

The managed policy path depends on the platform: /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, C:\Program Files\ClaudeCode\CLAUDE.md on Windows.

The list above is also the load order — broadest scope first — so a project instruction lands in context after a user instruction.

Where in the tree matters too. Claude Code walks up from your working directory, loading CLAUDE.md and CLAUDE.local.md from each directory along the way, in full, at launch. Files in subdirectories below you are not loaded at launch; they arrive when Claude reads a file in that subdirectory.

When to use it

Pick the location by asking who should get the instruction:

the whole team, versioned with the code → ./CLAUDE.md
only you, everywhere → ~/.claude/CLAUDE.md
only you, only here → ./CLAUDE.local.md, and add it to .gitignore

For a monorepo, a per-package CLAUDE.md in a subdirectory is useful precisely because it loads late: it costs nothing until Claude works in that package.

Example

Confirm which files actually loaded:

/context

Look under Memory files. A file that is not listed there is not in context, whatever the filename suggests.

Generate a starting project file:

/init

Keep personal notes out of git:

echo "CLAUDE.local.md" >> .gitignore

CLAUDE.local.md only exists in the worktree where you made it. To share personal instructions across worktrees of the same repository, keep the text in your home directory and pull it in with an @ import — a line beginning with @ and a path inlines that file's contents where the line stands:

# Individual Preferences
- @~/.claude/my-project-instructions.md

Common mistakes

Assuming a subdirectory file loads at startup. It does not. It loads when Claude reads a file in that directory, which may be never in a given session.

Expecting AGENTS.md to be read. Claude Code reads CLAUDE.md. If your repository uses AGENTS.md, import it: a CLAUDE.md containing @AGENTS.md makes both tools read the same instructions.

Committing CLAUDE.local.md. It is meant for things you would not share — sandbox URLs, test data, personal shortcuts. Put it in .gitignore.

Trusting the filename over /context. The only proof a file loaded is its appearance under Memory files.