Claude Certified Architect - FoundationsCCAR-F Learning Guide
Domain 3 · Lesson 3.1 · 5 min read

CLAUDE.md Hierarchy and Organization

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

CLAUDE.md files load from user, project and directory levels; only the project level is shared through version control. Keep them modular with @import and .claude/rules/, and check what loaded with /memory.

What you need to know

The hierarchy

LevelLocationApplies toShared with the team?
User~/.claude/CLAUDE.mdYou, in every projectNo
ProjectCLAUDE.md or .claude/CLAUDE.md at the repository rootEveryone working in the repositoryYes, through version control
DirectoryCLAUDE.md in a subdirectoryWork in that part of the treeYes, if committed

The classic failure: a new teammate's sessions ignore the team's standards, because the standards were written in a senior engineer's user-level file. That file never left the senior engineer's machine. The fix is to move the standards into the project CLAUDE.md.

Diagnose with /memory

The /memory command shows which memory files the current session has loaded. When behaviour differs between people or sessions, it is the first thing to check.

Keep it modular

A single CLAUDE.md that grows to 2,000 lines is loaded in full every session, whatever the task. Two tools keep it manageable:

  • @import pulls another file into a CLAUDE.md. A package's CLAUDE.md can import only the standards that package needs:
# api/CLAUDE.md
@../docs/standards/typescript.md
@../docs/standards/error-handling.md

API handlers use async/await and the typed errors in src/errors.
  • .claude/rules/ holds topic files (testing.md, api-conventions.md, deployment.md) as an alternative to one monolithic file. Rules can also be scoped to paths so they load only when relevant (lesson 3.3).

What belongs where

ContentPut it in
Team coding standards, test conventionsProject CLAUDE.md or .claude/rules/
Your personal preferencesUser CLAUDE.md
Context for one task today (table mappings for a one-off migration)The conversation itself, or an @-mentioned file in the prompt
Rules that must never be brokenHooks or permission settings, with CLAUDE.md explaining them

CLAUDE.md is guidance: Claude follows it with high reliability, but it is not enforcement. A zero-tolerance security rule needs a hook or a permission deny rule.

In the exam

Most questions describe inconsistent behaviour between people or sessions (scope problem), a huge CLAUDE.md (modularise), a monorepo with different conventions per package (@import or rules), or a hard rule written only as guidance (hook or permissions).

Check your understanding

Question 1

A new engineer's sessions ignore the team's import ordering. The rules are in a senior engineer's ~/.claude/CLAUDE.md. What is the fix?

Show answer

Answer: B. User-level files are never shared. Project-level CLAUDE.md reaches everyone through version control.

Question 2

Your project CLAUDE.md has grown to 2,000 lines covering testing, API design and deployment. What is the best restructuring?

Show answer

Answer: C. Topic files under .claude/rules/ organise the content and, with path scoping, load only when relevant. Moving it to user files would stop sharing it.

Question 3

Sessions behave differently on two machines in the same repository. What should you check first?

Show answer

Answer: A. /memory lists the memory files in use. A difference there (a user-level file on one machine, say) usually explains the behaviour.

Apply it: Restructure Harbor Lane's CLAUDE.md

Exercise · about 20 minCase: Harbor Lane Software

Harbor Lane's 1,800-line root CLAUDE.md mixes everything, and new hires miss the import-ordering rules that live in one person's user file. Restructure the configuration.

  1. Decide what stays in the root project CLAUDE.md. Keep it short.
  2. Move topics into .claude/rules/. Name the files.
  3. Give each package what it needs using @import, with one example for api/.
  4. Handle three special items: the import-ordering rules, the on-call notes, and "never commit secrets or call eval".
  5. Say how a new hire checks that the configuration loaded.
Check your work
Show model answer

1. Root CLAUDE.md. A short overview: what the monorepo contains, how to build and test, where the rules live, and that infra/ changes need a plan first. About 40 lines.

2. Rules. .claude/rules/testing.md, typescript-style.md, react.md, api-conventions.md, terraform.md, deployment.md.

3. Packages. api/CLAUDE.md imports @../.claude/rules/typescript-style.md and @../.claude/rules/api-conventions.md, then adds two lines specific to the API. web/ imports the TypeScript and React files; shared/ imports TypeScript style plus a JSDoc rule.

4. Special items.

  • Import ordering: moved from the senior engineer's user file into typescript-style.md, so everyone gets it.
  • On-call notes: not configuration for Claude; moved to the team wiki.
  • Secrets and eval: enforced by a PreToolUse hook and permission deny rules; CLAUDE.md keeps one sentence explaining them.

5. Check. Run /memory in a fresh session in api/ and confirm the root file, api/CLAUDE.md and the imported rules are listed.

Sources