Rubric
Contents — domains, guide and mocks

CLAUDE.md hierarchy and organisation

CCAR-F 3.111 min read · checked 21 September 2026

Task statementConfigure CLAUDE.md files with appropriate hierarchy, scoping, and modular organization

Where CLAUDE.md files live, in load order

loaded first → loaded last

  1. Managed policye.g. /etc/claude-code/CLAUDE.md — every user on the machine; cannot be excluded
  2. User~/.claude/CLAUDE.md — just you, every project; not in git
  3. Project./CLAUDE.md or ./.claude/CLAUDE.md — the team, via version control
  4. Local./CLAUDE.local.md — just you, this project; add to .gitignore
  5. Subdirectorysrc/api/CLAUDE.md — loaded on demand when Claude reads files there
All of these are concatenated, not chosen between. Broadest scope loads first; the files nearest your working directory are read last. Only the project file reaches teammates through git.

The four scopes, and who sees each

Claude Code reads CLAUDE.md files from several places, each with a different audience. The scope you choose is really a decision about who the instruction is for. Get it wrong and the instruction either reaches nobody who needs it or reaches people who don’t.

ScopeLocationWho gets itPut here
Managed policyOS-specific path, deployed by IT (MDM, Group Policy, Ansible)Every user on the machineCompany-wide standards, compliance reminders
User~/.claude/CLAUDE.mdOnly you, in every projectPersonal style and tooling preferences
Project./CLAUDE.md or ./.claude/CLAUDE.mdEveryone who clones the repoBuild and test commands, architecture, team conventions
Local./CLAUDE.local.md (gitignored)Only you, in this projectYour sandbox URLs, preferred test data

The user file is where team-wide instructions most often get lost. It sits in your home directory, so it never goes into git. A convention you wrote there will be followed on your laptop and nowhere else — including in CI, and on the new starter’s machine. If a rule should apply to everyone working on the repository, it belongs in the project file and gets committed.

How the files combine

Files do not override each other. Claude Code walks from the filesystem root down to the directory you launched from, loading every CLAUDE.md and CLAUDE.local.md it finds, and concatenates them. Start Claude in repo/packages/api/ and it loads repo/CLAUDE.md and repo/packages/api/CLAUDE.md, with the closer file read later. Within a directory, CLAUDE.local.md comes after CLAUDE.md.

Subdirectories below where you started behave differently: their CLAUDE.md files are not loaded at launch. They are pulled in on demand, when Claude reads a file in that subdirectory. This is what makes per-directory files cheap — the frontend team’s conventions cost nothing while Claude works in the backend.

Modular organisation: imports, rules and per-directory files

A single root CLAUDE.md tends to grow until it covers every subsystem. The documentation’s target is under 200 lines per file, because longer files consume more context and reduce adherence. There are three ways to split one up, and they do different things.

MechanismHow it worksSaves context?
@path import@docs/git-workflow.md inside a CLAUDE.md pulls that file in at launchNo — imported files load at launch too
.claude/rules/*.mdOne topic per file; files without paths frontmatter load at launch like the project fileOnly when scoped with paths (see 3.3)
Per-directory CLAUDE.mdLives beside the code it describes; owned by that teamYes — loads only when Claude works there

Imports are for organisation and reuse: pointing at an existing README, a package.json, or a shared file. Relative paths resolve from the file that contains the import, not from where you launched, and imports can nest up to four hops deep. A path inside backticks is not imported, which lets you mention a file without loading it. The first time a project imports a file from outside the working directory, Claude Code asks for approval.

A lean project CLAUDE.md that imports detailtext
# Project overview
See @README.md for the architecture and @package.json for scripts.

# Commands
- Build: npm run build
- Single test file: npm test -- path/to/file.test.ts

# Conventions
- API handlers live in src/api/handlers/
- Never edit files under generated/ — run npm run codegen

# Detail
- Git workflow: @docs/claude/git-workflow.md
- Release checklist lives in a skill (/release), not here

One bloated file versus a modular set

Weak: one 600-line root filetext

# CLAUDE.md
- Write clean code
- I like short commit messages
- My staging URL: dev-sam.internal
- React components: (80 lines)
- SQL migration rules: (90 lines)
- Release procedure: 40 steps
- File-by-file tour of src/
- IMPORTANT: ... (x25)

Strong: split by audiencetext

./CLAUDE.md (60 lines, committed)
  commands, layout, team rules
  @docs/claude/git-workflow.md
.claude/rules/react.md (paths)
.claude/rules/migrations.md (paths)
.claude/skills/release/SKILL.md
CLAUDE.local.md (gitignored)
  my staging URL
~/.claude/CLAUDE.md
  short commit messages
The weak version mixes team rules, personal habits and a long procedure in one always-loaded file. The strong version keeps the root short and moves each item to the scope and mechanism that fits it.

What to put in, and what to leave out

CLAUDE.md earns its place with facts Claude needs in every session and cannot work out from the code: commands it can’t guess, style rules that differ from defaults, repository etiquette, architectural decisions, environment quirks and known gotchas. It should not contain things Claude can derive by reading the code, standard language conventions, long tutorials, frequently changing information, or a file-by-file tour. The documentation’s test for each line is whether removing it would cause mistakes.

Where does this instruction belong?

What kind of instruction is it?
  • Every session, whole team
    Project CLAUDE.mdcommitted to git
  • Only for some files
    Path-scoped ruleor a subdirectory CLAUDE.md
  • A multi-step procedure
    Skillloads when invoked (3.2)
  • Must happen, no exceptions
    Hook or deny ruleenforced, not advisory

Checking what actually loaded

  • /context — shows which CLAUDE.md and rules files are in the current session, under Memory files. If a file isn’t listed, Claude can’t see it.
  • /memory — lists CLAUDE.md, CLAUDE.local.md and other memory locations across user and project scopes, and opens any of them in your editor.
  • /init — generates a starter CLAUDE.md from the codebase, or suggests improvements to an existing one.
  • The InstructionsLoaded hook — logs which files loaded, when and why; useful for debugging on-demand files.

Two behaviours are worth knowing when instructions seem to vanish. After /compact, the project-root CLAUDE.md is re-read from disk, but nested files and path-scoped rules only return when Claude next reads a matching file. And an instruction you only typed into chat is lost at compaction — if it should persist, it belongs in a CLAUDE.md.

Traps the wrong answers are built from

Tempting but wrongDo this instead
Putting team conventions in ~/.claude/CLAUDE.mdCommit them to the project CLAUDE.md so every clone, including CI, gets them.
One ever-growing root CLAUDE.md covering every subsystemKeep the root short; move area-specific conventions to per-directory files or path-scoped rules.
Splitting a big file into @imports to save contextImports organise but still load at launch; use path-scoped rules, subdirectory files or skills to defer loading.
Counting on the more specific file to win a contradictionFiles are concatenated and conflicts are resolved by judgement; remove the conflict instead.
Writing a hard requirement as a CLAUDE.md line in capitalsEnforce it with a hook or a permissions.deny rule; keep CLAUDE.md for guidance.

You should now be able to

  • Place an instruction at the managed, user, project, local or subdirectory level according to who needs it.
  • Explain that CLAUDE.md files concatenate from the root down, with subdirectory files loading on demand.
  • Split an oversized CLAUDE.md using imports, .claude/rules/ and per-directory files, knowing which of these actually save context.
  • Diagnose a missing instruction with /context and /memory.
  • Recognise when a requirement needs a hook or permission rule rather than CLAUDE.md.

Practice questions

Original questions written for this lesson, in the exam’s style. Answer first, then open the reasoning — every option is explained, including why the wrong ones are tempting.

  1. Question 1

    A platform team’s Claude Code sessions follow the house error-handling convention, but the same repository’s nightly CI job, which runs Claude Code headlessly, ignores it. The convention was written by the team lead months ago.

    What is the most likely cause?

    1. AThe CI job uses a different model that ignores CLAUDE.md files.
    2. BHeadless mode never loads any CLAUDE.md files from the repository.
    3. CThe convention lives in the lead’s user-level ~/.claude/CLAUDE.md, not the committed project file.
    4. DThe convention needs to be repeated with IMPORTANT in capitals to apply in CI.
    Show answer and reasoning
    1. AIncorrect. CLAUDE.md is loaded as context regardless of model; the problem is whether the file is present at all.
    2. BIncorrect. Tempting, but project CLAUDE.md files are part of a normal session; there’s no blanket rule that non-interactive runs skip them.
    3. CCorrect. User-level files sit in a home directory and never reach version control, so the CI checkout never sees them. Moving the rule to the project CLAUDE.md fixes every environment.
    4. DIncorrect. Emphasis can help an instruction that is present but overlooked; it cannot help one that isn’t loaded.

  2. Question 2

    A healthcare startup’s root CLAUDE.md has grown to 700 lines: general rules, 200 lines of React guidance, 150 lines on database migrations and a long release procedure. Engineers report that Claude often ignores rules near the bottom.

    Which two changes will most reduce what loads into every session while keeping the guidance available? (Select 2.)

    1. AMove the React and migration guidance into rule files scoped with paths frontmatter.
    2. BMove the release procedure into a skill that loads when it is invoked.
    3. CSplit the file into five @imports referenced from a short root file.
    4. DCopy the whole file into each developer’s ~/.claude/CLAUDE.md.
    5. EAdd IMPORTANT to every line near the bottom of the file.
    Show answer and reasoning
    1. ACorrect. Path-scoped rules load only when Claude works with matching files, so that guidance stops costing context in unrelated sessions.
    2. BCorrect. A multi-step procedure used occasionally is exactly what skills are for; only its short description sits in context until it’s needed.
    3. CIncorrect. Imports make the file easier to maintain, but imported files still load at launch, so the context cost is unchanged.
    4. DIncorrect. This duplicates the problem on every machine and takes the rules out of version control.
    5. EIncorrect. Emphasis on many lines means none stands out; the file is still too long.

  3. Question 3

    Claude Code is launched in repo/services/billing/. Which CLAUDE.md files are in context at launch?

    1. AOnly repo/services/billing/CLAUDE.md, because the most specific file replaces the others.
    2. BEvery CLAUDE.md from repo/ down to repo/services/billing/, plus user and managed files.
    3. CEvery CLAUDE.md in the repository, including the one in repo/services/ledger/.
    4. DOnly repo/CLAUDE.md, because Claude Code always resolves from the git root.
    Show answer and reasoning
    1. AIncorrect. Files don’t replace each other; they are concatenated.
    2. BCorrect. Claude Code loads every CLAUDE.md from the working directory and each directory above it at launch, alongside user and managed files.
    3. CIncorrect. Sibling and child directories are not loaded at launch; a subdirectory file under the working directory loads only when Claude reads files there.
    4. DIncorrect. Ancestors are loaded, but so is the working directory’s own file and everything between.

  4. Question 4

    An insurer’s security team requires that Claude Code never reads files in secrets/ on any developer machine. A developer proposes adding “Never open anything in secrets/” to the managed-policy CLAUDE.md.

    What is the best response?

    1. AAgree, because the managed-policy CLAUDE.md cannot be excluded by users.
    2. BPut it in each project’s CLAUDE.md so it is under version control.
    3. CEnforce it with a Read deny rule in managed settings; CLAUDE.md can explain why.
    4. DPut it in CLAUDE.local.md on every machine so that it is read last of all.
    Show answer and reasoning
    1. AIncorrect. It can’t be excluded, but it is still guidance that Claude tries to follow, not an enforced block.
    2. BIncorrect. Version control doesn’t make an instruction enforceable; it is still advisory context.
    3. CCorrect. Settings rules are enforced by the client regardless of what Claude decides; managed settings can’t be overridden by users. CLAUDE.md can carry the rationale.
    4. DIncorrect. Load order doesn’t turn guidance into enforcement, and a local file is per-developer and easy to omit.

Practise every question in Domain 3 →

Sources

Drafted with AI assistance and checked against the sources above; expert review is in progress. Spotted an error? Tell us and it gets fixed, dated and listed on how this is written.