Home › Study guides › CCAR-F › Domain 3 › Lesson 3.1

CCAR-F · Domain 3 · 20% of the exam · Lesson 3.1 · 23 min read

CLAUDE.md: hierarchy, scoping and modular organisation

The three CLAUDE.md levels, why a teammate never sees ~/.claude/CLAUDE.md, @import and .claude/rules/ for modular standards, and /memory to diagnose sessions.

Written against task statement 3.1 of the official CCAR-F exam guide (Version 1.0, effective July 2026). An independent resource, not affiliated with Anthropic; the practice questions are written from scratch.

3.1.1 Why the new hire's Claude Code ignores the team's rules

Picture a small engineering team that uses Claude Code, Anthropic's command-line coding assistant, to generate code, refactor, debug and write documentation. Marcus, who set it up, has it well trained. Every API handler it writes (the code that answers one kind of request to the team's server) checks its input, returns errors in the team's standard shape and comes with a test. Then Priya joins. She copies the team's code to her laptop, starts Claude Code and asks for a new handler. What comes back looks like it came from a different company: no input checks, a home-made error format, no test.

Nothing is broken on either laptop. Every Claude Code session starts with a fresh context window, the working memory that holds one conversation, so nothing Marcus told Claude Code last week travels to Priya. Whatever Claude Code should know about a team's conventions has to be written down in a file it reads at the start of every session. That file is CLAUDE.md: a plain Markdown text file of standing instructions.

The team's code lives in a repository, a shared project folder whose history is tracked by git, the team's version control system. When someone commits a file (records it in that history), every teammate who clones the repository (downloads their own copy) or updates it receives that file. Marcus did write the conventions down, and Claude Code follows them for him. The catch is WHERE he wrote them. CLAUDE.md can live in several places, and each has a different audience. Priya's problem is not a missing feature or a weak prompt. It is a file in the wrong place, and this lesson is about telling the places apart.

3.1.2 Three levels, three audiences

Here is the question that settles most questions on this task statement: when you write an instruction, who needs to receive it? The answer picks the file. The exam guide names three places Claude Code reads CLAUDE.md from, and they differ not in what they can say but in who gets to see them.

The user level is ~/.claude/CLAUDE.md. The ~ stands for your home directory, the personal folder your computer keeps for your account. Claude Code loads this file in every project you open, and no teammate ever sees it, because your home directory is not part of any repository. It is the right place for personal preferences: "explain your changes briefly", "I prefer tabs".

The project level is a CLAUDE.md at the repository root (its top folder) or at .claude/CLAUDE.md. It lives inside the repository, so it is committed and cloned like any other file, and that is the whole point. The team's build commands, coding standards, architecture notes and workflows go here. The team's repository also holds several packages, separate parts of the product side by side: packages/api/ for the server code, packages/web/ for the website. That is where the directory level comes in: a CLAUDE.md inside a subdirectory such as packages/api/. It is committed too, but it speaks only for that area of the code, such as the API package's own conventions.

Think of three notice boards. A note on your own fridge reaches you, whichever project you are working on. The board in the office lobby reaches everyone who walks in. A sign on one room's door reaches whoever goes into that room. Marcus pinned the team's rules to his fridge. Priya has never been to his kitchen.

The docs list two more locations worth recognising, though the exam guide names only the three above. A managed policy CLAUDE.md is deployed by IT to a fixed system path, such as /Library/Application Support/ClaudeCode/CLAUDE.md on macOS or /etc/claude-code/CLAUDE.md on Linux. It reaches every user on that machine, and individual settings cannot exclude it. And CLAUDE.local.md at the project root holds your personal notes for one project. You add it to .gitignore, git's list of files it must not track, so like the user level it reaches only you.

3.1.3 What actually loads when a session starts

Knowing the places is half the job. The other half is knowing which files a session actually reads, so you can diagnose "works for Marcus, not for Priya" instead of guessing.

The working directory is the folder you start Claude Code in. At launch, Claude Code loads your user-level file and then every CLAUDE.md (and CLAUDE.local.md) in the working directory and every folder above it. Start Claude Code in packages/api/ and it reads packages/api/CLAUDE.md and the root CLAUDE.md immediately. Subdirectories BELOW the working directory are different: their CLAUDE.md files load on demand, the moment Claude reads a file in that folder. Start at the repository root, and the API package's rules arrive only when Claude opens something under packages/api/.

The files do not override one another. Claude Code concatenates them into context, broadest first: managed policy, then user, then the project files from the top of the tree down to your working directory. An instruction closer to where you launched is read last, but a conflicting instruction higher up is not cancelled. Both stay in context, and the docs warn that Claude may then follow either one. So the levels are about audience and scope, not about one file winning; keep them consistent.

Now run Priya's session through this. She starts in packages/api/. Claude Code loads her own ~/.claude/CLAUDE.md, which is empty, then the root CLAUDE.md, then packages/api/CLAUDE.md. Marcus's conventions are in none of them. They sit in /Users/marcus/.claude/CLAUDE.md, a file that exists on exactly one laptop. Two people cloned the same repository and got different behaviour, so the instruction must be in a per-person file: a user-level CLAUDE.md or a CLAUDE.local.md. That is the diagnosis, and the fix follows: move the conventions to the project level and commit them.

3.1.4 @import: one standards file, many CLAUDE.md files

Moving the conventions to project level fixes Priya's morning, and raises the next question. The API and web packages use different stacks (sets of languages and frameworks), and the team keeps a growing pile of standards documents in docs/standards/. Do you paste the API conventions into packages/api/CLAUDE.md, the React conventions into packages/web/CLAUDE.md, and the testing standards into both? Pasting means copies that drift apart the first time someone edits one of them.

The @import syntax is the answer. Anywhere in a CLAUDE.md, a reference such as @docs/standards/testing.md tells Claude Code to expand that file into context together with the CLAUDE.md that contains the line. Paths can be relative or absolute. A relative path resolves from the file containing the import, not from where you launched. Imported files can import further files, up to four hops deep. Claude Code ignores an @ path inside backticks or a fenced code block, so `@README` stays literal text while @README on its own imports the file.

It works like a course syllabus that says "see the department style guide" instead of copying the guide into every handout. Each standard lives once, in docs/standards/, and each package's CLAUDE.md pulls in only the ones that apply to it. Who decides which ones apply? The person who maintains that package, because they know its stack. The API maintainer imports the API conventions and the testing standards; the web maintainer imports the React conventions and the same testing standards. Nobody loads rules for a stack they never touch.

Look at the two import lines. Each climbs two folders (../../), because the path resolves from packages/api/CLAUDE.md itself and the standards sit under the repository root.

# packages/api/CLAUDE.md
Copy `.env.example` to `.env` before running anything.
Never edit a migration after it has merged; add a new one.

# Team standards that apply to this package
@../../docs/standards/api-conventions.md
@../../docs/standards/testing.md

The docs add two cautions. First, imports organise your files; they do not shrink your context. Everything imported still loads and still costs tokens (the word pieces a model reads, and the unit context is measured in). Second, an import in a project's CLAUDE.md that points outside the working directory counts as external. The first time Claude Code meets external imports in a project, it asks you to approve them, which protects you from files other people commit. If Priya starts in packages/api/, the two lines above point outside that folder, so she sees that prompt once; decline it and those imports stay switched off.

3.1.5 Splitting the monolith: .claude/rules/

Now the other growth problem. Marcus's original file, once moved to the project root, is four hundred lines: testing rules, API conventions, deployment steps, naming, commit etiquette, all in one scroll. The docs recommend keeping each CLAUDE.md under about two hundred lines. Their reason is plain: a longer file uses more context and Claude follows it less reliably, so the rule you care about gets lost among the rest. When Claude Code keeps ignoring an instruction that is definitely in the file, "the file is too long" is the first suspect.

The remedy the exam guide names is the .claude/rules/ directory. Instead of one monolithic CLAUDE.md, you keep a short .claude/CLAUDE.md with the essentials and give each topic its own Markdown file: .claude/rules/testing.md, .claude/rules/api-conventions.md, .claude/rules/deployment.md. Claude Code finds every .md file under .claude/rules/, including subfolders such as rules/frontend/. A rule file loads at launch, with the same priority as .claude/CLAUDE.md. The one exception is a rule that carries a paths: field listing file patterns: it loads only when Claude works with a matching file.

A binder with tabs holds the same pages as one long scroll, but you can hand each tab to the person who owns it. The API maintainer owns api-conventions.md, the release engineer owns deployment.md, and a change to the testing rules touches one small file that the test lead reviews. Rule files without paths: all load at launch, so splitting alone does not shrink what Claude reads. What it buys is ownership: each small file is pruned by someone who knows which lines Claude would follow anyway.

The docs also offer a personal version of the same idea. ~/.claude/rules/ holds your own topic files, applies to every project on your machine and loads before the project's rules. Its audience is the same as ~/.claude/CLAUDE.md, and so is its trap: nothing in it reaches a teammate.

3.1.6 /memory: seeing which memory files are in play

Everything so far assumed you know which files a session read. Often you do not, and the symptom is maddening. Priya notices that Claude Code follows the team's database rule (every query goes through one shared helper) on Tuesday and ignores it on Thursday, in the same repository. The instinct is to rewrite the rule in stronger words. Resist it. Inconsistency across sessions is almost always a loading problem, so check what loaded before you edit anything.

The /memory command is the check. Claude Code calls its instruction files memory files, because they are what carries over from one session to the next. Type /memory in a session and Claude Code lists the memory files at user and project level: your ~/.claude/CLAUDE.md, the project's CLAUDE.md and CLAUDE.local.md, and more. It even lists files that do not exist yet; select any entry to open it in your editor, creating it if needed. Compare the list with what you expected, and "I think the rules are loaded" becomes something you can check.

Priya runs it, opens the listed files, and the database rule is in none of the user or project files. It lives only in packages/api/src/db/CLAUDE.md, which loads on demand. On Tuesday Claude read a file in that folder early in the session, so the rule arrived; on Thursday it never opened one. If every API session needs the rule, she moves it up into packages/api/CLAUDE.md. If it only matters inside src/db/, the scoping is working as designed.

Priya's team now makes /memory the first move whenever behaviour drifts, and each symptom points to one mechanism from this lesson:

Memorise the first row and the last; the others follow from the mechanisms once you have them.

3.1.7 The exam traps

Almost every mistake in this task statement is the same mistake in different clothes: an instruction that exists, but in a file whose audience or loading does not match what you need.

• ✗ Writing team conventions in ~/.claude/CLAUDE.md. ✓ Put them in the project's CLAUDE.md or .claude/CLAUDE.md and commit. The user level is never in version control, so a new team member cannot receive it.
• ✗ Telling the new hire to copy a colleague's home file. ✓ Commit the conventions at project level once. A copy fixes one laptop for one week; the next edit drifts and the next hire starts the cycle again.
• ✗ Pasting every standards document into every package's CLAUDE.md. ✓ Keep each standard in one file and @import only the relevant ones from each package, chosen by that package's maintainer.
• ✗ Letting one CLAUDE.md grow into a four-hundred-line monolith. ✓ Split it into .claude/rules/ topic files such as testing.md, api-conventions.md and deployment.md, and have each owner prune what Claude would do anyway.
• ✗ Rewriting an instruction in capitals because it works in some sessions and not others. ✓ Run /memory first and verify which memory files are loaded. Inconsistency across sessions is a loading problem until proven otherwise.
• ✗ Expecting a CLAUDE.md line to guarantee an action. ✓ CLAUDE.md is context that shapes behaviour, not enforcement. When something must happen every time, use a hook: a script Claude Code itself runs at a fixed moment, whatever Claude decides.

3.1.8 Put it together: reorganise the team's CLAUDE.md and break a clone

You now have every piece. The levels decide who receives an instruction and the loading rules decide when it arrives. @import and .claude/rules/ keep the files modular, and /memory shows what a session can see. The quickest way to make the levels real is to be Priya for half an hour: set the hierarchy up correctly, then put a rule in the wrong place and clone the repository.

Every other Claude Code configuration file lives at one of the same levels and raises the same question of audience. Slash commands and skills (3.2) sit in .claude/commands/ and .claude/skills/ for the team, or under ~/.claude/ for you alone. Path-specific rules (3.3) are the .claude/rules/ files from this lesson with a paths: field, so a convention loads only for matching files. Plan mode (3.4) and iterative refinement (3.5) are about how you work within a session. Claude Code in continuous integration (3.6), the automated pipeline that checks every change, runs with no human at the keyboard. There, the project CLAUDE.md is how it learns the team's testing standards and review criteria.

Key takeaways

• ✓ CLAUDE.md holds Claude Code's standing instructions, read at the start of every session; where the file lives decides who receives it.
• ✓ Three levels: user (~/.claude/CLAUDE.md, just you, never in version control), project (CLAUDE.md or .claude/CLAUDE.md, the whole team via git), directory (a subdirectory CLAUDE.md, that area only).
• ✓ At launch Claude Code loads the user file and every CLAUDE.md from the working directory upward; subdirectory files below it load on demand, and everything is concatenated broad to specific, with nothing overriding.
• ✓ "Works for one person, not the team" is a level problem: the instruction is in a per-person file, and the fix is to move it to project level and commit.
• ✓ @path/to/file pulls a standards file into context, relative to the importing file and up to four hops deep, so each package's CLAUDE.md includes only the standards its maintainer knows apply.
• ✓ .claude/rules/ splits a monolithic CLAUDE.md into owned topic files (testing.md, api-conventions.md, deployment.md); those without paths load at launch like .claude/CLAUDE.md.
• ✓ When behaviour is inconsistent across sessions, run /memory to verify which memory files are loaded before rewriting anything.

Check your understanding

4 questions written for this lesson, then one from the CCAR-F question bank on the same topic. Every answer option is explained, including the ones you did not pick. Nothing is stored.

Sources

• How Claude remembers your project
• Best practices for Claude Code
• Set up Claude Code in a monorepo
• Commands
• The CCAR-F exam guide, summarised