CLAUDE.md Hierarchy, Scoping, and Modular Organisation

Official Exam Guide Objectives

Knowledge of

• The CLAUDE.md configuration hierarchy: user-level (~/.claude/CLAUDE.md), project-level (.claude/CLAUDE.md or root CLAUDE.md), and directory-level (subdirectory CLAUDE.md files)
• That user-level settings apply only to that user—instructions in ~/.claude/CLAUDE.md are not shared with teammates via version control
• The @import syntax for referencing external files to keep CLAUDE.md modular (e.g., importing specific standards files relevant to each package)
• .claude/rules/ directory for organizing topic-specific rule files as an alternative to a monolithic CLAUDE.md

Skills in

• Diagnosing configuration hierarchy issues (e.g., a new team member not receiving instructions because they're in user-level rather than project-level configuration)
• Using @import to selectively include relevant standards files in each package's CLAUDE.md based on maintainer domain knowledge
• Splitting large CLAUDE.md files into focused topic-specific files in .claude/rules/ (e.g., testing.md, api-conventions.md, deployment.md)
• Using the /memory command to verify which memory files are loaded and diagnose inconsistent behavior across sessions

What You Need to Know

Claude Code picks up CLAUDE.md files from three places, and a surprising number of exam items reduce to noticing that a rule was written at the wrong one. Knowing what each level reaches — and what it cannot — is most of this task statement.

The Three-Level Hierarchy

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

Yours alone. It sits in your home directory rather than in any repository, which means git never sees it and it never reaches anybody else. A new teammate cloning the project inherits none of it. Reserve this level for things that are genuinely about you: how verbose you like responses, an output style you prefer, shortcuts nobody else would want.

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

Everyone's. It is committed with the code, so cloning or pulling the repository brings it along automatically for every developer. Anything the team has agreed on belongs here — naming conventions, how errors are handled, what testing is expected, architectural decisions, the review checklist.

Two paths are equally valid at this level: CLAUDE.md sitting at the repository root, or .claude/CLAUDE.md inside the .claude directory. Exam items use both, so neither is a signal that something is wrong.

Directory-level: subdirectory CLAUDE.md files

Scoped to work happening in that part of the tree. These carry conventions that are real for one package and irrelevant elsewhere — REST conventions in /packages/api/CLAUDE.md, say, which the frontend package has no use for.

Loading Order and Conflict Handling

It is tempting to read three levels as three tiers of precedence. That is not how CLAUDE.md behaves, and the Anthropic memory docs say so directly: "All discovered files are concatenated into context rather than overriding each other." Everything applicable ends up in the same context window together, and nothing displaces anything.

What the docs describe is a load order — the sequence in which files arrive — rather than a chain of overrides:

1. Ordering runs from broadest scope to most specific, so a project instruction lands in context after a user instruction. Down the directory tree, "content is ordered from the filesystem root down to your working directory," which means "instructions closer to where you launched Claude are read last."
2. At any one level, CLAUDE.local.md follows CLAUDE.md, putting your personal notes last in that directory.

Arriving later is not the same as winning. On this the docs leave no room: "if two rules contradict each other, Claude may pick one arbitrarily." CLAUDE.md reaches the model as a user message rather than as part of the system prompt, and Anthropic states plainly that "there's no guarantee of strict compliance." It is guidance that is usually followed — not a configuration layer resolving conflicts deterministically.

Which has a practical consequence worth carrying into the exam. Where a rule has to hold on every single run — a tool that must stay blocked, a formatter that must run, a permission that must not be granted — scoping it into the right CLAUDE.md does not make it binding. Put it in settings.json, which the client applies whatever the model concludes, or in a hook, which fires at a fixed point in the lifecycle. The docs state the division outright: "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

Once a CLAUDE.md runs past a few hundred lines it stops being pleasant to maintain, and the @ syntax exists to break it apart. A line is just @ followed by a path — there is no @import keyword, whatever a good proportion of the write-ups online show.

The syntax in your CLAUDE.md:

# .claude/CLAUDE.md

Coding standards:

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

Every @<path> pulls that file inline as the CLAUDE.md loads. Because each package's CLAUDE.md imports only what it needs, the API package takes the API conventions and the frontend takes the component rules, with nothing written twice.

Here is the part the docs skip over, and it matters for context budgeting: imports resolve eagerly. The referenced file is inlined the instant Claude reads the CLAUDE.md, exactly as though you had pasted it there yourself. Breaking 600 lines into six files of 100 improves the editing experience and leaves the context Claude receives precisely as large as before. Shrinking what actually loads per session is a different tool — .claude/rules/ with path-scoped frontmatter, covered in Task Statement 3.3, where files load only when the paths match.

CLAUDE.local.md, local-only overrides

CLAUDE.local.md sits beside CLAUDE.md at any level and loads by the same mechanism. Three differences are worth holding:

• Loading order. It arrives after the CLAUDE.md beside it, giving it the final word within that directory — subject, still, to conflicts resolving arbitrarily.
• Gitignored by convention. The .local suffix signals "not for committing", and most teams add it to .gitignore so private adjustments stay private.
• What it's for. The committed CLAUDE.md carries what the team agreed; the CLAUDE.local.md beside it carries what only you need here — a scratch directory you favour, an explanation you are tired of retyping, a debugging note with a short life expectancy.

The clean way to think about it: CLAUDE.local.md is ~/.claude/CLAUDE.md narrowed to one repository. Reaching for it to express something the whole team should follow is a signal that the rule belongs in CLAUDE.md instead.

The .claude/rules/ Directory

Rather than one CLAUDE.md carrying everything, .claude/rules/ holds a file per topic:

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

Any of these may carry YAML frontmatter that scopes it to particular paths, which Task Statement 3.3 covers properly. A rules file without frontmatter simply loads for every session.

The /memory Command

/memory reports which memory files the current session actually has. It earns its place when behaviour drifts — between two sessions, or between two developers running what should be identical setups — because it answers the question underneath most of those puzzles: are the files you assume are loaded genuinely loaded?

The Critical Exam Scenario: New Team Member Not Receiving Instructions

This is the exam's favourite trap for Task Statement 3.1, and the setup barely varies:

Someone who has been on the team a while gets exactly the behaviour they expect — API naming, test structure, error handling all followed. A new joiner clones the same repository, checks out the same branch, and gets output that ignores every one of those conventions.

The cause is the same every time. Those conventions live in the long-standing developer's own ~/.claude/CLAUDE.md, not in the repository's .claude/CLAUDE.md or root CLAUDE.md. Nothing at user level travels through git, so the new joiner never received any of it — and never could have, on any branch.

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

Learn to recognise it from the pairing alone. A new team member plus inconsistent behaviour, with the repository and branch confirmed identical, points at where the configuration lives rather than at anything in the code.

Deep Dive

settings.json: the precedence chain CLAUDE.md doesn't have

CLAUDE.md files concatenate; settings.json files don't — they resolve through a genuine five-level precedence order, highest to lowest: managed (enterprise policy, can't be overridden by anything) → command line arguments (temporary session overrides) → local (overrides project and user) → project (overrides user) → user (lowest, applies only when nothing else specifies the setting). A project actually has two settings files: .claude/settings.json for settings checked into source control and shared with the team, and .claude/settings.local.json for settings that are not checked in — personal preferences and experimentation.

Sourcecode.claude.com › settingsfetched 2026-07-30

settings.json locations, including the enterprise managed path

User-scope settings live at ~/.claude/settings.json and apply across all projects. Enterprise managed settings (managed-settings.json) load from an OS-specific path that individual users can't touch: /Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, and C:\Program Files\ClaudeCode\ on Windows.

Sourcecode.claude.com › settingsfetched 2026-07-30

The fourth CLAUDE.md scope: managed policy

Beyond the user/project/directory levels introduced above, Claude Code recognises a fourth scope: managed policy, loaded from the same OS-specific system paths as managed settings (e.g. /etc/claude-code/CLAUDE.md on Linux/WSL, C:\Program Files\ClaudeCode\CLAUDE.md on Windows). A managed policy CLAUDE.md is organisation-deployed, applies to every session on the machine, and "cannot be excluded" by any individual setting — it always applies, "regardless of individual settings."

Sourcecode.claude.com › memoryfetched 2026-07-30

@import mechanics: depth limit and what parsing skips

Imports recurse — an imported file can itself import others — but only to a maximum depth of four hops in current docs (older documentation said five; see the divergence log). Import parsing deliberately skips Markdown code spans and fenced code blocks, so wrapping a path in backticks lets you mention it in prose without triggering an import of it.

Sourcecode.claude.com › memoryfetched 2026-07-30

Sharing personal preferences across worktrees

CLAUDE.local.md is scoped to a single working-tree checkout, so it doesn't follow you into a git worktree of the same repo. To share personal instructions across worktrees, import a file from your home directory instead of relying on CLAUDE.local.md — e.g. a line reading @~/.claude/my-project-instructions.md inside the project CLAUDE.md.

Sourcecode.claude.com › memoryfetched 2026-07-30

/init and the 200-line size guidance

/init generates a starting CLAUDE.md by analysing the codebase: it creates a file with build commands, test instructions, and conventions it discovers, and if a CLAUDE.md already exists, /init suggests improvements rather than overwriting it. Separately, the docs recommend keeping each CLAUDE.md under 200 lines, since "longer files consume more context and reduce adherence" — the same argument that motivates splitting into .claude/rules/.

Sourcecode.claude.com › memoryfetched 2026-07-30

Quick Reference

Exam Traps

Practice Scenario

Build Exercise

Build a Multi-Level CLAUDE.md Configuration

Difficulty: Beginner (1/4)

30 minutes

1. Create a project-level .claude/CLAUDE.md with universal coding standards: naming conventions, error handling patterns, and a code review checklist

Why: Project-level configuration is the foundation of team-wide standards. The exam tests whether you place shared conventions here rather than in user-level config, which is the most common misconfiguration scenario.

You should see: A .claude/CLAUDE.md file at the repository root containing at least three sections: naming conventions, error handling patterns, and a code review checklist. Running /memory in the project root shows this file as loaded.

2. Create a directory-level CLAUDE.md in a /packages/api/ subdirectory with API-specific conventions (REST endpoint naming, request/response schema requirements)

Why: Directory-level configuration scopes conventions to a specific package. The exam tests whether you know that directory-level CLAUDE.md applies only within that directory, not across the entire project.

You should see: A CLAUDE.md file inside /packages/api/ containing REST-specific conventions. When you run /memory while working in /packages/api/, both the project-level and directory-level files appear as loaded.

3. Create .claude/rules/testing.md with test-specific conventions (test naming pattern, assertion style, fixture usage)

Why: The .claude/rules/ directory holds topic-specific rule files that can optionally include YAML frontmatter for path scoping. Understanding this mechanism is tested alongside path-specific rules in Task Statement 3.3.

You should see: A testing.md file inside .claude/rules/ containing at least three test conventions. Running /memory shows this rules file as loaded in your session.

4. Use an @ path import in the project-level CLAUDE.md to reference a shared standards file at ./standards/naming.md

Why: The @ import syntax enables modular organisation of conventions. There is no @import keyword — a path prefixed with @ on its own line is the import. Each package can import only relevant standards, reducing duplication and drift in the source files. The exam tests whether you know the mechanism exists and how the syntax actually looks.

You should see: The project-level .claude/CLAUDE.md contains a line beginning with @ pointing to ./standards/naming.md. A separate file at .claude/standards/naming.md (or standards/naming.md relative to the CLAUDE.md) exists with naming conventions. Running /memory confirms the imported content is loaded inline.

5. Run /memory in different directories to verify the correct files are loaded in each context

Why: The /memory command is the diagnostic tool for verifying which configuration files are active. The exam specifically tests that /memory reveals loaded files but does not trigger loading — configuration loads automatically based on location.

You should see: In the project root, /memory shows the project-level CLAUDE.md and rules files. In /packages/api/, /memory additionally shows the directory-level CLAUDE.md. The imported standards file content appears as part of the project-level configuration.

6. Move one convention from project-level to user-level (~/.claude/CLAUDE.md) and verify that a different user session does NOT pick it up — confirming the scoping boundary

Why: This is the exam favourite trap scenario. When conventions live in user-level config, new team members who clone the repo do not receive them. Proving this boundary experimentally cements the concept.

You should see: After moving a convention to ~/.claude/CLAUDE.md, your own /memory shows it loaded. A simulated second user session (or a fresh clone without your home directory config) does NOT show that convention. This confirms the scoping boundary.

Sources

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

Appendix A — Build Exercise Step Hints

Progressive hints revealed by the "Stuck? Get a nudge" control on each step.

Step 1. Create a project-level .claude/CLAUDE.md with universal coding standards: naming conventions, error handling patterns, and a code review checklist

Why: Project-level configuration is the foundation of team-wide standards. The exam tests whether you place shared conventions here rather than in user-level config, which is the most common misconfiguration scenario.

You should see: A .claude/CLAUDE.md file at the repository root containing at least three sections: naming conventions, error handling patterns, and a code review checklist. Running /memory in the project root shows this file as loaded.

Create the file at .claude/CLAUDE.md with content like:
# Coding Standards

## Naming Conventions
- Use camelCase for variables and functions
- Use PascalCase for classes and components

## Error Handling
- Always use typed error classes
- Never swallow exceptions silently

## Code Review Checklist
- Verify test coverage for new functions
- Check for hardcoded credentials

Step 2. Create a directory-level CLAUDE.md in a /packages/api/ subdirectory with API-specific conventions (REST endpoint naming, request/response schema requirements)

Why: Directory-level configuration scopes conventions to a specific package. The exam tests whether you know that directory-level CLAUDE.md applies only within that directory, not across the entire project.

You should see: A CLAUDE.md file inside /packages/api/ containing REST-specific conventions. When you run /memory while working in /packages/api/, both the project-level and directory-level files appear as loaded.

Create packages/api/CLAUDE.md with content like:
# API Conventions

- Use kebab-case for REST endpoint paths
- All responses must follow the shape: { data, error, metadata }
- Validate all request bodies with Zod schemas at the handler boundary

Step 3. Create .claude/rules/testing.md with test-specific conventions (test naming pattern, assertion style, fixture usage)

Why: The .claude/rules/ directory holds topic-specific rule files that can optionally include YAML frontmatter for path scoping. Understanding this mechanism is tested alongside path-specific rules in Task Statement 3.3.

You should see: A testing.md file inside .claude/rules/ containing at least three test conventions. Running /memory shows this rules file as loaded in your session.

Create .claude/rules/testing.md with content like:
# Test Conventions

- Name tests using the pattern: describe("ModuleName") > it("should behaviour when condition")
- Use factory functions for test data, not inline literals
- Mock external services at the module boundary

Step 4. Use an @ path import in the project-level CLAUDE.md to reference a shared standards file at ./standards/naming.md

Why: The @ import syntax enables modular organisation of conventions. There is no @import keyword — a path prefixed with @ on its own line is the import. Each package can import only relevant standards, reducing duplication and drift in the source files. The exam tests whether you know the mechanism exists and how the syntax actually looks.

You should see: The project-level .claude/CLAUDE.md contains a line beginning with @ pointing to ./standards/naming.md. A separate file at .claude/standards/naming.md (or standards/naming.md relative to the CLAUDE.md) exists with naming conventions. Running /memory confirms the imported content is loaded inline.

First create .claude/standards/naming.md with your naming rules, then add this line to .claude/CLAUDE.md:
@./standards/naming.md

Step 5. Run /memory in different directories to verify the correct files are loaded in each context

Why: The /memory command is the diagnostic tool for verifying which configuration files are active. The exam specifically tests that /memory reveals loaded files but does not trigger loading — configuration loads automatically based on location.

You should see: In the project root, /memory shows the project-level CLAUDE.md and rules files. In /packages/api/, /memory additionally shows the directory-level CLAUDE.md. The imported standards file content appears as part of the project-level configuration.

Run these commands in sequence:
1. cd /your-project && /memory
2. cd /your-project/packages/api && /memory
Compare the output lists to confirm directory-level scoping.

Step 6. Move one convention from project-level to user-level (~/.claude/CLAUDE.md) and verify that a different user session does NOT pick it up — confirming the scoping boundary

Why: This is the exam favourite trap scenario. When conventions live in user-level config, new team members who clone the repo do not receive them. Proving this boundary experimentally cements the concept.

You should see: After moving a convention to ~/.claude/CLAUDE.md, your own /memory shows it loaded. A simulated second user session (or a fresh clone without your home directory config) does NOT show that convention. This confirms the scoping boundary.

Move a rule to ~/.claude/CLAUDE.md:
# Personal Preferences
- Always use verbose variable names

Then verify: your /memory shows it, but a colleague cloning the repo fresh will not see it in their /memory output.

Appendix B — Interactive Study Prompts

Two prompts to paste into Claude. B1 drills the judgement the exam actually measures; B3 reviews the configuration you wrote for the Build Exercise above. The exam simulator between them is the interactive quiz on this page.

B1. Concept Check — Discrimination Drill

B2. Exam Simulator

B3. Build Coach — Config Review

The Build Exercise and its hint ladder are already on this page. This prompt is for the one thing the page cannot do: review the configuration you actually wrote.