What you will be able to do
- Describe when a path-scoped rule enters context and how it behaves after /compact
- Choose between a path-scoped rule and a per-directory CLAUDE.md for a given convention
- Keep unwanted rules out of context with claudeMdExcludes, and share rules through user-level folders or symlinks
1.When a path-scoped rule enters context
Before you type anything, several things load into context: CLAUDE.md, auto memory, MCP tool names and skill descriptions. A rule with paths frontmatter isn't one of them. As Claude works, each file it reads adds to context, and any rule whose globs match that file loads along with it. If Claude never touches a matching file, the rule costs nothing.
This is the main payoff of path scoping. Context fills up as a session goes on, and old material crowds out what you need next. Keeping specialised conventions out until they're relevant leaves room for the code Claude is actually working on.
Compaction shows the split clearly. /compact replaces the conversation with a structured summary and then restores startup content. The two kinds of rule are handled differently:
| Mechanism | After compaction |
|---|---|
| Project-root CLAUDE.md and unscoped rules | Re-injected from disk |
| Rules with paths: frontmatter | Claude Code reloads them as Claude reads files they match |
| Nested CLAUDE.md in subdirectories | Claude Code reloads them as Claude reads files in that subdirectory |
Checkpoint 1 of 5· Check yourself
A repo has .claude/rules/api.md with paths: ["src/api/**/*.ts"]. Claude spends a whole session editing files under docs/. How much context does api.md use?
Path-scoped rules load together with matching files. If Claude never touches a file under src/api/, the rule never enters context.
“path-scoped rules load automatically alongside matching files”Source: code.claude.com
Sources1
2.Rules or a subdirectory CLAUDE.md?
Per-directory CLAUDE.md files are the other way to keep conventions local. You put a CLAUDE.md inside a package or subsystem, such as packages/api/ or src/db/. If you start Claude from the repository root, only the root file loads at launch. A subdirectory's CLAUDE.md loads on demand when Claude reads a file in that directory. Both mechanisms defer loading. The real difference is where the trigger is defined: a nested CLAUDE.md fires on a directory, and a rule fires on a glob.
| Approach | File location | Loads when | Use when |
|---|---|---|---|
| Per-directory CLAUDE.md | Inside the directory, alongside its code | At launch when started from that directory, or on demand when Claude reads a file there | Directory owners maintain their own conventions; instructions are versioned with the code |
| Path-scoped rule in .claude/rules/ | Central .claude/ at the repo root | When Claude works with a file matching the rule’s paths: glob | You want all conventions in one place, or the same rule applies to many scattered paths |
A convention tied to a directory fits naturally in that directory's CLAUDE.md. A convention tied to a file type doesn't. Test files are the textbook example, because they sit next to source files in dozens of folders. Covering them with nested CLAUDE.md files would mean copying the same testing guidance into every one of those directories and keeping the copies in sync. That guidance would also load whenever Claude read any file in those directories, not just the tests. A single rule with a type-based glob such as **/*.test.tsx lives in one central file and loads only for files that match it.
Checkpoint 2 of 5· Check yourself
Test files sit next to source files in about 40 directories. The team wants one testing convention that loads only when Claude works on a test file. What should they create?
Nested CLAUDE.md files are tied to directories. A rule's glob can match one file type across many scattered paths from a single central file.
“You want all conventions in one place, or the same rule applies to many scattered paths”Source: code.claude.com
Checkpoint 3 of 5· Exam question
An infrastructure team wants Claude Code to load Terraform-specific formatting and tagging conventions only when Claude edits files under the terraform/ directory, at any subfolder depth. Which YAML frontmatter for a new .claude/rules/terraform.md file correctly scopes the rule to this requirement?
Correct answer: A — --- paths: - "terraform/**/*" ---
- A. Correct. The paths field takes a YAML list, and the double-star glob terraform/**/* matches files under terraform/ at any depth, including nested subfolders.
- B. A single star only matches files directly inside terraform/ and would miss files in nested subfolders such as terraform/modules/network/main.tf.
- C. The frontmatter field recognized for path scoping is paths, not include; a rule using include would not be treated as path-scoped.
- D. The paths field is documented as a YAML list of patterns, not a bare string; while a single pattern is common, it should be expressed as a list item under paths:.
Sources2
3.Sharing, excluding and keeping rules consistent
Rules aren't limited to the project. Personal rules go in ~/.claude/rules/ and apply to all your projects. The .claude/rules/ directory also follows symlinks, so a team can link a shared folder of standards, or a single shared file, into each repository:
ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.mdIn a large monorepo the opposite problem comes up: other teams' rules and CLAUDE.md files reach you when you don't need them. The claudeMdExcludes setting takes glob patterns or absolute paths for files to skip, and it covers rule directories as well as CLAUDE.md files. You can exclude another team's rules without editing anything in their directory, and your own path-scoped rules keep loading as normal:
{
"claudeMdExcludes": [
"**/monorepo/CLAUDE.md",
"/home/user/monorepo/other-team/.claude/rules/**"
]
}More files means more chances for instructions to contradict each other. The documentation doesn't define a strict override order here. CLAUDE.md content is additive, and it warns that when two instructions conflict, Claude may simply pick one. So periodically review your CLAUDE.md files, nested CLAUDE.md files and .claude/rules/, and remove stale or conflicting guidance.
Checkpoint 4 of 5· Match them up
Match each need to the mechanism that handles it
Tap a term, then the definition that fits it.
claudeMdExcludes globs can match rules as well as CLAUDE.md files. User-level rules and symlinks handle sharing. Conflicts aren't resolved deterministically, so you have to clean them up by hand.
“excludes every package whose name matches the glob, including rules”Source: code.claude.com
Checkpoint 5 of 5· Exam question
A developer configured .claude/rules/api-security.md scoped with paths: ["src/api/**/*.ts"]. During a session, Claude runs git status and lists the repository tree with Glob, but has not yet opened any file under src/api/. Based on how path-scoped rules are triggered, what should the developer expect?
Correct answer: A — The api-security.md rule has not been loaded into context yet, because path-scoped rules load when Claude reads a file matching the pattern, not merely when it uses other tools like Glob or Bash.
- A. Correct. Path-scoped rules trigger when Claude reads a file matching the pattern, not on every tool use, so running git status or listing files with Glob does not load the rule.
- B. Rules with a paths field are conditional, not unconditional; only rules omitting the paths field load automatically at launch.
- C. Seeing a matching filename in a directory listing is not the same as reading the file's contents; the trigger is Claude reading a file matching the pattern, not any tool surfacing the path.
- D. /memory is used to view and browse loaded instruction files, not to force path-scoped rules to activate; the rule loads automatically once a matching file is read.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Every subdirectory CLAUDE.md loads at session start, so it's no cheaper than putting the guidance in the root file.Why is that wrong?
When you start at the repository root, subdirectory CLAUDE.md files load on demand when Claude reads files there. They're still tied to a directory, though, which is why scattered file types are better served by a glob rule.
Covered in Rules or a subdirectory CLAUDE.md?
2.claudeMdExcludes only skips CLAUDE.md files, so the only way to block another team's rules is to edit their files.Why is that wrong?
Exclude globs also match rule files. A pattern pointing at a team's .claude/rules/ keeps those rules out of your context without touching their directory.
3.When two always-loaded rule files conflict, a fixed precedence order decides which one Claude follows.Why is that wrong?
The documentation warns that Claude may pick either one arbitrarily. Remove contradictions instead of relying on one rule overriding another.
Practise it for real
Add a path-scoped API rule to a project and confirm it loads only alongside matching files
1.Create .claude/rules/api.md with the frontmatter
paths:followed by the list entry- "src/api/**/*.ts"and a short API Development Rules bodyWhy: The paths field gates the rule to TypeScript files under src/api/
You should see: A committed rule file that sits in the project's .claude/rules/ directory
2.Start a session and ask Claude to work only on a file outside src/api/, such as a Markdown file
Why: No file matching the glob is involved
You should see: The API rule doesn't load, because path-scoped rules load only alongside matching files
3.Ask Claude to edit a .ts file under src/api/
Why: This file matches the rule's glob
You should see: The rule loads along with the matching file and its conventions apply to the edit
4.Run /compact, then ask Claude to read another file under src/api/
Why: Compaction drops path-scoped rules until they match again
You should see: The rule reloads when Claude reads the matching file, not immediately after compaction
Stuck? Get a nudge
If the rule seems to load everywhere, check that the frontmatter is at the very top of the file and that the paths field is spelled exactly 'paths'.
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/context-windowOfficial docs
“path-scoped rules load automatically alongside matching files”
↩︎ When a path-scoped rule enters context“Old conversation crowds out the files you need next and costs tokens on every message.”
↩︎ When a path-scoped rule enters context“Claude Code reloads them as Claude reads files they match”
↩︎ Prediction - 2.https://code.claude.com/docs/en/large-codebasesOfficial docs
“Root only; subdirectory files load on demand when Claude reads there”
↩︎ Rules or a subdirectory CLAUDE.md?“When Claude works with a file matching the rule’s paths: glob”
↩︎ Rules or a subdirectory CLAUDE.md?“excludes every package whose name matches the glob, including rules”
↩︎ Exam trap 2“You want all conventions in one place, or the same rule applies to many scattered paths”
↩︎ Checkpoint“excludes every package whose name matches the glob, including rules”
↩︎ Checkpoint - 3.https://code.claude.com/docs/en/memoryOfficial docs
“if two instructions contradict each other, Claude may pick one arbitrarily”
↩︎ Sharing, excluding and keeping rules consistent“if two instructions contradict each other, Claude may pick one arbitrarily”
↩︎ Exam trap 3 - 4.https://code.claude.com/docs/en/features-overviewOfficial docs
“When instructions conflict, Claude uses judgment to reconcile them.”
↩︎ Sharing, excluding and keeping rules consistent
Also cited
- https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-promptsOfficial docs
“loaded on demand when Claude reads files in that directory, not at session start”
↩︎ Exam trap 1