Domain 3 · Task 3.1

CLAUDE.md Hierarchy & Scoping

Configure CLAUDE.md with hierarchy, scoping, and modular organization.

CLAUDE.md is how you give Claude Code standing instructions and context. It loads in a three-level hierarchy — user, project, and directory — and the single most-tested idea is knowing which level a given instruction belongs at. Get the level wrong and a teammate silently misses the conventions everyone else has; get it right and one committed file governs the whole team.

Key concept

Everyone must get it → project-level (.claude/CLAUDE.md, committed). Just me → user-level (~/.claude/CLAUDE.md, not shared). Diagnose inconsistent behaviour with /memory to see what is actually loaded.

What you need to know

The three levels of the hierarchy

CLAUDE.md resolves from broad to specific, and each level answers a different scoping question:

User — ~/.claude/CLAUDE.md. Personal preferences and working style. Not shared via VCS, so it applies only to you.
Project — .claude/CLAUDE.md or a root CLAUDE.md. Team coding/testing standards and architecture decisions. Committed, so everyone who clones the repo gets it.
Directory — a CLAUDE.md inside a subdirectory. Conventions specific to that part of the codebase; it is in the repo, and subdirectory files load on demand when Claude works in that directory.

The decision is always the same question: *"is this instruction in a location everyone shares?"* If it must reach the whole team, it belongs at project level.

text

~/.claude/CLAUDE.md        # USER  — personal, NOT committed
my-repo/
  CLAUDE.md                # PROJECT — team standards, committed
  .claude/CLAUDE.md        # PROJECT — equivalent project location
  services/api/CLAUDE.md   # DIRECTORY — conventions for services/api, loads on demand

The classic hierarchy bug

The canonical exam scenario: a new hire does not receive the team's conventions. The cause is almost always that the instructions were written to user-level (~/.claude/CLAUDE.md) on someone's machine instead of project-level (.claude/CLAUDE.md) in the repo. User-level files never travel through version control, so a new teammate's checkout has none of them. The fix is to move the conventions into the committed project file. Similarly, inconsistent behaviour across sessions is diagnosed with /memory, which shows exactly which memory files are currently loaded so you can spot a stray user-level or missing project-level file.

Keeping it modular: @import and .claude/rules/

A monolithic CLAUDE.md becomes hard to maintain. Two mechanisms keep it modular:

@import pulls in other files inline. Write @ immediately before the path (no space); relative paths resolve against the importing file. This lets each package include only the standards relevant to it. (The exam baseline cites max nesting depth 5; current docs say 4 — either way, keep imports shallow.)
.claude/rules/ holds focused, topic-specific files (testing.md, api-conventions.md, deployment.md) as an alternative to one giant file. This is also the home for path-scoped rules (covered in module 3.3).

Use @import when you want a shared standard included wherever it is relevant; split into .claude/rules/ when a single file has grown to cover too many unrelated topics.

markdown

Coding standards: @./standards/coding-style.md
Testing requirements: @./standards/testing-requirements.md
Project overview: @README.md

Exam traps

The trap	The reality
Putting the team's conventions in `~/.claude/CLAUDE.md` shares them with everyone on the project.	User-level files are personal and never committed, so teammates never see them. Team conventions go in project-level `.claude/CLAUDE.md`.
A new hire missing the conventions means their local Claude Code install is broken or out of date.	It is a hierarchy placement bug: the instructions live at user level instead of project level. Move them into the committed project file.
Inconsistent behaviour across sessions is random and can only be fixed by re-writing the prompt.	Run `/memory` to see which memory files are actually loaded — the inconsistency is usually a stray or missing `CLAUDE.md` at one level.
A directory-level `CLAUDE.md` can enforce a convention on files spread across many directories.	A directory file only applies to its own directory. For a convention that spans the tree, use `@import` of a shared standard or a path-scoped rule (module 3.3).

Practice scenario

Real questions from the bank that test this topic — the correct answer is highlighted.

Your organization uses Claude Code with multiple levels of CLAUDE.md:

~/.claude/CLAUDE.md — your personal preferences: "always write tests in Jest"
/repo/CLAUDE.md — project-level: "use Vitest for new tests, Jest only for legacy"
/repo/services/billing/CLAUDE.md — service-level: "all billing tests must include amount validation"

You start a new test file in /repo/services/billing/ .

Which instructions does Claude follow?

AOnly the most specific file ( /repo/services/billing/CLAUDE.md ) — more specific files completely override less specific ones

BOnly the project-level file ( /repo/CLAUDE.md ) — user-level files don't apply when working in a repo

CAll three files are loaded in order; when they conflict, the more specific file's guidance takes precedenceCorrect

DOnly ~/.claude/CLAUDE.md — user-level files are loaded first and "win" by default

Why: Claude Code loads CLAUDE.md files hierarchically: user-level, then project-level, then progressively more specific subdirectories. All apply; for conflicts, the more specific file's guidance wins. So in /repo/services/billing/ you'd get: Vitest for new tests (project overrides user-level Jest), and amount validation required (service-level applies). Knowing this hierarchy cold is exam-critical — Domain 3 leans on it heavily.

You want every Claude Code session in your repository to automatically load the current sprint's task list (which changes weekly, stored in .claude/sprint-context.md ) into context before the user types anything, without bloating CLAUDE.md (reserved for static project rules).

Which mechanism fits?

AAdd @.claude/sprint-context.md to the top of CLAUDE.md

BUse a SessionStart hook that reads the file and injects it as additional contextCorrect

CDefine it as a custom slash command users must run at the start of each session

DAdd the file path to an additionalDirectories setting in settings.json

Why: SessionStart hooks fire when a session begins and can inject dynamic context — perfect for content that changes between sessions (sprint task lists, current branch state, etc.). CLAUDE.md is for static project rules; the question explicitly says don't bloat it. The @import (A) is technically possible but the question rules it out by reserving CLAUDE.md for static content. Slash commands (C) require explicit user invocation. additionalDirectories (D) controls which directories Claude can access, not context injection.

Build exercise

Set up a three-level CLAUDE.md and diagnose a placement bug

~35 min

1
In a test repo, create a project-level .claude/CLAUDE.md with a team convention (e.g. "always run the linter before committing") and commit it.
Why: Project level is the only level that reaches everyone who clones the repo.
2
Add a directory-level CLAUDE.md inside one subpackage with a convention that only applies there.
You should see: The directory file loads on demand when Claude works in that subpackage, layered on top of the project file.
3
Deliberately put a second team convention in ~/.claude/CLAUDE.md instead of the project file, then simulate a fresh clone (or a teammate's machine) that lacks it.
You should see: The fresh clone is missing that convention — a live reproduction of the new-hire bug.
4
Run /memory and read which files are loaded; identify the user-level file as the misplaced one.
Why: /memory is the diagnostic tool for hierarchy and inconsistency issues.
5
Move the misplaced convention into .claude/CLAUDE.md, and split the now-larger project file into .claude/rules/ topic files (or @import them).
You should see: Both conventions now travel with the repo, and the config is modular rather than monolithic.

Sources

Claude Code — Memory (CLAUDE.md)Claude Code — Overview

Drill Claude Code Configuration & Workflows

Practice only this domain’s questions, untimed, with instant explanations.