What you will be able to do
- Explain what a file in .claude/rules/ is and how it differs from CLAUDE.md
- Write a rule's paths frontmatter as a YAML list or a comma-separated string of glob patterns
- Predict when a path-scoped rule enters Claude's context, including after /compact
- Identify the project, parent-directory and user locations Claude Code reads rule files from
Key concept
Path-scoped rule — A markdown file in .claude/rules/ whose paths frontmatter lists glob patterns. Claude Code only puts the rule into context once Claude works with a file that matches one of those patterns.
1.Rules: topic files that can be gated by path
Claude Code's .claude/ directory has two places for written instructions, and they behave differently. CLAUDE.md is described as "Instructions loaded every session". Files under rules/*.md are described as "Topic-scoped instructions, optionally path-gated". Both can live in a project or in your global configuration, and both can be committed so the whole team shares them.
The word to notice is "optionally". A rule file with no gating works like another slice of CLAUDE.md, split out by topic so that no single file gets huge. The gating is what makes rules worth studying for this objective. It lets you write a convention that only reaches Claude when Claude is working in the part of the codebase it applies to.
Rule files have a very small frontmatter. The directory reference lists skills with close to twenty frontmatter fields and subagents with more than a dozen. For rules/*.md it lists exactly one field: paths. A rule has no name, description or tool list. Its only setting is which files it applies to.
Sources1
2.The paths field
The memory documentation defines paths in one row. It is not required, it holds glob patterns that scope the rule to matching files, and it accepts either a YAML list or a comma-separated string. So you can scope a rule to one pattern or to several, in whichever form you find easier to read.
The exam guide gives the typical example. A rule of Terraform conventions gets the frontmatter paths: ["terraform/**/*"], which covers every file at any depth under terraform/. Leave out paths and the rule is unscoped. It then stops being conditional and loads the way the project-root CLAUDE.md does.
Sources2
3.When a scoped rule enters context and why that matters
The context-window walkthrough splits loading into two phases. Before you type anything, a fixed set of content is already in context: CLAUDE.md, auto memory, MCP tool names and skill descriptions. Path-scoped rules come in during the second phase. As Claude works, "path-scoped rules load automatically alongside matching files". The directory reference says the same thing from the other side: a path-scoped rule loads when Claude works with a file that matches its paths glob.
That answers the prediction. If the session never touches a file under terraform/, the Terraform rule never loads. This is the practical benefit. Conventions for areas you aren't working in take up no context-window space, so they can't distract Claude from the task in front of it. Support guidance on CLAUDE.md makes the same point, calling it "still worth keeping the file lean for context-window space and signal-to-noise". Moving area-specific conventions into scoped rules keeps the always-loaded layer lean without throwing those conventions away.
The trigger is Claude working with or reading a matching file. It is not limited to editing. A rule for test files can load while Claude is only reading a test to understand it, before it changes anything.
| 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 |
No. Unscoped rules are re-injected from disk along with the root CLAUDE.md. Rules with paths: frontmatter stay out until Claude reads a matching file again, and then they reload. Loading after compaction follows the same conditional logic as the first load.
4.Where rule files can live
The Agent SDK's loading table gives the full set of locations. Project rules come from .claude/rules/*.md in the working directory and also from .claude/rules/*.md in every parent directory. User rules come from ~/.claude/rules/*.md, which is the place for personal preferences that follow you across projects. In the SDK, project rules load only when settingSources includes "project", and user rules only when it includes "user".
You don't have to copy a rule file into place. The memory documentation shows the rules directory accepting symlinks, both to a whole shared folder and to a single file. That lets one set of company standards feed many repositories.
ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.mdHaving several locations raises a question: what happens when a personal rule and a project rule both load without a paths field and contradict each other? The source excerpts for this lesson list both locations but give no tie-break between conflicting rules. Don't rely on one rule overriding the other. The robust fix is to remove the contradiction, or to narrow one of the rules with paths so they no longer apply to the same files.
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.
Sources6
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Every file in .claude/rules/ loads at session start, just like CLAUDE.md.Why is that wrong?
Only unscoped rules behave like CLAUDE.md. A rule with paths: frontmatter loads once Claude works with a matching file, and after /compact it reloads only when such a file is read again.
Covered in When a scoped rule enters context and why that matters
2.After /compact, every rule that loaded during the session is re-injected along with the root CLAUDE.md.Why is that wrong?
Only unscoped rules are re-injected from disk. Rules with paths: frontmatter wait until Claude reads a matching file again.
Covered in When a scoped rule enters context and why that matters
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/claude-directoryOfficial docs
“Topic-scoped instructions, optionally path-gated”
↩︎ Rules: topic files that can be gated by path“Instructions loaded every session”
↩︎ Rules: topic files that can be gated by path - 2.https://code.claude.com/docs/en/memoryOfficial docs
“Glob patterns that scope the rule to matching files. Accepts a YAML list or a comma-separated string”
↩︎ The paths field“Glob patterns that scope the rule to matching files. Accepts a YAML list or a comma-separated string”
↩︎ Key concept - 3.https://code.claude.com/docs/en/context-windowOfficial docs
“Before you type anything: CLAUDE.md, auto memory, MCP tool names, and skill descriptions all load into context.”
↩︎ When a scoped rule enters context and why that matters“As Claude works: each file read adds to context, path-scoped rules load automatically alongside matching files”
↩︎ Exam trap 1“Claude Code reloads them as Claude reads files they match”
↩︎ Exam trap 2 - 4.https://code.claude.com/docs/en/large-codebasesOfficial docs
“When Claude works with a file matching the rule’s paths: glob”
↩︎ When a scoped rule enters context and why that matters - 5.https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-promptsOfficial docs
“It is still worth keeping the file lean for context-window space and signal-to-noise”
↩︎ When a scoped rule enters context and why that matters - 6.
“.claude/rules/*.md in every parent directory”
↩︎ Where rule files can live