CLAUDE.md hierarchy and modular configuration

What you’ll be able to do

• Place instructions at the right level of the CLAUDE.md hierarchy: user, project, or directory
• Diagnose a teammate not receiving instructions that live only in someone’s user-level file
• Use @import to pull only the relevant standards files into each package’s CLAUDE.md
• Split a monolithic CLAUDE.md into topic-specific files in .claude/rules/
• Use /memory to verify which memory files are loaded when behavior differs between sessions

What you need to know

Three levels, and who can see each one

Claude Code reads CLAUDE.md files from three levels of a hierarchy. The architecture question for any instruction is which level it belongs to, and the main thing that decides it is who should receive it.

• User-level — ~/.claude/CLAUDE.md. Lives in one person's home directory and applies to every project that person opens. It is not in the repository, so it is never shared through version control. Use it for personal preferences only.
• Project-level — .claude/CLAUDE.md or a root CLAUDE.md. Committed with the code, so everyone who clones or pulls the repo gets it. Team coding standards, the test command, and architectural rules go here.
• Directory-level — a CLAUDE.md in a subdirectory. Adds instructions that are true only for that part of the tree, such as one package in a monorepo, on top of the project-level file.

The classic failure: a tech lead writes the team's conventions into their own ~/.claude/CLAUDE.md while setting up Claude Code. Everything works on their machine. A new hire clones the repo and Claude ignores the conventions entirely, because the instructions never left the lead's laptop. The fix is not to send the new hire a copy. It's to move the instructions into the project-level file so version control distributes them.

Diagnosing with /memory

When Claude follows a convention in one session and ignores it in another, or behaves differently for two developers on the same repo, don't start by rewording the instruction. First find out what was actually loaded. The /memory command shows which memory files are loaded in the current session. Common findings:

• The instruction only exists in someone's user-level file.
• A directory-level file applies only when working in that subtree, so sessions started elsewhere behave differently.
• An expected file isn't there at all, perhaps because it's untracked or in the wrong location.

Confirm the loading first, then fix the content. Rewording an instruction that never loaded changes nothing.

Keeping CLAUDE.md modular with @import

A CLAUDE.md can reference other files with the @ import syntax, so the file stays short and points to standards documents kept elsewhere. The point is to be selective: the maintainers of each package know which standards apply to their code, so each package's CLAUDE.md imports only those files.

Each standard now lives in one file, is updated in one place, and loads only where it's relevant. Importing everything into everywhere just recreates the monolith in another form.

Splitting a monolith into .claude/rules/

The other modular option is the .claude/rules/ directory: instead of one large CLAUDE.md, keep a set of focused, topic-specific rule files, such as testing.md, api-conventions.md, and deployment.md. Each topic has an obvious home. Edits to testing guidance don't collide with edits to deployment guidance, and anyone reviewing a change can see which area it affects.

Rule files can also be scoped so they load only when Claude is editing matching files, using a paths field in their frontmatter. That's the subject of 3.3. For this task statement, the point is organizational: .claude/rules/ is the alternative to a monolithic CLAUDE.md.

Choosing the mechanism

• Applies to everyone on the project → project-level CLAUDE.md or a topic file in .claude/rules/.
• True only for one subtree → directory-level CLAUDE.md for that subtree.
• Large shared standard that some packages need and others don't → keep it in its own file and @-import it where it applies.
• Only your own preference → ~/.claude/CLAUDE.md, knowing nobody else will see it.

Don't copy one project-wide rule into every subdirectory's file "to be safe." State it once at the scope where it's true. Every copy is another place to update when the rule changes, and the copies will drift.

Key concept

Put each instruction where the people who need it will receive it. User-level files are personal and unshared; team rules belong at project level. Keep the configuration modular with @import and .claude/rules/, and confirm what loaded with /memory before editing content.

When a scenario says "it works for me but not for the new team member," check the hierarchy first. The instruction is almost always in a user-level file.

Practice scenario

Build exercise — Restructure a monolithic CLAUDE.md

Intermediate · 30 min

What you’ll learn

• Separating personal, project-wide, and package-specific instructions
• Using @ imports so each package loads only the standards it needs
• Verifying the result with /memory instead of assuming

1. Take a large CLAUDE.md (or one you’ve written for the exercise) and label each section: personal preference, project-wide rule, or package-specific rule.

   • Why: The right location follows from who needs the instruction, so you have to classify before you move anything.
   • You should see: A few personal items that belong in ~/.claude/CLAUDE.md, a core set of project-wide rules, and blocks that apply only to particular packages or topics.

2. Move topic blocks into .claude/rules/ files (for example testing.md, api-conventions.md, deployment.md), and replace pasted standards in package files with @ imports of only the files each package uses.

   • Why: Topic files and selective imports keep each standard in one place and stop unrelated guidance from loading where it doesn’t apply.
   • You should see: A short root CLAUDE.md, a handful of focused rule files, and package CLAUDE.md files that are mostly import lines plus a few local facts.

3. Open sessions in two different packages and run /memory in each.

   • Why: This confirms which memory files actually load in each place, the same check you’d use to diagnose inconsistent behavior.
   • You should see: The project-level configuration in both sessions, each package’s own CLAUDE.md only in its own session, and no personal files that teammates would be missing.

Exam traps

Putting team-wide conventions in ~/.claude/CLAUDE.md and expecting teammates to get them

User-level instructions apply only to that user and are not shared through version control. Team conventions belong in the project-level CLAUDE.md.

Assuming instructions that work on your machine are reaching everyone because they’re “in CLAUDE.md”

Which CLAUDE.md matters. If it’s your user-level file, nobody else gets it, so a new team member’s sessions behave differently.

Importing every standards file into every package regardless of what that package does

Imports should be selective, based on what the package’s maintainers know applies. Importing everything everywhere rebuilds the monolith.

Letting one root CLAUDE.md grow into a monolith instead of splitting it into .claude/rules/ topic files

Focused files such as testing.md and deployment.md are easier to maintain and review than one ever-growing file that every team edits.

Rewording instructions to fix inconsistent behavior before checking which memory files actually loaded

Use /memory first. If the file holding the instruction isn’t loaded in that session, rewording it won’t help.

Copying the same project-wide rule into every subdirectory’s CLAUDE.md

State a rule once at the scope where it’s true. Copies drift and multiply the work every time the rule changes.

Sources

• Claude Code Docs
• Anthropic, Claude Certified Architect – Foundations Exam Guide v1.0 (July 2026)