TimoBy Amotion AI

CLAUDE.md hierarchy: CCAR-F task statement 3.1

CCAR-F · Claude Code Configuration & Workflows (20% of the exam)

Task statement 3.1 opens Claude Code Configuration & Workflows, 20% of the CCAR-F exam. It tests where an instruction should live so that the right people get it: the whole team, one developer, or only the code in one folder, and how to keep those files small and organised.

What the official guide covers

The Claude Certified Architect Foundations exam guide (version 1.0, effective July 2026) lists this under task statement 3.1, "Configure CLAUDE.md files with appropriate hierarchy, scoping, and modular organization":

Knowledge ofSkills in
The hierarchy: user level (~/.claude/CLAUDE.md), project level (.claude/CLAUDE.md or a root CLAUDE.md) and directory level (CLAUDE.md in a subdirectory)Diagnosing hierarchy problems, such as a new team member missing instructions that sit in someone's user-level file
User-level instructions apply only to that user and are not shared through version controlUsing @import so each package's CLAUDE.md pulls in only the standards files its maintainers choose
The @import syntax for pulling external files into a CLAUDE.mdSplitting a large CLAUDE.md into topic files in .claude/rules/, such as testing.md, api-conventions.md and deployment.md
.claude/rules/ as an alternative to one large CLAUDE.mdUsing /memory to check which memory files are in use and diagnose behaviour that differs between sessions

Where CLAUDE.md files live and who gets them

ScopeLocationShared withUse it for
Managed policyAn OS-level path set by IT (for example /etc/claude-code/CLAUDE.md on Linux)Everyone on the machineCompany-wide standards
User~/.claude/CLAUDE.mdOnly you, in every projectPersonal preferences
Project./CLAUDE.md or ./.claude/CLAUDE.md, committedThe team, through version controlBuild commands, conventions, architecture
Local./CLAUDE.local.md, added to .gitignoreOnly you, in this projectYour sandbox URLs, test data
DirectoryCLAUDE.md in a subdirectoryThe team, if committedRules for one package or folder

The exam's favourite fact is the second row. A file in your home directory never reaches a teammate. If an instruction must apply to everyone, it belongs in a committed project file.

How Claude Code loads them

At launch, Claude Code reads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it, plus your user file and any managed file. CLAUDE.md files in subdirectories below the working directory do not load at launch. They load when Claude reads files in those subdirectories.

All the files that load are added to the context together. None of them overrides another. They are ordered from the broadest scope to the most specific, so a project instruction appears after a user instruction, and a folder closer to where you started appears later. If two files contradict each other, Claude may follow either one, so the fix for a conflict is to remove it, not to rely on order.

CLAUDE.md is context, not enforcement. Claude reads it and tries to follow it. A rule that must hold every time belongs in a hook or a permission setting (see 1.5 Agent SDK hooks).

Keep it modular: @imports and .claude/rules/

Imports. A line such as @docs/testing-standards.md in a CLAUDE.md pulls that file in. Relative paths resolve from the file that contains the import, not from where you started Claude. Imported files can import others, up to four hops deep. The first time a project file imports something outside the working directory, Claude Code asks you to approve it. Imported files load together with the CLAUDE.md that references them, so imports organise content but do not reduce what Claude reads.

Rules. Markdown files in .claude/rules/ are found automatically, including in subfolders. Each file covers one topic. A rule file without frontmatter loads when the session starts, at the same priority level as .claude/CLAUDE.md. A rule file with a paths field in its frontmatter loads only when Claude works on matching files; that is the subject of 3.3 Path-specific rules. Personal rules can live in ~/.claude/rules/.

Anthropic's documentation suggests keeping each CLAUDE.md under about 200 lines. Longer files use more context and are followed less consistently.

Write rules Claude can follow

Where a file lives decides who gets it. How each line is written decides whether Claude follows it.

  • Concrete and checkable. "Put new API handlers in src/api/handlers/, one per file" can be checked; "keep files organised" cannot. If you could not tell whether a rule was followed, neither can Claude.
  • Name the replacement. "Use named exports, not default exports" closes the gap that "don't use default exports" leaves open.
  • Group by topic. Headings and short bullets are easier to follow than dense paragraphs.
  • Spend emphasis sparingly. Marking one rule "IMPORTANT" can lift it. Marking twenty makes none of them stand out.
  • Keep it a working set, not a log. Decision history, archived notes and long explanations belong in separate documents Claude can open when needed. Multi-step procedures belong in a skill, which loads only when relevant.

Start with /init, which scans the project and drafts a CLAUDE.md with build commands, test instructions and conventions it finds. Then edit it like code: when Claude repeats a mistake, add or sharpen a rule, and delete lines Claude already gets right without them. You can ask Claude to "add this to CLAUDE.md" or open the file with /memory.

A monorepo set up this way

acme-platform/
├── CLAUDE.md                    # team: build, test, shared conventions (committed)
├── CLAUDE.local.md              # you: sandbox URLs (gitignored)
├── .claude/rules/
│   ├── testing.md
│   ├── api-conventions.md
│   └── deployment.md
├── standards/
│   ├── python-style.md
│   ├── react-style.md
│   └── data-retention.md
└── packages/
    ├── payments-api/CLAUDE.md   # loads when Claude reads files in payments-api/
    └── web-app/CLAUDE.md

packages/payments-api/CLAUDE.md, written by the payments maintainers:

# Payments API

Python service. Owned by the payments team.

@../../standards/python-style.md
@../../standards/data-retention.md

- Run `make test-payments` before every commit.
- Store money as integer cents. Never use floats for amounts.

The web-app file imports react-style.md instead. Each package gets the standards its maintainers know apply, and neither sees the other's.

Check what actually loaded

Two commands answer "why is Claude ignoring my instruction?":

  • /memory lists your CLAUDE.md, CLAUDE.local.md and other memory file locations at user and project level, and opens any of them for editing.
  • /context shows which CLAUDE.md and rules files are loaded in the current session, under Memory files.

If a file is missing from the session, Claude cannot see it. Common causes: the instruction sits in one person's user file, the file is in a subdirectory Claude has not read yet, or two files conflict.

Four less obvious causes come up when behaviour differs between sessions or tasks:

  • Built-in Explore and Plan subagents skip CLAUDE.md. They start without your project instructions to keep research fast. The general-purpose subagent and custom subagents load the full hierarchy by default. If a project rule must hold during delegated work, delegate to one of those.
  • Compaction treats files differently. After /compact, Claude Code re-reads the project-root CLAUDE.md from disk. Subdirectory CLAUDE.md files and path-scoped rules come back only when Claude reads matching files again.
  • Another team's file is loading. In a monorepo, an ancestor CLAUDE.md written for other teams can apply to your folder. The claudeMdExcludes setting skips named files by path or glob.
  • The run was scripted. A plain claude -p run loads the same CLAUDE.md files as an interactive session, but --bare skips them, and so does an Agent SDK app that sets setting_sources to an empty list. If a CI job ignores project rules, check those flags first.

To see exactly which files load, when and why, add an InstructionsLoaded hook that logs each one. It fires for files loaded at start, nested files and path-matched rules, but cannot block anything.

Where should this instruction go?

SituationPut it inWhy
Every developer must follow itProject CLAUDE.md or .claude/CLAUDE.md, committedShared through version control
Only you want it, in every project~/.claude/CLAUDE.mdPersonal, never shared
Only you, only this projectCLAUDE.local.md, gitignoredPersonal and project-specific
Applies to one package's folderA CLAUDE.md in that packageLoads when Claude works there
Root CLAUDE.md is long and mixes topicsTopic files in .claude/rules/Easier to own and review
Each package needs a different subset of shared standards@import in each package's CLAUDE.mdMaintainers choose what applies
Must never be brokenA hook or permission ruleCLAUDE.md is guidance
A multi-step procedure used for some tasksA skillLoads only when relevant
Rule ignored during an Explore or Plan delegationUse the general-purpose or a custom subagentExplore and Plan skip CLAUDE.md

Rules that decide exam answers

  • Shared means committed. If teammates do not get an instruction, check whether it sits in someone's ~/.claude/CLAUDE.md. Move it to the project file.
  • Files add up; they do not override. Every loaded file is in context at once. Fix conflicts by removing them.
  • Subdirectory files load on demand. A package's CLAUDE.md applies when Claude reads files there, not at launch.
  • Imports organise but do not shrink. Imported files still load. To keep context small, split by package or use rules with paths.
  • Check before guessing. /memory lists and opens memory files; /context shows what is loaded in this session.
  • Guidance is not enforcement. A rule that must always hold goes in a PreToolUse hook or a deny rule, not in CLAUDE.md. When a rule is being ignored, the fix is usually a shorter file or a more specific line, not more capital letters.

Where it appears in the exam

Claude Code Configuration & Workflows is a primary domain in three of the six exam scenarios: Code Generation with Claude Code, Developer Productivity with Claude and Claude Code for Continuous Integration. The Code Generation scenario names CLAUDE.md configuration directly. The guide's practice exercise on configuring Claude Code for a team development workflow starts with a project-level CLAUDE.md and .claude/rules/ files.

Two sample questions

These are original Timo practice questions. They are not official exam questions.

Question 1

A team's coding conventions work well for the senior developer who wrote them. A new team member clones the repository, and Claude Code ignores the conventions in their sessions. The conventions are in the senior developer's ~/.claude/CLAUDE.md. What should the team do?

Answer: A. A committed project file reaches everyone who clones the repository and stays in one place. B creates personal copies that drift apart. C is meant to be gitignored, so it is not shared. D saves the conventions only on that developer's machine.

Question 2

A monorepo has three packages owned by different teams. The root CLAUDE.md has grown to 900 lines covering every team's standards. In the web package, Claude sometimes applies the Python service's conventions. What is the best restructure?

Answer: C. Package files with selective imports put each team's standards where they apply, and rules files keep the root short. A tidies the file, but every import still loads at launch, so Claude sees the same mix. B relies on Claude sorting 900 lines correctly. D moves team standards into personal files nobody else can see.

Build exercise

  1. In a test repository, put one instruction in ~/.claude/CLAUDE.md and another in the project CLAUDE.md. Run /context and confirm both appear under Memory files. Clone the repository as another user and note which one is missing.
  2. Add a CLAUDE.md to a subdirectory. Start Claude at the root, check /context, then ask Claude to read a file in that subdirectory and check again.
  3. Split a long CLAUDE.md into testing.md and api-conventions.md in .claude/rules/. Confirm with /context that both load.
  4. Give two packages their own CLAUDE.md files that import different standards files. Ask the same coding question in each package and compare the answers.

Practise this topic

Sources