A .claude/rules/ file without paths frontmatter loads for every edit. In a project with 7 technology areas, a developer editing Python files loads 2,800 tokens of rules — Python, React, Go, Terraform, Testing, Deploy, Security. Only 400 tokens (the Python rules) are relevant. The other 2,400 tokens — 86% — are waste.
Adding paths globs to each rules file fixes this in one step. The Python rules file gets paths: ["**/*.py"]. It loads only when editing Python files. Everything else stays out of context.
The Syntax
---
paths:
- "src/api/**/*"
- "src/graphql/**/*"
---
API conventions here.** matches any depth of subdirectories. * matches any filename. src/api/**/* matches src/api/users.ts, src/api/v2/billing/handler.ts, and everything in between.
If the glob does not match when you expect it to, check the YAML syntax — quoting issues and indentation errors are the most common causes.
Overlapping Patterns Load Simultaneously
This surprises people. If react-rules.md has paths: ["**/*.tsx"] and testing-rules.md has paths: ["**/*.test.tsx"], editing Button.test.tsx loads both files.
This is a feature. Button.test.tsx is both a React component file and a test file. When writing a component test, you need React conventions (component patterns) AND testing conventions (test structure, assertion style). Multiple rules loading simultaneously gives you exactly the context you need.
There is no specificity priority. There is no cancellation. Each pattern is evaluated independently.
Layered Architecture: The Right Way to Handle Overlaps
A monorepo with 4 languages and 3 cross-cutting concerns (testing, security, docs) does not need 12 combination files (python-testing.md, python-security.md, etc.). That is a maintenance nightmare.
Instead, use two layers:
Language rules match by directory and extension:
react.md→paths: ["frontend/**/*.tsx"]python.md→paths: ["data/**/*.py"]node-api.md→paths: ["backend/**/*.ts"]
Cross-cutting rules match by filename or directory pattern:
testing.md→paths: ["**/*.test.*", "**/*.spec.*"]security-auth.md→paths: ["**/auth/**/*"]
A Python test file in data/pipeline/test_loader.py loads both python.md and testing.md. An auth handler in backend/auth/handler.ts loads both node-api.md and security-auth.md. Each file gets exactly the rules it needs from both layers.
This is the key advantage of path globs over directory-level CLAUDE.md files. Directory CLAUDE.md can only scope by location. Path globs can scope by filename pattern — reaching across the entire project tree to find test files, auth files, or migration files wherever they live.
Cross-Contamination: The Problem Paths Solve
A 2,500-token monolithic CLAUDE.md containing React, API, database, testing, and deployment conventions causes cross-contamination. Claude sometimes applies React conventions when editing API code.
This is not a model error. All 2,500 tokens load for every edit. Claude must infer which section applies to the current file. Section headers (”## React Only”) do not control loading — the entire file is in context regardless.
The fix is structural: split into 5 path-scoped rules files. React rules load only for .tsx files. API rules load only for src/api/ files. The possibility of cross-application is eliminated — rules that are not loaded cannot be misapplied.
Coexisting Conventions During Migration
During a REST-to-GraphQL migration, both API styles coexist:
# .claude/rules/rest-conventions.md
---
paths: ["src/api/rest/**/*"]
---
# .claude/rules/graphql-conventions.md
---
paths: ["src/api/graphql/**/*"]
---REST conventions load for REST code. GraphQL conventions load for GraphQL code. No cross-contamination. When migration completes, delete rest-conventions.md.
A single combined file with paths: ["src/api/**/*"] loads both convention sets for any API file — risking GraphQL patterns in REST code.
The Full-Stack Edge Case
After migrating from monolithic CLAUDE.md to 8 path-scoped files, average context dropped 85% (3,000 → 450 tokens). But one full-stack developer who edits 6 of 8 file types per session only saw a 27% reduction (3,000 → 2,200).
This is expected, not failure. Path-specific rules optimize for focused sessions. A developer working on one technology area sees dramatic savings. A developer touching everything in one session sees smaller but still positive gains. The architecture serves the common case (focused editing) without penalizing the edge case (broad editing).
Anti-Patterns
paths: ["**/*"]— Matches every file. Functionally identical to omitting paths, but misleading. If rules apply universally, either omit paths or put them in CLAUDE.md.- Monolithic CLAUDE.md with section headers — Section headers do not control loading. All content loads regardless. Split into path-scoped rules.
- No-rules = no-review — Rules provide convention context, but Claude reviews for bugs and security without custom rules too. Files without matching rules still benefit from general analysis.
CI Integration
Path-specific rules work seamlessly in CI. When Claude Code reviews auth files, security rules auto-load. When reviewing documentation, docs rules auto-load. No CI script logic needed to select the right rules — the paths globs handle it.
One-liner: paths globs in rules frontmatter turn unconditional loading into conditional loading — multiple matching rules stack, language rules and cross-cutting rules layer naturally, and 86% of context waste disappears.