CertSafari
    Anthropic Claude Certified Architect – Foundations (CCAR-F)· Lessons

    Domain 3 · Lesson 13/30

    CLAUDE.md hierarchy, scope, imports and rules files

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

    20 min read
    3.33% of exam
    7 sources
    Published 17 Nov 2026
    Docs as of 11 Nov 2026

    What you will be able to do

    • Place an instruction at the right CLAUDE.md level (managed, user, project, local, directory) based on who must receive it
    • Name the user, project and directory levels of the CLAUDE.md hierarchy and say which load at launch and which on demand
    • Diagnose a teammate who is missing instructions that live in someone's user-level ~/.claude/CLAUDE.md
    • Predict which CLAUDE.md files load at launch and which load on demand in a monorepo
    • Use @path imports and .claude/rules/ topic files to keep instructions modular, and know what each costs in context
    • Use /memory to check which memory files a session is actually using

    Key concept

    Scope follows location — Where a CLAUDE.md file is stored sets who receives it and when it loads. A file in your home directory reaches only you. A file committed to the repository reaches the whole team. A file in a subdirectory loads only when Claude works there.

    1.Where CLAUDE.md files live and who receives them

    CLAUDE.md is a plain markdown file of standing instructions that Claude Code reads without being asked. It works like the briefing you would give a new teammate: how the team does things, what to avoid, and where the important pieces live. You never attach it to a prompt. If the file exists in a location Claude Code reads, Claude already has it.

    Claude Code looks in several locations and combines what it finds, from broad to specific. Each location has a different audience, so choosing where to put an instruction is really choosing who receives it. Imagine 'Use 2-space indentation' saved in four different places: it would reach four different groups of people.

    CLAUDE.md scopes, where each lives, and who receives it
    ScopeLocationShared withTypical content
    Managed policymacOS: /Library/Application Support/ClaudeCode/CLAUDE.md; Linux and WSL: /etc/claude-code/CLAUDE.md; Windows: C:\Program Files\ClaudeCode\CLAUDE.mdAll users in organizationCompany coding standards, security policies, compliance requirements
    User~/.claude/CLAUDE.mdOnly you (all projects)Code styling preferences, personal tooling shortcuts
    Project./CLAUDE.md or ./.claude/CLAUDE.mdTeam members via source controlProject architecture, coding standards, common workflows
    Local./CLAUDE.local.md (add to .gitignore)Only you (current project)Your sandbox URLs, preferred test data
    Directory<subdir>/CLAUDE.mdWhoever works in that subdirectoryModule-specific rules, such as different conventions in frontend/ and api/

    The project file is the main one. You can start it with /init: Claude explores the codebase and drafts a CLAUDE.md with build commands, test commands, a structure overview and the conventions it detects. Review the draft, remove anything inaccurate, and commit it. Keep each file under about 200 lines, because longer files take up more context and Claude follows them less reliably.

    Managed policy is the only scope that individuals and teams cannot opt out of. IT or DevOps writes the managed CLAUDE.md and the managed-settings.json file to system-level locations on each machine, using the organization's configuration management system. Managed settings take precedence over every settings file and every --settings value, with a few narrow exceptions. Neither a project's committed files nor a developer's personal files can override them. Committing a CLAUDE.md to every repository does not achieve the same thing. It misses any repository nobody remembered, and the team that owns the file can edit it.

    Within managed policy, enforcement belongs in settings and behavioral guidance belongs in the managed CLAUDE.md
    ConcernConfigure in
    Block specific tools, commands, or file pathsManaged settings: permissions.deny
    Enforce sandbox isolationManaged settings: sandbox.enabled
    Code style and quality guidelinesManaged CLAUDE.md
    Data handling and compliance remindersManaged CLAUDE.md
    Behavioral instructions for ClaudeManaged CLAUDE.md

    Checkpoint 1 of 9· Match them up

    A team lead saves the instruction 'Use 2-space indentation' in each of these files. Match each file to the people who will receive that instruction.

    Tap a term, then the definition that fits it.

    Checkpoint 2 of 9· Exam question

    An architect is designing a configuration strategy for a company rolling out Claude Code to all engineering teams. They need security and compliance instructions that every developer receives on every machine, in every repository, and that individual developers or teams cannot disable through their own settings. Which approach satisfies this requirement?

    Sources123

    2.The CLAUDE.md hierarchy and diagnosing a teammate who is missing instructions

    Claude Code builds its instructions from a hierarchy of CLAUDE.md files, and the level a file sits at decides who receives it. At the broad end is the user level, ~/.claude/CLAUDE.md, which applies to every project on your machine and to no one else. Next is the project level, ./CLAUDE.md or ./.claude/CLAUDE.md, which teammates receive through version control. At the specific end is the directory level: a CLAUDE.md inside a subdirectory such as frontend/ or api/, holding rules for that module. Claude merges what it finds from broad to specific.

    The levels also differ in when they load. The user file and the project files at and above the working directory are read at session start. A directory-level file below the working directory loads on demand, once Claude reads files in that subdirectory. A rule in api/CLAUDE.md is therefore absent from a session that never touches api/, which is expected behavior and not a fault.

    The scope mistake you will see most often is a team convention saved in someone's user-level file. Suppose a senior engineer writes 'run the integration suite before opening a PR' into ~/.claude/CLAUDE.md. Claude follows it in every one of their sessions, so the rule seems to work. A new hire clones the repository and Claude never mentions the integration suite. The rule was never in the repository. It sits in one person's home directory, and version control does not carry it.

    The fix is to move the instruction, not reword it. Put the convention in ./CLAUDE.md or ./.claude/CLAUDE.md and commit it, so the team receives it the same way it receives code. Leave genuinely personal preferences, such as 'I use pnpm, not npm', in the user file. They follow you into every project and should not be forced on anyone else.

    Personal notes about a single project go in CLAUDE.local.md at the project root. It loads alongside the project CLAUDE.md, and you add it to .gitignore so it stays out of the shared history. It suits your sandbox URLs or the test data you prefer. It is the wrong home for anything a teammate needs, because they will never receive it.

    To diagnose an instruction that reaches one person and not another, work down the hierarchy:

    1. On the machine where the rule works, find which file it comes from.
    2. Read its level. A user-level file or CLAUDE.local.md never travels with the repository, so the teammate cannot have it.
    3. If it is a directory-level file, check whether the teammate's session ever worked in that subdirectory, since the file loads only there.
    4. If the whole team needs the rule, move it into a committed project file.

    Checkpoint 3 of 9· Check yourself

    After cloning the repository, a new hire notices that Claude never runs the integration suite before opening a PR. A senior engineer says Claude does this reliably in their sessions, because the rule is in their ~/.claude/CLAUDE.md. What fixes this for the new hire?

    Sources13

    3.Which files load at launch and which load on demand

    Not every CLAUDE.md loads when the session starts. At session start, Claude Code reads the files in your working directory and in every directory above it. A CLAUDE.md in a subdirectory below where you started loads later, when Claude reads files in that subdirectory. Once loaded, a file is not re-read from disk on each turn and is not summarized or truncated.

    Where you start Claude Code decides which CLAUDE.md files load at launch
    Start fromCLAUDE.md loaded at launchUse when
    Repository rootRoot only; subdirectory files load on demandTasks span multiple packages or subsystems
    A subdirectoryThat directory’s plus every ancestor’sWork is scoped to one package or subsystem

    This makes a per-package CLAUDE.md the natural home for conventions that matter only inside one package. In a monorepo with packages/api, packages/web and packages/shared, the root CLAUDE.md holds what applies everywhere, such as coding standards and commit conventions. packages/api/CLAUDE.md holds the api team's database and testing rules. A session started in packages/api loads both files. A session started at the root loads the api file only once Claude opens a file under packages/api. The api maintainer owns that file, and it is versioned alongside the code it describes.

    Two common alternatives defeat this. If the root CLAUDE.md imports @packages/api/CLAUDE.md, the api conventions load at launch in every session, because an imported file loads with the file that imports it. If the conventions go in a .claude/rules/ file with no paths: frontmatter, they load with the project instructions in every session, not just api work. Gating a rule to file patterns is covered in path-specific rules.

    A monorepo where unrelated packages clutter the context has another tool. The claudeMdExcludes setting takes glob patterns, so you can skip the CLAUDE.md files of packages you never work in. The pattern **/packages/*/CLAUDE.md, for example, excludes every package's file while keeping the root. Excludes are a setting, though, so they need to be configured somewhere. When the clutter comes from a root file importing every package's CLAUDE.md, the cleaner fix is to delete those imports and let each package's file load on demand.

    A claudeMdExcludes setting that skips one package's instructions and rulesjson
    {
      "claudeMdExcludes": [
        "**/packages/web/**"
      ]
    }

    Checkpoint 4 of 9· Check yourself

    In a monorepo, the root CLAUDE.md contains the line @packages/api/CLAUDE.md. A developer starts Claude Code at the repository root and edits files only under packages/web. What happens to the api team's conventions in this session?

    Checkpoint 5 of 9· Exam question

    A platform team maintains a monorepo with packages/api, packages/web, and packages/shared. The api package's maintainer wants api-specific database and testing conventions to load only when someone is actively working in packages/api, without duplicating those conventions into the root CLAUDE.md. Which approach best satisfies this requirement?

    Sources32

    4.Composing a CLAUDE.md with @path imports

    An @path reference inside a CLAUDE.md pulls another file's contents in alongside it. This lets you keep standards in separate files, such as API conventions or git workflow, and assemble each package's CLAUDE.md from only the ones that apply. The maintainer who knows the package decides which to include. The api package might import the API and database standards, while the web package imports the frontend style guide. Neither one carries the other's rules.

    Importing a standards file under a headingmarkdown
    # Additional Instructions
    - git workflow @docs/git-instructions.md

    Imports organize content but do not save context. Their cost is paid wherever the importing file loads, so what matters is which file holds the import. An import in a package's own CLAUDE.md costs nothing until that package's file loads. The same import in the root CLAUDE.md costs context in every session.

    An import can also point outside the repository, for example to a file in your home directory. A shared CLAUDE.md can then reference a personal file that each developer keeps for themselves. The first time Claude Code meets an import of a file outside your working directory, it asks you to approve external imports.

    A project CLAUDE.md importing a per-developer file from the home directorymarkdown
    # Individual Preferences
    - @~/.claude/my-project-instructions.md

    Checkpoint 6 of 9· Fill the gap

    A package maintainer wants this CLAUDE.md to pull the team's git workflow standards file in alongside it. Which reference completes the line?

    # Additional Instructions
    - git workflow  ? 

    Sources41

    5.Splitting a monolithic CLAUDE.md into .claude/rules/

    The .claude/rules/ directory is the alternative to one long CLAUDE.md. Each markdown file in it covers one topic, such as testing.md, api-conventions.md, deployment.md or security.md. Each file is short enough to review in a pull request, and the person who owns the deployment process can edit deployment.md without touching anything else. Topic files also make it easier to spot two instructions that contradict each other. That matters because when instructions contradict, Claude may pick one arbitrarily.

    Rules files load the same way as the CLAUDE.md at their level. Project rules in .claude/rules/*.md load with the project instructions, including rules directories in parent folders. Personal rules in ~/.claude/rules/ load with your user-level CLAUDE.md and, like it, reach only you. A rule file with no frontmatter is always active. Adding a paths: glob restricts it to sessions where Claude works with matching files.

    Choosing between a per-directory CLAUDE.md and a central rules file
    ApproachLives inLoads whenWins when
    Per-directory CLAUDE.mdInside the directory, alongside its codeAt launch when started from that directory, or on demandDirectory owners maintain their own conventions; instructions are versioned with the code
    Rule in .claude/rules/Central .claude/ at the repo rootWith project instructions, or only for matching files if it has a paths: globYou want all conventions in one place, or the same rule applies to many scattered paths

    Checkpoint 7 of 9· Check yourself

    Your team breaks a 600-line root CLAUDE.md into three committed files, .claude/rules/testing.md, .claude/rules/api-conventions.md and .claude/rules/deployment.md, with no frontmatter in any of them. The API conventions matter only for code under src/api/. Which statement about the result is correct?

    Sources516

    6.Checking what actually loaded with /memory

    When Claude follows a rule for one engineer and ignores it for another, check what loaded before rewording the rule. Running /memory lists the memory file locations across user and project scopes. You can open any of them in your editor, and the command also gives access to the auto memory folder and its toggle. Have both engineers run it and compare the lists. Suppose the linter rule shows up only for the engineer who follows it, coming from their ~/.claude/CLAUDE.md or CLAUDE.local.md. Then the cause is scope, and the fix is to move the rule into a committed file.

    Common reflexes do not answer the question. Restarting and rerunning the prompt shows the same behavior without showing why. Re-cloning the repository changes nothing, because personal files live outside the clone or are gitignored. Comparing claude --version output looks at builds, not instruction files.

    /memory also matters when you edit a CLAUDE.md mid-session. Claude does not re-read the file on each turn, so an edit takes effect at your next /compact, when you open the file via /memory, or in your next session. You can add a rule mid-session the same way: open /memory, or ask Claude to remember the rule and it appends it to the right CLAUDE.md.

    Checkpoint 8 of 9· Check yourself

    Two engineers work in the same repository. Claude enforces the team's linter rule in one engineer's sessions and ignores it in the other's. Before anyone rewords the rule, what is the most useful first step?

    Checkpoint 9 of 9· Exam question

    Two engineers on the same team report that Claude behaves inconsistently: one gets careful adherence to a 'always run the linter before committing' rule, while the other says Claude never mentions the linter at all, even in the same repository on the same branch. Before assuming the rule text is unclear, what is the fastest way to confirm whether the inconsistency is actually a memory-loading problem?

    Sources73

    Practise it for real

    Turn a single CLAUDE.md into a project file plus topic rules files and a personal local file, then confirm the result with /memory.

    1. 1.In a repository, run /init and review the CLAUDE.md that Claude drafts.

      Why: It gives you a project-level file built from the codebase's real build commands, test commands and conventions.

      You should see: A draft CLAUDE.md at the project root that you can edit and commit.

    2. 2.Move the testing guidance into .claude/rules/testing.md and the deployment guidance into .claude/rules/deployment.md, leaving the project-wide essentials in CLAUDE.md.

      Why: Topic files are easier to own, review and keep free of contradictions than one long file.

      You should see: A shorter CLAUDE.md, well under 200 lines, plus two committed topic files.

    3. 3.Create CLAUDE.local.md at the project root with a personal sandbox URL and add it to .gitignore.

      Why: Personal project notes stay out of the shared history and never reach teammates.

      You should see: git status does not list CLAUDE.local.md.

    4. 4.Run /memory in a new session.

      Why: It shows which memory files the session is using, across user and project scopes.

      You should see: Memory file locations for your user and project scopes, each of which you can open in your editor.

    Stuck? Get a nudge

    If a rule seems to be ignored, compare your /memory list with a teammate's before rewording the rule.

    Sources

    (7)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “Organization-wide instructions managed by IT/DevOps”
      ↩︎ Where CLAUDE.md files live and who receives them
      “target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.”
      ↩︎ Where CLAUDE.md files live and who receives them
      “Deploy with your configuration management system”
      ↩︎ Where CLAUDE.md files live and who receives them
      “Personal project-specific preferences; add to .gitignore”
      ↩︎ The CLAUDE.md hierarchy and diagnosing a teammate who is missing instructions
      “Imports help you organize a long file but don’t reduce its context cost, because imported files load together with the CLAUDE.md that imports them.”
      ↩︎ Composing a CLAUDE.md with @path imports
      “Claude Code asks you to approve external imports”
      ↩︎ Composing a CLAUDE.md with @path imports
      “if two instructions contradict each other, Claude may pick one arbitrarily.”
      ↩︎ Splitting a monolithic CLAUDE.md into .claude/rules/
      “Personal preferences for all projects”
      ↩︎ Exam trap 1
      “Imports help you organize a long file but don’t reduce its context cost, because imported files load together with the CLAUDE.md that imports them.”
      ↩︎ Exam trap 2
      “User instructions | ~/.claude/CLAUDE.md | Personal preferences for all projects | Code styling preferences, personal tooling shortcuts | Only you (all projects)”
      ↩︎ Checkpoint
      “because imported files load together with the CLAUDE.md that imports them”
      ↩︎ Checkpoint
      “Move instructions that matter for only part of the codebase into path-scoped rules, which load only when Claude works with matching files.”
      ↩︎ Checkpoint
    2. 2.
      “Everyone, enforced in every session: set the rules in managed settings, which user and project settings cannot override.”
      ↩︎ Where CLAUDE.md files live and who receives them
      “Directory owners maintain their own conventions; instructions are versioned with the code”
      ↩︎ Which files load at launch and which load on demand
      “excludes every package’s CLAUDE.md while keeping the root”
      ↩︎ Which files load at launch and which load on demand
    3. 3.
      “Claude will explore the codebase and draft a CLAUDE.md for you, covering build commands, test commands, a structure overview, and any conventions it detects.”
      ↩︎ Where CLAUDE.md files live and who receives them
      “Claude looks in a few places and merges what it finds, from broad to specific”
      ↩︎ The CLAUDE.md hierarchy and diagnosing a teammate who is missing instructions
      “Subdirectory CLAUDE.md files are loaded on demand later, when Claude reads files in that subdirectory.”
      ↩︎ The CLAUDE.md hierarchy and diagnosing a teammate who is missing instructions
      “Subdirectory CLAUDE.md files are loaded on demand later, when Claude reads files in that subdirectory.”
      ↩︎ Which files load at launch and which load on demand
      “If you edit the file mid-session, the change is picked up the next time you run /compact or open it via /memory”
      ↩︎ Checking what actually loaded with /memory
      “Most teams only need the project-root file. Commit it to git so the whole team benefits.”
      ↩︎ Key concept
      “Subdirectory CLAUDE.md files are loaded on demand later, when Claude reads files in that subdirectory.”
      ↩︎ Exam trap 3
      “Most teams only need the project-root file. Commit it to git so the whole team benefits.”
      ↩︎ Checkpoint
    4. 4.
      “Add @path/to/file.md to ./CLAUDE.md to load additional files on launch”
      ↩︎ Composing a CLAUDE.md with @path imports
    5. 5.
      “Topic-scoped instructions, optionally path-gated”
      ↩︎ Splitting a monolithic CLAUDE.md into .claude/rules/
      “Managed settings deployed by your organization take precedence over every settings file and --settings value”
      ↩︎ Exam trap 4
      “Enterprise-enforced settings that your own settings files and --settings values can’t override, apart from narrow exceptions.”
      ↩︎ Prediction
    6. 6.
      “<cwd>/.claude/rules/*.md and .claude/rules/*.md in every parent directory”
      ↩︎ Splitting a monolithic CLAUDE.md into .claude/rules/
    7. 7.
      “Memory file locations across user and project scopes with the option to open each in your editor”
      ↩︎ Checking what actually loaded with /memory

    Spotted a mistake, or was something unclear? Tell us.