3.3 Path-Specific Rules
3.3.1 The Problem: Conventions That Live Everywhere
You've met two configuration layers: always-on CLAUDE.md (3.1) and on-demand skills (3.2). There's a gap between them that Task Statement 3.3 fills. Consider a real situation: your test files follow specific conventions, but those test files are scattered all over the codebase — Button.test.tsx sits next to Button.tsx, api.test.ts next to api.ts, across fifty directories. You want Claude to apply the test conventions whenever it touches a test file, no matter where that file lives. How?
The always-on option is clumsy: cram the test conventions into the root CLAUDE.md, and now they're loaded into EVERY session — burning context even when you're nowhere near a test file. The directory-level option is worse: a CLAUDE.md is bound to its directory, but your test files are spread across fifty directories, so you'd have to duplicate the conventions fifty times. Neither fits a convention that applies to a TYPE of file regardless of location.
Path-specific rules are the answer. They let you say: 'load THESE instructions ONLY when Claude is working with files matching THIS pattern.' The test conventions load when Claude touches any *.test.tsx file, anywhere — and stay out of context the rest of the time. It's conditional, pattern-based loading: the right instructions at the right moment, with no waste.
A convention for a file TYPE spread across many directories: root CLAUDE.md wastes context, per-directory CLAUDE.md means duplicating 50×, and a path-specific rule loads exactly when relevant from one file.
The one idea to hold onto
Path-specific rules load instructions ONLY when Claude works with files matching a glob pattern. They're the right tool for conventions that apply to a file TYPE spread across many directories — conditional, not always-on, and defined once.
3.3.2 How Path-Specific Rules Work
A path-specific rule is a markdown file in the .claude/rules/ directory (the same rules directory from 3.1) — but with a piece of YAML frontmatter at the top called paths. That paths field holds glob patterns, and it's what makes the rule conditional: the rule loads into context ONLY when Claude is working with a file matching one of those patterns. A rule WITHOUT a paths field, by contrast, loads unconditionally every session (that's the default rules behavior from 3.1).
---
paths:
- "**/*.test.tsx"
- "**/*.test.ts"
---
# Testing conventions
- Every test uses the Arrange-Act-Assert structure.
- Mock external services; never hit a live API in a unit test.
- One behavior per test; name tests describe-it style.The glob patterns are flexible, and matching them to intent is the skill. **/*.ts matches every TypeScript file anywhere; src/api/**/* matches everything under the API directory; *.md matches markdown in the project root only; and brace expansion like src/**/*.{ts,tsx} matches multiple extensions in one pattern. You choose the pattern to match the files your convention should govern — by type, by directory, or both.
| Glob pattern | Matches |
|---|---|
| **/*.ts | Every TypeScript file, any directory |
| src/api/**/* | Everything under src/api/ |
| *.md | Markdown files in the project root only |
| src/**/*.{ts,tsx} | TS and TSX files under src/ (brace expansion) |
Glob patterns let you target files by extension, directory, or both. The pattern decides exactly when the rule loads.
3.3.2 — Key Concept
A path-specific rule is a .claude/rules/ file with a YAML paths field of glob patterns; it loads ONLY when Claude works with matching files. A rule without paths loads unconditionally. This is how you make instructions conditional on file type or location.
3.3.3 Choosing the Right Mechanism
You now have four ways to give Claude instructions, and the exam rewards picking the right one for the shape of the need. Here's the decision in one table — it ties together 3.1, 3.2, and 3.3.
| The instruction… | Use | Why |
|---|---|---|
| Applies to EVERYTHING, always | Root CLAUDE.md | Universal, always-on |
| Applies to ONE package/directory | Directory-level CLAUDE.md | Bound to that directory |
| Applies to a FILE TYPE across many dirs | Path-specific rule | Loads only on matching files, defined once |
| Is an on-demand TASK workflow | Skill | Loads when invoked, not always |
The four-way decision. The distinguishing question for rules: does the convention follow a file TYPE across the codebase? Then it's a path-specific rule, not a CLAUDE.md.
The key discriminators: 'universal vs file-type-specific' separates root CLAUDE.md from path-specific rules. 'Spread across many directories vs confined to one' separates path-specific rules from directory-level CLAUDE.md. And 'always-on reference vs on-demand procedure' separates rules (always-on for matching files) from skills (loaded only when invoked). Match the shape of the need to the mechanism and the rest follows.
3.3.3 — Key Concept
Universal → root CLAUDE.md; one package → directory CLAUDE.md; a file TYPE across many directories → path-specific rule; an on-demand task workflow → skill. The path-specific rule is uniquely suited to conventions that follow a file type regardless of where those files live.
3.3.4 The Exam Traps
The 3.3 traps test whether you'll reach for the right mechanism when conventions are spread across the codebase. The wrong answers are usually the OTHER three mechanisms applied where they don't fit.
The signature scenario: test files (or API handlers, or terraform files) are scattered throughout the codebase, and you want their conventions applied automatically wherever they appear. The answer is a path-specific rule with a glob (e.g. **/*.test.tsx). Why not the alternatives? Root CLAUDE.md would load the conventions every session (wasted context). A directory-level CLAUDE.md is bound to one directory and can't span the many directories the files live in (you'd duplicate it). And a skill requires manual invocation or relies on Claude choosing to load it — but the requirement is AUTOMATIC, deterministic loading based on file path, which only path-specific rules provide.
3.3.4 — Exam Trap
For conventions on a file TYPE spread across many directories, choose a path-specific rule with a glob. ✗ Root CLAUDE.md (loads always, wastes context). ✗ Directory-level CLAUDE.md (bound to one dir, can't span many). ✗ A skill (needs invocation / isn't automatic per-file). ✓ A .claude/rules/ file with a paths glob — automatic and defined once.
3.3.5 Put It Together: Scope Rules by Path
You now understand path-specific rules, their glob patterns, and how they fit alongside CLAUDE.md and skills. The exercise has you create several path-scoped rules and confirm they load only when relevant — and measure the context you save versus stuffing everything into the root CLAUDE.md.
3.3.5 — Build Exercise (30 min)
(1) Create three rule files in .claude/rules/ with paths frontmatter: testing conventions for **/*.test.*, API conventions for src/api/**/*, and infra conventions for terraform/**/*. (2) Open a test file and use /memory to confirm only the testing rule loaded; open an API file and confirm only the API rule loaded. (3) Compare the launch context footprint to a version where all three sets of conventions live in the root CLAUDE.md. (4) Note why a directory-level CLAUDE.md couldn't have handled the test files spread across many directories.
That completes the configuration-loading trio: always-on CLAUDE.md (3.1), on-demand skills (3.2), and conditional path-specific rules (3.3). The next lesson, 3.4, shifts from WHAT Claude knows to HOW it works — choosing plan mode versus direct execution for a task.
Where this shows up on the exam
3.3 questions describe conventions for a file type scattered across the codebase. If your reflex is 'path-specific rule with a glob' — and you can say why root CLAUDE.md (always-on), directory CLAUDE.md (one dir), and skills (invoked) don't fit — you'll answer correctly.
Key Takeaways
- ✓Path-specific rules load instructions ONLY when Claude works with files matching a glob — the right tool for conventions that apply to a file TYPE spread across many directories.
- ✓A path-specific rule is a .claude/rules/ markdown file with a YAML paths field of glob patterns; a rule WITHOUT paths loads unconditionally every session.
- ✓Glob patterns target by extension/directory/both: **/*.ts (all TS), src/api/**/* (under a dir), *.md (root only), src/**/*.{ts,tsx} (brace expansion).
- ✓Decision: universal → root CLAUDE.md; one package → directory CLAUDE.md; a file type across many dirs → path-specific rule; on-demand workflow → skill.
- ✓Path-specific rules beat root CLAUDE.md (which loads always, wasting context) and directory CLAUDE.md (bound to one directory) when files are spread across the codebase.
- ✓They beat a skill for this case because loading is AUTOMATIC and deterministic based on file path, not dependent on manual invocation.
- ✓Defining the convention once (in one rule file) avoids duplicating it across the many directories the matching files live in.
Check Your Understanding
Test what you learned in this lesson.
Q1.Test files are spread throughout the codebase (Button.test.tsx next to Button.tsx, etc.) and you want their conventions applied automatically whenever Claude works on a test file, regardless of location. What's the most maintainable approach?
Q2.What distinguishes a path-specific rule from a regular rule in .claude/rules/?
Q3.Why is a directory-level CLAUDE.md a poor fit for conventions governing test files spread across 50 directories?
Q4.Which glob pattern would apply a rule to all TypeScript and TSX files under the src/ directory?
Practice This Lesson