CLAUDE.md Hierarchy: User, Project and Directory Scopes

1.Where CLAUDE.md files can live

A CLAUDE.md file is a plain markdown briefing that Claude reads automatically. You don't attach it to a prompt. If the file exists in a location Claude checks, the instructions are already in context. There are several such locations, and each one answers a different question: who should this instruction reach?

The project file is the one most teams need. It holds the architecture, conventions, and build and test commands that everyone working on the repository should follow. The support guidance says it plainly: most teams only need the project-root file, committed to git. The other scopes cover exceptions. The user file holds personal habits that follow you across projects. The local file holds personal settings for one project, such as your sandbox URLs, and should be gitignored. The managed file is for organisation-wide policy that IT deploys.

Sources12

2.User-level instructions stay on your machine

~/.claude/CLAUDE.md sits in your home directory, not in any repository, so version control never sees it. That's why it suits preferences like "I use pnpm, not npm". It's also why it's the wrong place for anything the team depends on. The file applies to every project you open, but only for you.

That scenario is the standard shape of a configuration hierarchy issue, and diagnosing it follows a fixed routine. When a new team member is not receiving instructions that work for everyone else, first ask which scope the instruction lives in. An instruction in user-level configuration (~/.claude/CLAUDE.md) or in a gitignored ./CLAUDE.local.md never travels with the clone. An instruction in project-level configuration (./CLAUDE.md or ./.claude/CLAUDE.md) does. Run /memory on both machines: it lists the memory file locations across user and project scopes, so you can see at once that the rule appears under the senior engineer's user scope and under no project scope at all. The docs' own signal for what belongs in the project file is the same one: if a new teammate would need the same context to be productive, it belongs in the shared file, not in a personal one.

The same reasoning works in reverse. If you want personal editor or formatting preferences to apply to every project on your machine without committing them anywhere, the user-level file is the right place. If a personal preference applies to only one project, ./CLAUDE.local.md keeps it out of the shared file, as long as you add it to .gitignore. Auto memory is separate again. It lives under ~/.claude/projects/<project>/memory/ and holds notes Claude writes for itself, while the CLAUDE.md files are the ones you maintain by hand.

Sources134

3.Directory-level files load when Claude works there

CLAUDE.md files can also sit in subdirectories, such as frontend/CLAUDE.md or packages/api/CLAUDE.md, to hold conventions for one module. When they load depends on where you started Claude. Files at and above the working directory are read at session start. A file in a subdirectory below the working directory isn't read at start. It loads when Claude reads files in that subdirectory.

The recommended split follows from this. The root CLAUDE.md holds rules that apply everywhere, such as coding standards and commit conventions. Each subdirectory file holds conventions for that area's stack. In a monorepo that means one file per package. In a large single tree it means one per subsystem, such as src/db/ or src/api/. Because subdirectory files load on demand, someone working only in the API package doesn't carry the frontend's rules in context.

Per-package files don't have to repeat shared material, because a CLAUDE.md can reference external files with the @import syntax. Writing @ followed by a path inside the file pulls that file's content in when the CLAUDE.md loads. The docs' example reads "See @README for project overview and @package.json for available npm commands for this project." A bullet such as "git workflow @docs/git-instructions.md" imports a standards document, and a home-directory path such as @~/.claude/my-project-instructions.md imports a personal file. This keeps CLAUDE.md modular: the standards live once, in their own files, and each CLAUDE.md just lists which ones apply.

In a monorepo, that lets you use @import selectively. Keep the shared standards as separate files, say docs/api-conventions.md, docs/testing.md and docs/deployment.md, and let each package's CLAUDE.md import only the ones relevant to that package. Which standards those are is domain knowledge the package's maintainers hold: the API package's maintainers know it needs the API conventions and the deployment standards, while the shared library's maintainers know it needs only the testing standards. The same mechanism is how an existing AGENTS.md is folded in: when a CLAUDE.md already imports AGENTS.md, Claude reads the CLAUDE.md with AGENTS.md included through the import.

Sources521

4.Splitting a monolithic CLAUDE.md into .claude/rules/

Imports are one way to keep CLAUDE.md modular. The other is the .claude/rules/ directory, an alternative to a monolithic CLAUDE.md that keeps everything in one central place. Instead of one large file covering testing, API conventions and deployment at once, you split it into focused topic-specific rule files, one markdown file per topic, and Claude loads them alongside the project CLAUDE.md. Like CLAUDE.md, rules files are committed to the repository, so the whole team receives them.

A rules file can also be path-gated. Its only frontmatter field is paths, an optional list of glob patterns such as src/api/**/*.ts. When paths is set, the rule loads only when Claude works with a file that matches, so an API rule file doesn't sit in context while Claude edits the frontend. Without paths, the rule loads like any other project instruction. The same directory exists at user scope as ~/.claude/rules/, for personal rule files that stay on your machine, and a shared standards file can be symlinked into .claude/rules/ rather than copied.

Sources165

5.How the levels combine, and checking them with /memory

The levels don't replace each other. Every CLAUDE.md that loads adds its content to the same context. A subdirectory file doesn't override the root file, and a project file doesn't cancel your user file. When two instructions conflict, Claude uses its judgement to reconcile them. There's no strict precedence rule. So the fix for a contradiction is to remove it, not to count on one file winning.

When Claude behaves differently from one session to the next, or from one teammate to another, start by checking which files were actually loaded. The /memory command lists memory file locations across user and project scopes and lets you open each one in your editor. That's usually enough to show a missing project file, a rule that exists only in someone's user file, or a stale instruction.

Timing is the other common cause. CLAUDE.md is read when the session starts and isn't re-read from disk on every turn. An edit made mid-session is picked up the next time you run /compact or open the file through /memory. Otherwise it takes effect in your next session. So if you just added a rule and Claude doesn't seem to follow it yet, the session may still be using the older version.

Sources732

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Rules in ~/.claude/CLAUDE.md reach every developer who works on the repository.Why is that wrong?

   The user-level file applies only to the person whose home directory it's in. Only the project CLAUDE.md is shared with teammates through source control.

   Covered in User-level instructions stay on your machine

2. 2.Every subdirectory CLAUDE.md in the repository is loaded when a session starts at the root.Why is that wrong?

   Only files at and above the working directory load at launch. A subdirectory file below it loads later, when Claude reads files in that subdirectory.

   Covered in Directory-level files load when Claude works there

3. 3.A file in .claude/rules/ only loads if its frontmatter declares a paths glob.Why is that wrong?

   paths is optional. It narrows a rule to matching files when present; a rule file without it still loads as a topic-scoped instruction alongside CLAUDE.md.

   Covered in Splitting a monolithic CLAUDE.md into .claude/rules/

4. 4.A more specific CLAUDE.md replaces the instructions from the levels above it.Why is that wrong?

   CLAUDE.md files are additive: every level contributes to context at the same time, and Claude uses judgement to reconcile conflicts.

   Covered in How the levels combine, and checking them with /memory