User / Project / Directory Levels

Claude Code reads memory from three levels, and each one answers a different question: who does this rule apply to?

• User level — ~/.claude/CLAUDE.md: your personal preferences, on your machine only.
• Project level — ./CLAUDE.md or .claude/CLAUDE.md: shared with the whole team via version control.
• Directory level — a CLAUDE.md inside a subfolder: scoped to that subtree only.

Knowing which file a rule belongs in is a core Claude Certified Architect skill. Put it in the wrong place and either your teammates miss it, or your personal habits leak into everyone's workflow.

The user-level file at ~/.claude/CLAUDE.md lives in your home directory. It applies to every project you open on this machine, but it travels with you, not the repo.

Critically, it is NOT shared via version control. A new teammate cloning the repo will never see it. So it is the right home for personal taste: your preferred commit-message style, how chatty you like responses, or shell aliases you favor.

It is the wrong home for anything the team must agree on — coding standards, build commands, security rules.

The project-level file lives at the repo root as ./CLAUDE.md (or .claude/CLAUDE.md). Because it sits inside the repository, it is committed and shared via version control.

That is exactly what you want for rules the whole team relies on: the build command, test framework, architectural conventions, directory layout, and anything a new contributor needs on day one.

Rule of thumb: if a fresh clone would break without it, it belongs in the project-level CLAUDE.md — not in your personal user file.

A CLAUDE.md placed inside a subfolder is directory-scoped: it applies only when Claude is working within that subtree. This keeps narrow, local rules close to the code they govern.

Example: a frontend/CLAUDE.md can hold React/Tailwind conventions that make no sense for the backend, while services/payments/CLAUDE.md can carry rules that only matter for billing code.

Directory-level files are still committed (they live in the repo), so they are shared — but their reach is the folder, not the whole project.

The levels are additive context, not mutually exclusive. When you work in a subfolder, Claude can draw on the user file, the project file, and the directory file together.

Think of it as concentric scopes:

• User — broadest reach (every project), narrowest audience (just you).
• Project — whole repo, whole team.
• Directory — one subtree, whole team.

So the question is never only "how specific is this rule?" but also "who needs to see it — me, or everyone?" Audience decides user vs project; scope decides project vs directory.

The most common anti-pattern: putting a rule everyone depends on into ~/.claude/CLAUDE.md. It works perfectly for you — so the gap is invisible — but because the user file is never shared via VCS, new teammates miss it entirely.

Symptoms: Claude follows the convention on your machine and ignores it on a colleague's, and nobody can figure out why. The fix is always the same: move shared rules down into the project-level (or directory-level) CLAUDE.md so they ship with the repo.

A CLAUDE.md does not have to be one giant file. You can pull in other files with @path imports, which keeps each file focused and readable.

For example, a project file can import a shared standards document instead of inlining hundreds of lines. This makes the hierarchy easier to maintain and lets you reuse the same standards across files.

A monolithic CLAUDE.md loads into context for every task — even when most of it is irrelevant — wasting tokens. A cleaner pattern for narrow rules is .claude/rules/ files with YAML frontmatter.

Each rule file declares a paths pattern, and it loads only when you are editing matching files. This gives you directory-level precision while saving context, because rules that don't match the current file are never pulled in.

You don't have to hand-edit these files in an external editor. Inside Claude Code, the /memory command opens and edits the CLAUDE.md memory, and changes persist across sessions.

For a brand-new repository, /init bootstraps a project-level CLAUDE.md by documenting the codebase, giving you a sensible starting point you can then refine.

Choosing which file /memory writes to still comes back to the same decision: personal (user) versus shared (project or directory).

This user-versus-project split is not unique to CLAUDE.md — it is a consistent Claude Code pattern. Skills and commands use the exact same two scopes:

• Project scope — .claude/skills/ and .claude/commands/ in the repo are shared via VCS.
• User scope — ~/.claude/skills/ is personal.

Note that .claude/commands/ is the legacy form and .claude/skills/ is the current one, but the scoping rule is identical: repo = team, home = you. Learn the split once and it applies everywhere.

Because project-level and directory-level files are committed to version control, treat them like public code: never put secrets in them. The same discipline applies to a project-scoped .mcp.json (shared in VCS) versus the personal ~/.claude.json.

For tokens and keys, reference environment variables — for example ${GITHUB_TOKEN} — instead of pasting the raw value. The shared file says which variable to use; the actual secret stays in the environment, out of the repo and out of CLAUDE.md.

Your team agrees on a build command and a test framework that every contributor must use. A new engineer just cloned the repo. Where should this rule live so that Claude Code applies it for the whole team from day one?

Pick the level by answering two questions — who and where:

• User (~/.claude/CLAUDE.md): personal, every project, NOT shared via VCS — new teammates miss it. Use for personal preferences only.
• Project (./CLAUDE.md): shared via VCS, whole team, whole repo. The home for build commands and conventions everyone needs.
• Directory (subfolder CLAUDE.md): shared via VCS but scoped to one subtree.

Keep files lean with @path imports and load narrow rules on demand via .claude/rules/ with paths frontmatter. Never commit secrets — reference env vars like ${GITHUB_TOKEN}. The biggest trap to avoid: putting team rules in your personal user file, where everyone else will silently never see them.