3.1 CLAUDE.md Hierarchy, Scoping, and Modular Organisation

What You Need to Know

Claude Code reads configuration from CLAUDE.md files at three levels. Knowing which one applies where — and spotting when the wrong level was used — comes up again and again on the exam.

The Three-Level Hierarchy

User-level: ~/.claude/CLAUDE.md

This file applies only to you. It lives in your home directory, outside any repository, so it isn’t version-controlled and never travels through git. Clone the repo as a new teammate and you won’t get these instructions. Keep this level for strictly personal preferences: verbosity settings, a preferred output style, your own shortcuts.

Project-level: .claude/CLAUDE.md or root CLAUDE.md

This file applies to everyone on the project. It lives in the repository and is version-controlled, so every developer who clones or pulls the repo gets these instructions automatically. Team-wide standards belong here: naming conventions, error handling patterns, testing requirements, architecture decisions, code review checklists.

Both .claude/CLAUDE.md (inside the .claude directory) and a CLAUDE.md at the repository root are valid project-level locations. The exam may present either path.

Directory-level: subdirectory CLAUDE.md files

These apply when you’re working in that specific directory. Use them for package-specific conventions that differ from the project root. A /packages/api/CLAUDE.md, say, might hold REST conventions that the frontend package never needs.

Loading Order and Conflict Handling

CLAUDE.md files aren’t a strict-precedence config. The Anthropic memory docs are explicit: “All discovered files are concatenated into context rather than overriding each other.” Every applicable file loads into the same context window. None replaces another.

The docs describe a documented load order, not a precedence chain:

Files are ordered from broadest scope to most specific. A project instruction appears in context after a user instruction. Across the directory tree, “content is ordered from the filesystem root down to your working directory,” so “instructions closer to where you launched Claude are read last.”
Within a directory, CLAUDE.local.md is appended after CLAUDE.md, so your personal notes are the last thing Claude reads at that level.

None of this makes it a winner-take-all hierarchy. The docs are blunt about it: “if two rules contradict each other, Claude may pick one arbitrarily.” CLAUDE.md is delivered as a user message — not as part of the system prompt — and Anthropic says “there’s no guarantee of strict compliance.” Treat CLAUDE.md as guidance the model usually follows, not as a configuration layer with deterministic overrides.

The practical consequence: if a rule must hold on every run — a blocked tool, a required formatter, a permission policy — don’t lean on CLAUDE.md scoping to enforce it. Encode it in settings.json (which the client enforces regardless of what Claude decides) or in a hook (which fires at a fixed lifecycle event). The Anthropic docs spell this out directly: “Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude’s behavior but are not a hard enforcement layer.”

Modular Organisation with @ path imports

Past a few hundred lines, one CLAUDE.md becomes a slog to maintain. The @ syntax lets you split it across files and reference them from the main one. The directive is just @ followed by a path. There is no @import keyword, even though half the docs you’ll find online write it that way.

The syntax in your CLAUDE.md:

Coding standards:

@./standards/naming-conventions.md
@./standards/error-handling.md
@./standards/testing-requirements.md

Each @<path> line gets that file inlined into the CLAUDE.md at load time. Per-package CLAUDE.md files can import only the standards that apply to them. The API package pulls in API conventions, the frontend pulls in component rules. No duplication.

One thing the docs are quiet about: imports load eagerly. The referenced file gets inlined the moment Claude reads your CLAUDE.md, exactly as if you’d pasted it in. So splitting a 600-line CLAUDE.md into six 100-line imports makes the source nicer to work in, but the context Claude actually sees is the same size. If you want to shrink per-session context, the tool for the job is .claude/rules/ with path-scoped frontmatter (covered in Task Statement 3.3). Those files only load when Claude is working in matching paths.

CLAUDE.local.md, local-only overrides

CLAUDE.local.md lives next to CLAUDE.md at any level in the hierarchy and loads the same way, with three small differences worth knowing:

Loading order. CLAUDE.local.md is appended after CLAUDE.md at the same level, so your personal notes are the last thing Claude reads there. That’s load order, not precedence: reading last doesn’t win a contradiction. If two instructions conflict, Claude may still pick either one.
Gitignored by convention. The .local suffix flags files you don’t want committed. Most teams add CLAUDE.local.md to .gitignore so personal tweaks stay personal.
What it’s for. The shared CLAUDE.md is the team’s rules. The CLAUDE.local.md next to it is your own quirks for this repo: a favourite scratchpad path, a verbose explanation you keep needing to re-paste, a temporary debugging note you’ll delete next week.

Think of CLAUDE.local.md as a project-scoped version of ~/.claude/CLAUDE.md: same idea, narrower scope. If you find yourself reaching for it to express a team rule, that rule belongs in CLAUDE.md instead.

The .claude/rules/ Directory

As an alternative to a single CLAUDE.md file, the .claude/rules/ directory holds topic-specific rule files:

testing.md — test naming, assertion patterns, fixture usage
api-conventions.md — endpoint naming, request/response schemas
deployment.md — deployment checklist, environment configuration

Each file can optionally include YAML frontmatter with path scoping (covered in detail in Task Statement 3.3). Without frontmatter, rules files load for all sessions.

Diagnosing What Loaded: /memory and /context

When behaviour drifts between sessions, or between developers, you need to see which memory files the session actually picked up. If Claude Code follows the team conventions for one teammate and ignores them for another, that answer settles it.

Current Claude Code splits the job across two commands. /memory lists your CLAUDE.md, CLAUDE.local.md and auto-memory locations, and opens any of them in your editor. /context reports what actually loaded into this session, under Memory files — so to confirm a file is live, run /context and read that list. The docs are explicit about it: “check the list under Memory files to verify your CLAUDE.md and CLAUDE.local.md files loaded”. (Claude Code memory docs, verified August 2026.)

What Survives Compaction

When /compact summarises a long session, project-root CLAUDE.md comes back intact. Not because it sits somewhere privileged. Because Claude re-reads it from disk after compaction and re-injects it, and your instructions were never part of the conversation history to begin with, so there’s nothing there for the summariser to compress.

Two things don’t come back automatically: nested CLAUDE.md files in subdirectories, and .claude/rules/ files with paths: frontmatter. Both load on demand, so they return the next time Claude reads a matching file rather than the moment compaction ends. When an instruction seems to vanish after /compact, that’s usually why. The other candidate is an instruction that only ever existed in conversation, which compaction is free to summarise.

The Critical Exam Scenario: New Team Member Not Receiving Instructions

This is the exam’s favourite trap for Task Statement 3.1. It usually runs like this:

Developer A has been on the team for months. Claude Code follows all the team’s conventions perfectly — API naming, test structure, error handling. Developer B joins the team, clones the repository, and Claude Code produces inconsistent results that ignore the conventions.

The root cause is always the same: the conventions are stored in Developer A’s user-level config (~/.claude/CLAUDE.md) instead of the project-level config (.claude/CLAUDE.md or root CLAUDE.md). User-level config is not shared via git. Developer B never received the instructions.

The fix: move instructions from user-level to project-level configuration.

You need to diagnose this on sight. See “new team member” paired with “inconsistent behaviour”? Check where the configuration lives.

Exam Traps

Practice Scenario

Developer A’s Claude Code follows the team’s API naming conventions perfectly. Developer B, who joined last week, gets inconsistent naming from Claude Code. Both work on the same repo and branch. What is the most likely root cause?

A. Developer B has not run /memory to load the configuration files into the session, so the project-level instructions have never entered the model context
B. The API naming conventions are stored in Developer A’s user-level CLAUDE.md (~/.claude/CLAUDE.md) rather than the project-level configuration
C. Developer B has not yet installed the MCP server that supplies the naming convention rules for the team to the Claude Code session running on their machine
D. The conventions are stored in a .claude/rules/ file that Developer B’s local setup does not support, so the rules never load on their machine

Answer & explanation

Correct: B

A — /memory is a diagnostic tool that shows which files are loaded. It does not trigger loading. Configuration loads automatically based on file location.
B — User-level CLAUDE.md is not version-controlled or shared via git. Developer A has the instructions locally from months of use; Developer B, having just cloned the repo, does not have them. Moving instructions to project-level .claude/CLAUDE.md fixes the issue.
C — MCP servers provide tool integrations, not CLAUDE.md configuration. Naming conventions are configuration, not tools.
D — .claude/rules/ files are inside the repository and version-controlled. If the conventions were there, Developer B would receive them on clone, just like any other version-controlled file.

Sources

How Claude remembers your project (CLAUDE.md and auto memory) — Anthropic
Claude Certified Architect Foundations Exam Guide — Task Statement 3.1 — Anthropic

Exam Simulator

Five exam-style multiple-choice questions on CLAUDE.md Hierarchy, Scoping, and Modular Organisation. Pick an answer, then open the explanation.

Question 1

A. Developer B has not run /memory to load the configuration files
B. Developer B needs to install an MCP server to access the naming convention rules
C. The conventions live in Developer A’s user-level CLAUDE.md, not the project config
D. The conventions are in a .claude/rules/ file that Developer B’s system does not support

Answer & explanation

Correct: C

A is wrong: /memory is a diagnostic tool that shows which files are loaded. It does not trigger loading. Configuration loads automatically based on file location.
B is wrong: MCP servers provide tool integrations, not CLAUDE.md configuration. Naming conventions are configuration, not tools.
C is correct: User-level CLAUDE.md (~/.claude/CLAUDE.md) is not version-controlled or shared via git. Developer A has the instructions locally; Developer B, having just cloned the repo, does not. Moving instructions to project-level config (.claude/CLAUDE.md) fixes this.
D is wrong: .claude/rules/ files are inside the repository and version-controlled. If the conventions were there, Developer B would receive them on clone.

Question 2

A team’s project has grown to include over 200 lines of coding conventions in a single CLAUDE.md file. The file covers naming, testing, deployment, API design, and infrastructure. What is the most maintainable approach to reorganise this?

A. Use the .claude/rules/ directory with topic-specific rule files (testing.md, api-conventions.md, deployment.md)
B. Move all conventions to the user-level ~/.claude/CLAUDE.md so each developer can customise
C. Split the file into multiple CLAUDE.md files in the root directory
D. Create a skill in .claude/skills/ that loads the conventions on demand

Answer & explanation

Correct: A

A is correct: The .claude/rules/ directory holds topic-specific rule files. Each file handles one concern (testing, API, deployment). This is the intended alternative to a monolithic CLAUDE.md.
B is wrong: User-level config is personal and not shared via git. Moving team conventions there means new team members do not receive them.
C is wrong: You cannot have multiple CLAUDE.md files in the same root directory. The .claude/rules/ directory is the designed mechanism for splitting conventions by topic.
D is wrong: Skills load on-demand as task-style workflows, either when you invoke them with /name or when the model picks them up from context. Coding conventions should apply to every edit without relying on invocation, which is what .claude/rules/ and CLAUDE.md provide.

Question 3

A developer runs /memory and discovers that an expected rules file is not showing as loaded. What does this tell them?

A. They need to run /memory again with a –reload flag to force loading
B. They need to restart Claude Code because configuration only loads at startup
C. The /memory command is only available in interactive mode and does not work in their current session
D. Wrong path, broken frontmatter, or a glob pattern that never matches

Answer & explanation

Correct: D

A is wrong: /memory does not have a –reload flag. It is a diagnostic tool only.
B is wrong: Configuration loads based on the files being edited and the hierarchy, not only at startup.
C is wrong: /memory works in the interactive session to show loaded configuration.
D is correct: If a rules file is not loaded, the issue is either that the file is missing, has malformed frontmatter, or (for path-scoped rules) the developer is not editing files that match the glob pattern.

Question 4

A project has packages/api/ with API-specific conventions and packages/frontend/ with component conventions. The team wants each package to follow its own standards without duplicating shared conventions. What is the correct configuration approach?

A. Create a directory-level CLAUDE.md in each package directory with all conventions, including shared ones
B. Project-level CLAUDE.md with an @ path import for shared standards, directory-level for package ones
C. Place all conventions in the user-level config and instruct each developer to copy the right sections
D. Create one skill per package that developers must invoke before working in that directory

Answer & explanation

Correct: B

A is wrong: This duplicates the shared conventions in every package directory, creating maintenance burden and drift risk.
B is correct: the @ path import enables modular organisation. Note the syntax: a line reading @./standards/naming.md, not @import. There is no @import keyword. Shared standards live in one place and are imported where needed. Package-specific conventions live in directory-level CLAUDE.md files. No duplication.
C is wrong: User-level config is personal and not shared via git. This approach fails for new team members.
D is wrong: Skills load on-demand as task-style workflows. Conventions should apply to every edit as always-in-context guidance, which CLAUDE.md (and .claude/rules/ for path-scoped cases) provides.

Question 5

Which of the following is a valid project-level CLAUDE.md location?

A. ~/CLAUDE.md
B. node_modules/.claude/CLAUDE.md
C. /etc/claude/CLAUDE.md
D. .claude/CLAUDE.md in the repository root

Answer & explanation

Correct: D

A is wrong: ~/CLAUDE.md is in the user’s home directory, not inside a repository. It is not the same as ~/.claude/CLAUDE.md (user-level) and would not be recognised.
B is wrong: node_modules/ is for installed dependencies. Configuration inside node_modules is not recognised by Claude Code.
C is wrong: /etc/ is a system directory. Claude Code does not read configuration from system-level paths.
D is correct: .claude/CLAUDE.md inside the repository is one of two valid project-level locations (the other being a root CLAUDE.md file).