What You Need to Know
Path-specific rules are the mechanism for applying conventions conditionally based on which files you are editing. They solve a problem that neither root CLAUDE.md nor directory-level CLAUDE.md files handle well: conventions that must apply to files of a specific type spread across many directories.
How Path-Specific Rules Work
Rule files live in the .claude/rules/ directory. Each file contains YAML frontmatter with a paths field specifying glob patterns. The rules inside the file load only when you are editing files that match those patterns.
--- paths: ["terraform/**/*"] --- # Terraform Conventions - Use snake_case for all resource names - Tag every resource with environment and team labels - Never hardcode AMI IDs — use data sources - All modules must have a variables.tf, outputs.tf, and README.md
When you edit a file matching terraform/**/*, these rules load automatically. When you edit a React component or an API handler, they do not. The rules are invisible until relevant.
Glob Patterns Match Across the Entire Codebase
This is the critical advantage. A glob pattern like **/*.test.tsx catches every test file in the codebase, regardless of which directory it sits in. Consider a typical project structure:
src/
components/
Button.tsx
Button.test.tsx
api/
auth.ts
auth.test.ts
utils/
format.ts
format.test.ts
pages/
dashboard/
Dashboard.tsx
Dashboard.test.tsx
Test files are co-located with their source files across four different directories. A path-specific rule with paths: ["**/*.test.tsx", "**/*.test.ts"] applies the same test conventions to every one of these files, automatically.
Why Not Directory-Level CLAUDE.md?
A directory-level CLAUDE.md applies to files in that one directory. To apply test conventions to test files spread across 50+ directories, you would need to place a CLAUDE.md file in every single directory containing tests. That means:
- 50+ copies of the same conventions
- Every new directory with tests needs a new copy
- Any convention change requires updating all 50+ files
- Inevitable drift as some copies fall behind
Path-specific rules with glob patterns eliminate this entirely. One file, one pattern, universal coverage.
Why Not Root CLAUDE.md?
Root CLAUDE.md loads for every session, regardless of which files you edit. If your Terraform conventions are in the root CLAUDE.md, they consume tokens even when you are editing React components. If your test conventions are in the root, they load when you are writing API handlers.
Key Concept
Path-scoped rules are more token-efficient than root CLAUDE.md because they load ONLY when editing matching files. This reduces irrelevant context and keeps the model focused on conventions that actually apply to the current work. In large projects with many convention categories, this efficiency gain is substantial.
Practical Rule File Examples
Test conventions across the entire codebase:
--- paths: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"] --- # Test Conventions - Use describe/it blocks with descriptive names that read as sentences - Each test file must have at least one happy path and one error case - Use factory functions for test data, not inline object literals - Mock external services at the module boundary, not individual functions - Assert behaviour, not implementation details
API conventions for any route handler:
---
paths: ["src/api/**/*", "**/routes/**/*", "**/*.controller.ts"]
---
# API Conventions
- All endpoints return { data, error, metadata } response shape
- Use Zod schemas for request validation at the handler boundary
- Log request ID on every error response
- Rate limiting configuration must be explicit, not inherited from defaults
Infrastructure-as-code conventions:
--- paths: ["terraform/**/*", "**/*.tf", "infrastructure/**/*"] --- # Infrastructure Conventions - State files must reference remote backends, never local - Use workspaces for environment separation - Every module must be versioned with a CHANGELOG
When to Use Each Approach
| Scenario | Best approach |
|---|---|
| Universal team standards that apply to all code | Root CLAUDE.md |
| Conventions for one specific package directory | Directory-level CLAUDE.md |
| Conventions for a file type spread across many directories | Path-specific rules with glob patterns |
| Task-specific workflows invoked on demand | Skills in .claude/skills/ |
The exam frequently presents the scenario of test files co-located with source files across many directories. The answer is always path-specific rules with glob patterns.
Exam Traps
Choosing directory-level CLAUDE.md over path-specific rules for cross-directory conventions
When conventions must apply to files spread across 50+ directories (like co-located test files), path-specific rules with glob patterns are correct. Directory-level CLAUDE.md would require placing a file in every directory — a massive maintenance burden.
Placing file-type-specific conventions in root CLAUDE.md
Root CLAUDE.md loads for every session regardless of which files you edit. Terraform conventions consume tokens when editing React components. Path-specific rules load only when editing matching files, preserving token budget.
Confusing skills with path-specific rules for automatic convention application
Skills are on-demand and require explicit invocation. Path-specific rules load automatically based on file paths. When the question asks about automatic, conditional convention loading, the answer is path-specific rules, never skills.
Practice Scenario
A codebase has test files co-located with source files throughout 50+ directories (e.g., Button.test.tsx next to Button.tsx). The team wants all tests to follow the same conventions regardless of location. What is the most maintainable approach?
Build Exercise
Configure Path-Specific Rules with Glob Patterns
What you'll learn
- Write YAML frontmatter with glob patterns for conditional rule loading
- Apply path-specific rules to files spread across many directories
- Understand why path-specific rules are more token-efficient than root CLAUDE.md
- Distinguish when to use path-specific rules vs directory-level CLAUDE.md
- Verify conditional loading behaviour using the /memory command
- Create .claude/rules/testing.md with YAML frontmatter paths: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"] and test conventions (naming, assertions, mocking patterns)
Why: Path-specific rules with glob patterns are the correct solution for conventions that apply to a file type spread across many directories. The exam favourite scenario is test files co-located with source files across 50+ directories.
You should see: A file at .claude/rules/testing.md with YAML frontmatter containing a paths array with glob patterns. The body contains at least three test conventions covering naming, assertions, and mocking.
- Create .claude/rules/api-conventions.md with paths: ["src/api/**/*", "**/routes/**/*"] and API conventions (response shape, validation, error handling)
Why: Separating API conventions into their own path-scoped rule means they only load when editing API files. This avoids consuming tokens with irrelevant context when working on frontend or infrastructure code.
You should see: A file at .claude/rules/api-conventions.md with YAML frontmatter paths targeting API directories. The body contains at least three API conventions.
- Create .claude/rules/terraform.md with paths: ["terraform/**/*", "**/*.tf"] and infrastructure conventions
Why: Infrastructure conventions are completely irrelevant when editing application code. Path-scoped rules ensure Terraform rules never consume tokens during React or API development sessions.
You should see: A file at .claude/rules/terraform.md with YAML frontmatter paths matching Terraform files. The body contains infrastructure-specific conventions.
- Edit a test file and use /memory to verify that testing rules are loaded but API and Terraform rules are not
Why: This proves the conditional loading mechanism works. The exam tests whether you understand that path-specific rules load only for matching files, and /memory is the diagnostic tool to verify this.
You should see: When editing a .test.ts file, /memory output lists .claude/rules/testing.md as loaded. The .claude/rules/api-conventions.md and .claude/rules/terraform.md files do NOT appear in the /memory output.
- Edit an API handler and verify that API rules load while testing and Terraform rules do not
Why: This is the complementary verification. Switching contexts should swap which rules are loaded, confirming that the glob patterns correctly scope each rule file.
You should see: When editing a file in src/api/, /memory output lists .claude/rules/api-conventions.md as loaded. The testing and Terraform rule files do NOT appear.
- Compare the token footprint when all conventions are in root CLAUDE.md versus split into path-specific rules
Why: Token efficiency is a key exam concept. Root CLAUDE.md loads all conventions for every session regardless of relevance. Path-specific rules load only matching conventions, reducing irrelevant context and preserving token budget for actual work.
You should see: With all conventions in root CLAUDE.md, /memory shows the full set of conventions loaded even when editing a simple utility file. With path-specific rules, /memory shows only the relevant subset. The token count for loaded configuration is measurably smaller when using path-specific rules for targeted editing sessions.