What you will be able to do
- Place an instruction at the right CLAUDE.md scope (managed, user, project, local, or subdirectory) based on who should receive it
- Predict which CLAUDE.md files are in context at session start and which load later, depending on where Claude Code was launched
- Diagnose why a teammate or a session is missing instructions, using /memory and /context
- Explain why instructions in ~/.claude/CLAUDE.md are never shared with teammates through version control, and trace a new team member's missing instructions back to user-level configuration
Key concept
Scope decides who receives an instruction — Where a CLAUDE.md file lives determines who gets its instructions and when they load. A file in ~/.claude/ reaches only you. A file committed to the repository reaches the whole team. A subdirectory file reaches anyone working in that part of the tree, but only once Claude goes there.
1.Four places a CLAUDE.md can live
CLAUDE.md is a plain markdown file of instructions that Claude Code reads automatically. You don't attach it to a prompt. The real design decision is where you put it, because Claude reads several locations and merges what it finds, going from broad to specific. Each location is a scope, and each scope has a different audience.
| Scope | Location | Purpose | Shared with |
|---|---|---|---|
| Managed policy | /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux and WSL) | Organization-wide instructions managed by IT/DevOps | All users in organization |
| User instructions | ~/.claude/CLAUDE.md | Personal preferences for all projects | Just you (all projects) |
| Project instructions | ./CLAUDE.md or ./.claude/CLAUDE.md | Team-shared instructions for the project | Team members via source control |
| Local instructions | ./CLAUDE.local.md | Personal project-specific preferences; add to .gitignore | Just you (current project) |
The audience follows directly from the location. Your home directory isn't part of any repository, so ~/.claude/CLAUDE.md applies to every project on your machine and to nobody else's. That makes it the right place for things like "I use pnpm, not npm". The project file is the one that carries architecture, conventions and commands. The support guide calls it "the main one" and says most teams need only this file. CLAUDE.local.md sits in the project but is gitignored, so it holds personal details for that one project, such as your sandbox URLs. Managed policy is deployed by IT across the organization.
Checkpoint 1 of 7· Match them up
Match each instruction to the CLAUDE.md scope it belongs in
Tap a term, then the definition that fits it.
Each location reaches a different audience: you everywhere, the team through source control, you in one project, or the whole organization.
“Your sandbox URLs, preferred test data | Just you (current project)”Source: code.claude.com
Checkpoint 2 of 7· Exam question
A platform team maintains a monorepo with packages/api, packages/web, and packages/shared. The api package's maintainer wants api-specific database and testing conventions to load only when someone is actively working in packages/api, without duplicating those conventions into the root CLAUDE.md. Which approach best satisfies this requirement?
Correct answer: C — Create packages/api/CLAUDE.md with the api-specific conventions, so it loads at launch when Claude starts from packages/api or on demand when Claude reads files there
- A. Importing the api file from root would load it into every session regardless of which package is being worked on, defeating the goal of scoping it to api-only work.
- B. A file cannot meaningfully import itself, and this describes a non-existent precedence rule; imports don't create self-referential precedence.
- C. Correct. A per-directory CLAUDE.md in packages/api loads at launch when Claude starts there, or lazily when Claude reads files in that subdirectory, keeping it scoped without touching the root file.
- D. User-level CLAUDE.md is personal, not shared through version control, and would need to be manually duplicated by every developer rather than maintained once by the package owner.
2.What loads at launch and what loads on demand
Subdirectories can have their own CLAUDE.md files too, for example different conventions in frontend/ and api/. In a monorepo that usually means one per package. These directory-level files don't all load at the same moment, and exam scenarios often turn on exactly that timing.
The rule has two parts. Files at and above your working directory are read at session start. Files below it load on demand, the first time Claude reads something in that subdirectory. That makes the launch directory significant.
| Start from | CLAUDE.md loaded at launch | Use when |
|---|---|---|
| Repository root | Root only; subdirectory files load on demand when Claude reads there | Tasks span multiple packages or subsystems |
| A subdirectory | That directory’s plus every ancestor’s | Work is scoped to one package or subsystem |
This split also shows up after compaction. The project-root CLAUDE.md is re-injected from disk. A nested CLAUDE.md only comes back when Claude reads files in that subdirectory again.
Checkpoint 3 of 7· Check yourself
Claude Code was launched from the repository root. packages/web/CLAUDE.md contains frontend conventions. When does Claude first see them?
Subdirectory CLAUDE.md files below the launch directory are loaded on demand, when Claude reads files in that directory, not at session start.
“loaded on demand when Claude reads files in that directory, not at session start”Source: support.claude.com
Checkpoint 4 of 7· Exam question
A project's single CLAUDE.md has grown to over 500 lines covering code style, testing, security requirements, and deployment steps, and the team notices Claude adheres to instructions less reliably than before. The architect wants to reorganize this into focused, maintainable files while keeping everything loaded for every session. Which restructuring best achieves this?
Correct answer: A — Split the content into code-style.md, testing.md, security.md, and deployment.md under .claude/rules/, leaving CLAUDE.md as a short project pointer
- A. Correct. Splitting a monolithic CLAUDE.md into topic-specific files under .claude/rules/ (testing.md, security.md, etc.) is the documented pattern; rules without paths frontmatter load at launch with the same priority as CLAUDE.md, keeping everything available while improving maintainability.
- B. Consolidating everything into one large rules file just relocates the monolith and does not solve the adherence or maintainability problem the team is trying to fix.
- C. Using a `**/*` paths glob on every rule makes them conditional on file reads rather than loaded at launch, and offers no organizational benefit over unconditional rules for content meant to apply everywhere.
- D. The `@` import syntax references files by path, not arbitrary external URLs, and Claude Code does not fetch remote gists as CLAUDE.md imports.
3.Diagnosing missing or inconsistent instructions
Here is a common failure. A senior engineer has been getting consistent results for months. A new hire joins, and Claude ignores the team's conventions in that person's sessions. The cause is usually scope: the conventions were written into the senior engineer's ~/.claude/CLAUDE.md. That file is "Just you (all projects)". It was never in the repository, so cloning the repo doesn't deliver it. The fix is to move the team-relevant rules into the project CLAUDE.md and commit them, and to leave only genuinely personal preferences in the user file.
Checkpoint 5 of 7· Check yourself
A new teammate's Claude sessions ignore the team's testing conventions, but the original developer's sessions follow them. The conventions are in the original developer's ~/.claude/CLAUDE.md. What is the right fix?
Only the project-level file reaches teammates through source control. Copying the user file would work but drift over time, and CLAUDE.local.md is personal and gitignored.
“Most teams only need the project-root file. Commit it to git so the whole team benefits.”Source: support.claude.com
The underlying rule is that user-level configuration applies only to that user. Instructions in ~/.claude/CLAUDE.md live in one person's home directory, outside the repository, so they are not shared with teammates via version control. Only the project-level file is delivered that way, as the "Team members via source control" entry in the scope table says. The same holds for settings files: ~/.claude/settings.json reaches every project on your machine and nothing on a teammate's. So a rule that works for you and not for a colleague has usually been written at the wrong scope.
To diagnose a new team member's missing instructions, work through the hierarchy in order. First, have them run /memory and /context in the affected project and read the list under Memory files. If the project's CLAUDE.md is absent, Claude can't see it. Second, ask where the rule was written. If it exists only in someone's ~/.claude/CLAUDE.md, the diagnosis is user-level rather than project-level configuration. Third, check that the project CLAUDE.md was actually committed and that the teammate has pulled it. Then move the rule into the project file.
Checkpoint 6 of 7· Check yourself
A new team member runs /context and the Memory files list shows no project CLAUDE.md with your team's conventions. You wrote those conventions only in your own ~/.claude/CLAUDE.md. What is the diagnosis?
A user-level file stays on your machine. Conventions the team needs must be in the project CLAUDE.md and committed, so teammates receive them via source control.
“If a CLAUDE.md file is missing there, Claude can’t see it.”Source: code.claude.com
When you need to see what is actually happening, use the built-in commands rather than guessing. /memory shows the memory file locations across user and project scopes and lets you open each one in your editor. /context lists the memory files that loaded in this session. If a CLAUDE.md doesn't appear in that list, Claude can't see it, and the first thing to check is whether the file sits somewhere that gets loaded for your session.
| Command | What it tells you |
|---|---|
| /memory | Memory file locations across user and project scopes, with the option to open each in your editor |
| /context | The list under Memory files: which CLAUDE.md and CLAUDE.local.md files actually loaded |
Behaviour can also differ between sessions for two other reasons. First, CLAUDE.md isn't re-read from disk on every turn. If you edit it mid-session, the change takes effect after /compact, after you open the file through /memory, or in your next session. Second, two files may contradict each other, for example a nested CLAUDE.md and the root one. In that case Claude may follow either instruction, chosen arbitrarily, so review the whole hierarchy and remove the conflict.
Checkpoint 7 of 7· Check yourself
You add a rule to the project CLAUDE.md during a session, and Claude keeps ignoring it for the rest of that session. What explains this?
The file is read at session start and isn't re-read from disk each turn. Mid-session edits are picked up after /compact, after opening the file via /memory, or in the next session.
“If you edit the file mid-session, the change is picked up the next time you run /compact or open it via /memory”Source: support.claude.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Instructions in ~/.claude/CLAUDE.md reach everyone who works on the project.Why is that wrong?
The user-level file applies only to the person whose home directory it is in. Team conventions belong in the project CLAUDE.md, which teammates receive through source control.
2.Every CLAUDE.md in the repository loads at session start.Why is that wrong?
Only files at and above the launch directory load at startup. Subdirectory files below it load on demand when Claude reads files there.
3.Editing CLAUDE.md mid-session changes Claude's behaviour on the very next message.Why is that wrong?
The file is not re-read from disk on each turn. The change is picked up after /compact, after opening the file via /memory, or in the next session.
4.If a new teammate isn't getting instructions, the fix is for them to write the same rules in their own user-level file.Why is that wrong?
That leaves the rules unshared and prone to drift. The team rules belong in the committed project CLAUDE.md, which teammates receive via source control.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/memoryOfficial docs
“Personal preferences for all projects”
↩︎ Four places a CLAUDE.md can live“Team members via source control”
↩︎ Four places a CLAUDE.md can live“Run /context and check the list under Memory files to verify your CLAUDE.md and CLAUDE.local.md files loaded.”
↩︎ Diagnosing missing or inconsistent instructions“Check that the relevant CLAUDE.md is in a location that gets loaded for your session”
↩︎ Diagnosing missing or inconsistent instructions“Consistency: if two instructions contradict each other, Claude may pick one arbitrarily.”
↩︎ Diagnosing missing or inconsistent instructions“Just you (all projects)”
↩︎ Diagnosing missing or inconsistent instructions“Team-shared instructions for the project”
↩︎ Key concept“Just you (all projects)”
↩︎ Exam trap 1“Team members via source control”
↩︎ Exam trap 4“Your sandbox URLs, preferred test data | Just you (current project)”
↩︎ Checkpoint“If a CLAUDE.md file is missing there, Claude can’t see it.”
↩︎ Checkpoint - 2.https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-promptsOfficial docs
“Claude looks in a few places and merges what it finds, from broad to specific”
↩︎ Four places a CLAUDE.md can live“There is no summarization or truncation, and it is not re-read from disk on each turn.”
↩︎ Exam trap 3“loaded on demand when Claude reads files in that directory, not at session start”
↩︎ Checkpoint“Most teams only need the project-root file. Commit it to git so the whole team benefits.”
↩︎ Checkpoint“If you edit the file mid-session, the change is picked up the next time you run /compact or open it via /memory”
↩︎ Checkpoint - 3.https://code.claude.com/docs/en/large-codebasesOfficial docs
“That directory’s plus every ancestor’s”
↩︎ What loads at launch and what loads on demand“Root only; subdirectory files load on demand when Claude reads there”
↩︎ Exam trap 2 - 4.https://code.claude.com/docs/en/context-windowOfficial docs
“Nested CLAUDE.md in subdirectories | Claude Code reloads them as Claude reads files in that subdirectory”
↩︎ What loads at launch and what loads on demand - 5.https://code.claude.com/docs/en/debug-your-configOfficial docs
“Memory file locations across user and project scopes with the option to open each in your editor”
↩︎ Diagnosing missing or inconsistent instructions - 6.https://code.claude.com/docs/en/settingsOfficial docs
“You, in every project on this machine”
↩︎ Diagnosing missing or inconsistent instructions