Task statement 3.1 · Claude Code configuration and workflows

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

Claude has followed your team's commit conventions in your sessions for months. A new team member clones the monorepo, starts Claude Code in packages/api/, and Claude ignores every one of them, because the file that holds them never reached the clone.

Why it's tested

The tempting fixes all work on the wording. Adding IMPORTANT or repeating the rule changes nothing, because the file that holds it is never loaded on the new team member's machine. Asking them to paste the rules into their own ~/.claude/CLAUDE.md works, but only for that person and only until the rules change.

KnowledgeWhich files load, and in what order

The guide names three levels of CLAUDE.md. The user level, ~/.claude/CLAUDE.md, applies to every project you open but is never in the repository, so it applies only to you and is not shared with teammates through version control. The project level is CLAUDE.md or .claude/CLAUDE.md at the repository root, which is committed and arrives with every clone. The directory level is a CLAUDE.md in a subdirectory, such as one per package. Every path in this section resolves against this monorepo:

repo/CLAUDE.md            # every package
├── standards/            # react.md · api.md · terraform.md · security.md
└── packages/CLAUDE.md    # every package
    ├── web/CLAUDE.md     # imports react.md
    ├── api/CLAUDE.md     # api/src/CLAUDE.md sits below it
    └── infra/CLAUDE.md   # imports terraform.md, security.md

At launch, Claude Code loads the CLAUDE.md in the launch directory and in every directory above it, and concatenates them from the top of the tree down, so the launch directory's file is read last. A later file adds to an earlier one and never overrides it, so two contradicting files leave Claude to pick one arbitrarily. A CLAUDE.md below the launch directory waits until Claude reads a file there.

  1. You start Claude Code in packages/api/.
  2. It reads the managed policy file, if your organization has one, then ~/.claude/CLAUDE.md.
  3. It checks every directory from the filesystem root down and finds CLAUDE.md files in repo/, packages/ and packages/api/.
  4. It concatenates them in that order, with packages/api/CLAUDE.md last.
  5. Later, when Claude reads a file in packages/api/src/, that directory's CLAUDE.md is added.

The diagram steps through the same walk. Switch to packages/infra/ to see which package files that session never loads.

Interactive · choose where the session starts

Diagram of CLAUDE.md load order for a session launched in packages/api: managed policy, user, repository root, root local file, packages, packages/api, then a subdirectory file that loads only on demand. A button switches the launch directory to packages/infra, where the web and api package files are not in the walk. CONTEXT WINDOW · SESSION LAUNCHED IN packages/api/ CONTEXT WINDOW · SESSION LAUNCHED IN packages/infra/ read order at launch MANAGED POLICY /etc/claude-code/CLAUDE.md (Linux) Everyone in the organization · set by IT USER ~/.claude/CLAUDE.md Just you · every project · never committed PROJECT · REPOSITORY ROOT ./CLAUDE.md or ./.claude/CLAUDE.md The whole team · committed LOCAL · REPOSITORY ROOT ./CLAUDE.local.md Just you · this project · gitignored PROJECT · ON THE WAY DOWN packages/CLAUDE.md The whole team · a parent of the launch folder PROJECT · LAUNCH DIRECTORY packages/api/CLAUDE.md packages/infra/CLAUDE.md + 2 imports The whole team · read last at launch terraform.md, security.md · at launch SUBDIRECTORY · NOT AT LAUNCH SIBLING PACKAGES · NOT IN THE WALK packages/api/src/CLAUDE.md packages/web/CLAUDE.md · packages/api/CLAUDE.md Loads when Claude reads a file in src/ Neither above nor below infra/ · not loaded

Step through what loads before your first message.

1 · Managed policy CLAUDE.md, if your organization deploys one. Broadest scope, read first.

2 · ~/.claude/CLAUDE.md — your personal instructions, on this machine, in every project. Never committed.

3 · The repository root: ./CLAUDE.md or ./.claude/CLAUDE.md. Committed, so every clone carries it.

4 · ./CLAUDE.local.md — your private notes for this project. Gitignored, and read after the root CLAUDE.md.

5 · packages/CLAUDE.md — a parent of the launch directory. The walk reads every directory on the way down.

6 · packages/api/CLAUDE.md — the launch directory. Read last at launch, so it is closest to your first message.

7 · packages/api/src/CLAUDE.md is not loaded yet. It arrives only when Claude reads a file in src/.

Launched in packages/infra/. Step through what loads before your first message.

1 · Managed policy CLAUDE.md, if your organization deploys one. Broadest scope, read first.

2 · ~/.claude/CLAUDE.md — your personal instructions, on this machine, in every project. Never committed.

3 · The repository root: ./CLAUDE.md or ./.claude/CLAUDE.md. Committed, so every clone carries it.

4 · ./CLAUDE.local.md — your private notes for this project. Gitignored, and read after the root CLAUDE.md.

5 · packages/CLAUDE.md — a parent of the launch directory. The walk reads every directory on the way down.

6 · packages/infra/CLAUDE.md — the launch directory, read last. Its two @imports expand here, at launch.

7 · packages/web/CLAUDE.md and packages/api/CLAUDE.md are not in this walk, so react.md is never loaded.

Rows 1–2 are step 2 of the list, rows 3–6 are steps 3–4, and the dashed row 7 is step 5. Every solid row is concatenated into one context at launch, and no row overrides another. Amber rows are committed, so they are the only rows a teammate's clone carries.

More precise than the guide. Claude Code reads two files the guide's three levels leave out: a managed policy CLAUDE.md that IT deploys, loaded before the user file, and a gitignored CLAUDE.local.md, loaded right after the CLAUDE.md in the same directory (checked 2026-10-01). Exam answer: user level, project level and directory level.

SkillDiagnosing the new team member's missing instructions

The symptom is that your sessions follow the commit conventions and the new team member's sessions do not, on the same commit of the same repository. The cause is where the conventions live: in your ~/.claude/CLAUDE.md, which their clone never received, so their session loaded only their own user file. The fix is to move the lines into the committed root CLAUDE.md, which every session in every package loads at launch.

Where it was

User level

# ~/.claude/CLAUDE.md
Commit messages use Conventional
Commits. Run `npm run typecheck`
before every commit.

New team member's session loads: their own ~/.claude/CLAUDE.md, which does not contain these lines.

Where it belongs

Project level

# repo/CLAUDE.md  (committed)
Commit messages use Conventional
Commits. Run `npm run typecheck`
before every commit.

New team member's session loads: this file, at launch, from the first clone onward.

Knowledge@import: each package pulls in its own standards

A CLAUDE.md can pull another file in with @path/to/file, which keeps it short and modular. A relative path resolves against the file that contains the import, not your working directory, and imports can nest up to four hops deep. Imported files are expanded into context at launch, with the CLAUDE.md that imports them. The guide's skill is to let each package's maintainers, who know which standards their code needs, choose that package's imports.

Root imports everything

Session in packages/infra/

# repo/CLAUDE.md
@standards/react.md
@standards/api.md
@standards/terraform.md
@standards/security.md

Loads at launch: all four standards, in every session in every package.

Each package imports its own

Session in packages/infra/

# packages/infra/CLAUDE.md
This package provisions AWS
with Terraform.
@../../standards/terraform.md
@../../standards/security.md

Loads at launch: these two. ../../ climbs from packages/infra/ to repo/.

Both layouts are modular, but only the second saves context, and the saving comes from the walk, not the import. A session in packages/infra/ never loads packages/web/CLAUDE.md, because that file is neither above nor below the launch directory, so it never expands what that file imports. A root CLAUDE.md that imports all four standards still loads all four in every session.

SkillSplitting a monolithic CLAUDE.md into .claude/rules/

Suppose the root CLAUDE.md has grown to 600 lines. The docs recommend under 200 lines per file, because a longer file costs more context and is followed less reliably. The guide's alternative is .claude/rules/, one markdown file per topic. A rule with no frontmatter loads at launch like CLAUDE.md, so the split makes topics easier to maintain but does not reduce their cost. Adding a paths field, a list of globs (filename patterns such as **/*.tf), makes a rule load only when Claude reads a matching file, as 3.3 shows.

# before: one file
CLAUDE.md                          600 lines
# after: one file per topic
CLAUDE.md                          120 lines
.claude/rules/testing.md
.claude/rules/api-conventions.md
.claude/rules/deployment.md

SkillVerifying what loaded with /memory

When behaviour is inconsistent across sessions, find out which files each session read before you change any wording. /memory, a command you type in a session, lists the CLAUDE.md locations across user and project scope and opens any of them, including a project file nobody has created yet. Suppose the API error-format rule in packages/api/CLAUDE.md is followed in one session and ignored in another. In the session started at repo/, /context lists repo/CLAUDE.md under Memory files but not the api file, which waits until Claude reads a file in packages/api/. The difference is the launch directory, not the rule.

More precise than the guide. The guide names /memory as the way to verify which memory files are loaded. In current Claude Code, /memory lists and opens the file locations, and /context shows the files that actually loaded into this session (checked 2026-10-01). Exam answer: /memory.

Ask one question: should a teammate who clones the repository get this instruction? Yes → it is a team standard, so put it in a committed file: the root CLAUDE.md, a package's CLAUDE.md, or .claude/rules/. No → it is personal, so put it in ~/.claude/CLAUDE.md.
Takeaway
  • An instruction that reaches one teammate and not another usually sits in a file that was never committed, most often ~/.claude/CLAUDE.md.
  • Claude Code concatenates every CLAUDE.md from the root down to the launch directory, and none overrides another. Files below the launch directory load only when Claude reads there.
  • @import organises a file but does not shrink it. Per-package imports save context only because a session in one package never loads another package's CLAUDE.md.

check yourself

0 / 3 answered

repo/CLAUDE.md imports all four files in standards/: react.md, api.md, terraform.md and migrations.md. Engineers in packages/api say every session loads 250 lines of React and Terraform rules they never use. The platform team maintains each standard as a single file in standards/.Which change best stops api sessions loading the React and Terraform standards while keeping each standard as one file in standards/?

Select one.

Two engineers on the infra package report that Claude applies the resource-tagging convention for one of them and ignores it for the other, on the same branch. Before anyone edits a file or a setting, you want to see which instruction files each engineer's sessions actually read.Which TWO steps best establish that without changing any file or setting?

Select two.

A session launched in packages/web/ sometimes installs with npm and sometimes with pnpm. /context lists repo/CLAUDE.md, packages/CLAUDE.md and packages/web/CLAUDE.md under Memory files. The root file says "Install with npm" and the web file says "Install with pnpm".What is the most likely root cause?

Select one.

sources

  1. Claude Docs, "How Claude remembers your project": the scope table (managed policy paths per OS, user, project, local) and its load order; loading from the launch directory and every directory above it, concatenated root-down with CLAUDE.local.md after CLAUDE.md; subdirectory files loading when Claude reads files there; @path imports resolving against the importing file, expanded at launch, up to four hops, skipped inside code spans; the 200-line target; .claude/rules/ and rules without paths loading at launch; /memory listing locations and /context showing what loaded. Checked 2026-10-01.
  2. Task statement text, the user/project/directory framing, "maintainer domain knowledge", and the testing.md / api-conventions.md / deployment.md split: Claude Certified Architect — Foundations Exam Guide v1.0, Domain 3.1. The monorepo packages are this course's Scenario 2 detail.