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.
share
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.
- You start Claude Code in
packages/api/. - It reads the managed policy file, if your organization has one, then
~/.claude/CLAUDE.md. - It checks every directory from the filesystem root down and finds CLAUDE.md files in
repo/,packages/andpackages/api/. - It concatenates them in that order, with
packages/api/CLAUDE.mdlast. - 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
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.
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.
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.
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.
Session in packages/infra/
# repo/CLAUDE.md
@standards/react.md
@standards/api.md
@standards/terraform.md
@standards/security.mdLoads at launch: all four standards, in every session in every package.
Session in packages/infra/
# packages/infra/CLAUDE.md
This package provisions AWS
with Terraform.
@../../standards/terraform.md
@../../standards/security.mdLoads 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.
.claude/rules/. No → it is personal, so put it in ~/.claude/CLAUDE.md.- 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.
@importorganises 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.