- In short
- A Claude Code path-specific rule is a markdown file inside .claude/rules/ whose YAML frontmatter lists glob patterns under a paths field. The rule loads into context only when Claude reads a file matching one of those globs, so a convention stays scoped to the code it governs instead of loading on every session.
What Claude Code path-specific rules are
Claude Code path-specific rules are markdown files you place inside a project's .claude/rules/ directory, each carrying a small block of YAML frontmatter that tells Claude when the rule should apply. The frontmatter holds a paths field, a list of glob patterns, and Claude only pulls the rule into its context window when it reads a file that matches one of those patterns. A rule about Terraform style sits dormant while you work on React components, then appears the moment Claude opens a .tf file.
This is the mechanism task statement 3.3 is built around: applying conventions conditionally rather than loading every instruction on every session. It sits one level past plain modular organisation. Moving instructions into .claude/rules/ files already keeps your configuration tidy, but a rule without frontmatter still loads at launch. Adding a paths field is what makes the rule load on demand, and understanding that single field is the whole of this knowledge point.
- Path-specific rule
- A markdown file in .claude/rules/ whose YAML frontmatter declares a paths field of glob patterns. Claude loads the rule into context only when it reads a file matching one of those globs. Without a paths field, the same file loads unconditionally at the same priority as .claude/CLAUDE.md.
The shape of a path-specific rule file
A rule file is ordinary markdown with a frontmatter header fenced by triple dashes. The header is short: typically just the paths field. Everything below it is the instruction text Claude will read when the rule activates.
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments
Three details matter here. First, the file lives under .claude/rules/, which is discovered recursively, so you can nest folders like backend/ and frontend/ and Claude still finds every .md file. Second, the paths value is a YAML list; each entry is a glob pattern. Third, every pattern is wrapped in quotes. That last point is not cosmetic. YAML reserves characters such as * and the opening brace as special indicators, so a pattern written as **/*.ts without quotes is invalid YAML and the rule fails to parse, often silently. Quoting "**/*.ts" is the difference between a rule that works and one that never loads.
How the paths field decides when a rule loads
The contract is simple to state. If a rule file has no paths field, it loads unconditionally at session start, at the same priority as .claude/CLAUDE.md. If a rule file does have a paths field, it loads only when Claude reads a file whose path matches one of the listed globs. There is no third behaviour to memorise; the presence or absence of paths is the entire switch.
That means the rule's instructions are not floating around in context waiting to maybe be relevant. When you are editing a Python service, your TypeScript-component rule and your Terraform rule are simply absent. When Claude later reads a file under src/api/, the API rule above is injected, and Claude now sees the validation and error-format instructions exactly when it is about to touch API code. Scoping the instruction to the file is what gives the convention its precision.
Read-time loading, and what it does not cover
There is one nuance the exam can probe and that trips up people in real projects: path-scoped rules trigger when Claude reads a matching file, not on every tool use, and notably not when Claude creates a brand-new file that would match the pattern. If your rule says "every file under src/api/ must use the standard error format" and Claude is writing a new src/api/orders.ts from scratch, it may not have read an existing match, so the rule may not be in context at creation time.
The practical consequence is a design rule of thumb: if a convention is genuinely non-negotiable at creation time, make it unconditional by removing the paths field, accepting the small always-on context cost in exchange for reliability. Conditional loading is the right default for the large body of conventions that come into play while editing existing files; it is not a guarantee that fires the instant a matching path comes into existence.
It helps to hold the two states clearly in mind, because the exam likes to probe the boundary between them. A scoped rule is dormant by default and activates on a matching read; an unconditional rule is active from launch and never sleeps. Neither is "better" in the abstract: the scoped form keeps your context lean and is correct for the many conventions that only matter while editing existing code, while the unconditional form trades a little context for a guarantee and is correct for the few rules that must apply the moment a file is born. Choosing between them is simply a question of whether read-time activation is good enough for that particular convention, and being able to articulate that trade is exactly what an understand-level answer is expected to do.
Why this beats stuffing everything into CLAUDE.md
The alternative most teams start with is putting every convention into one CLAUDE.md. That file loads in full at launch, so a rule meant only for Terraform is in context while Claude edits CSS. Past a couple of hundred lines this is actively harmful: the official guidance is that bloated configuration causes Claude to lose important rules in the noise. Path-specific rules let you keep universal facts in CLAUDE.md while moving the conditional, area-specific conventions into scoped files that appear only where they apply. The downstream knowledge points build directly on this: the same mechanism is what makes a single glob rule beat a forest of per-directory CLAUDE.md files, and what keeps your context budget lean.
Worked example
A monorepo mixes a React frontend, a Python API, and Terraform infrastructure under infra/. The team wants Claude to follow strict Terraform naming and tagging conventions, but only when it touches infrastructure files, without those rules cluttering frontend or API work.
Start by deciding the scope: the convention applies to Terraform files, which live under infra/ and end in .tf. That maps cleanly to a glob. Create a single file at .claude/rules/terraform.md:
---
paths:
- "infra/**/*.tf"
---
# Terraform conventions
- Name resources with the pattern <env>-<service>-<resource>
- Every resource must carry the standard cost-center and owner tags
- Use remote state; never commit local .tfstate files
Now trace what happens. While a developer has Claude refactoring a React component, the path being read is something like src/components/Button.tsx, which does not match infra/**/*.tf, so the Terraform rule never enters context. The frontend session stays focused and lean. Later, the developer asks Claude to adjust a module under infra/network/. Claude reads infra/network/main.tf, the path matches the glob, and the naming and tagging rules are injected right as Claude prepares its edit.
Notice what you did not do. You did not create a CLAUDE.md inside infra/, and you did not paste Terraform rules into the root CLAUDE.md where they would load for every CSS and Python change. One scoped rule file expresses the convention once and delivers it exactly where it belongs. The only caveat to keep in mind is creation time: if Claude scaffolds a brand-new .tf file rather than reading an existing one, the rule may not yet be in context, so a team that treats tagging as non-negotiable at creation might drop the paths field and pay the small always-on cost instead.
Common misreadings to avoid
The two mistakes below are the ones that most often turn a perfectly good rule into one that quietly does nothing.
Misconception
Putting a rule in .claude/rules/ automatically makes it load only for the files it is about.
What's actually true
Misconception
You can write glob patterns in the paths field exactly as you would type them in a shell, like paths: **/*.ts.
What's actually true
How rules sit alongside the rest of your configuration
A path-specific rule never exists in isolation; it joins the same context as your CLAUDE.md files and any unconditional rules, so knowing the load order helps you reason about precedence. Personal rules in ~/.claude/rules/ apply to every project on your machine and load before a given project's rules, which means the project rules take priority wherever the two overlap. Project rules under .claude/rules/ travel with the repository through version control, so the whole team and every CI run receive them, exactly as they receive the project CLAUDE.md. A rule with no paths field, wherever it lives, simply loads at launch at CLAUDE.md priority, while a scoped rule waits quietly for a matching read before it contributes anything at all.
This is also why a committed path-specific rule is a better home for a shared convention than personal configuration. Because the rule file is checked in, every developer sees the same scoped instruction, which sidesteps the classic scoping bug where one engineer's edits follow a convention and a teammate's do not. When behaviour diverges between developers, the cause is rarely the model and usually a convention stranded in someone's user-level config, or a rule whose glob silently never matched the files in question.
Verifying that a rule actually loaded
Because a scoped rule is invisible until a matching file is read, you need a reliable way to confirm it fired. The /memory command lists every CLAUDE.md, CLAUDE.local.md, and rules file active in the current session, so after opening a file that should match, you can check that your rule appears in that list. If it does not, the usual suspects are an unquoted glob that failed to parse, a pattern that does not actually match the path you opened, or a file placed outside .claude/rules/. For harder cases, the InstructionsLoaded hook can log exactly which instruction files load, when, and why, which is invaluable for tracing a rule that fires on some files but not others. Treating "did the rule load?" as a checkable fact rather than an assumption is the discipline that turns conditional rules from mysterious into dependable, and it is the same habit the configuration-debugging knowledge points reward.
Rules guide Claude, they do not enforce
A point worth holding onto, especially once a convention feels important, is that a path-specific rule is context, not enforced configuration. When the glob matches, Claude reads the rule and is instructed to follow it, but nothing in the loading mechanism compels obedience; the model can still occasionally deviate. For the large body of conventions that are genuinely advisory, that is exactly what you want. For the few requirements that must hold every time with no exceptions, a rule is the wrong layer. The tool that actually blocks an action regardless of what the model decides is a PreToolUse hook, which runs as a deterministic script at a fixed lifecycle event and can refuse the operation outright. Reach for a hook when "Claude should" needs to become "this will not happen," and keep rules for the conventions where guidance is enough.
There is also a complement to the paths field worth knowing. Where paths decides which files cause a rule to load, the claudeMdExcludes setting decides which CLAUDE.md files and rules to skip, by path or glob pattern. It can be set at any settings layer, user, project, local, or managed policy, so you can keep an ancestor team's CLAUDE.md or an unrelated rules directory out of your context without editing their files. Together the two give you both halves of path-based control: paths scopes a rule in, and claudeMdExcludes scopes unwanted instructions out.
How this shows up on the exam
This knowledge point is assessed at the understand level, so questions test whether you can explain the mechanism rather than just name it. Expect scenarios that describe a rule file and ask why it is or is not loading. The two discriminators are the ones above: whether you know that the paths field is what makes loading conditional (no field means always-on), and whether you remember that patterns must be quoted because the frontmatter is YAML. A surface answer says "rules in .claude/rules/ load only when relevant"; the precise answer ties that behaviour specifically to a quoted paths glob and to read-time triggering. Get the mechanism right and the analyse-level and apply-level knowledge points that follow have a solid base to stand on.
A developer adds .claude/rules/testing.md containing strong test conventions, expecting them to load only when Claude works on test files. The frontmatter reads exactly: a heading '# Testing conventions' followed by the bullet rules, with no other lines. The developer reports the rules load on every session regardless of which file is open. What is the cause?
People also ask
How do path-specific rules work in Claude Code?
What is the paths field in .claude/rules frontmatter?
Where do you put path-specific rules in Claude Code?
Watch and learn
Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.
Anatomy of the .claude/ Folder: The Secret to 10x Claude Code
Why watch: Maps out the .claude/ folder including the rules directory, giving learners the structural context for where path-scoped rule files live.
More videos for this concept
References & primary sources
Master this concept with Archie
Practice it inside an adaptive study session. Archie, your Socratic AI tutor, tracks your mastery with Bayesian Knowledge Tracing and schedules the perfect next review.