.claude/rules/ files carry YAML frontmatter with a paths field of glob patterns, so a given rule file loads into context only when a matching file is being edited:
---
paths: ["terraform/**/*"]
---
Two concrete payoffs: token efficiency (conventions for Terraform never load into context when you're editing something unrelated) and cross-directory reach — a pattern like paths: ["**/*.test.tsx"] covers test files no matter which directory they're scattered across, which a directory-scoped CLAUDE.md structurally cannot do.
The discriminator: does the convention follow a file type across many directories, or is it confined to one subtree? Type-following conventions (React component rules, test-file rules, API-handler rules) want path rules with glob frontmatter. Subtree-confined conventions want a directory-level CLAUDE.md instead. Consolidating everything under headers in one root CLAUDE.md and relying on the model to infer which section applies is inference, not explicit matching — exactly the failure this mechanism exists to avoid. And a CLAUDE.md per directory doesn't help when the actual convention (say, "all test files, wherever they live") cuts across directories rather than respecting them.
This is one of the trickier discriminators in the domain, so it's worth having the two use-cases stated side by side rather than only as a single sentence:
Use path rules when:
- The convention follows a file type, not a location
- Matching files are scattered across many directories
- Token efficiency matters — irrelevant conventions should never load
- You want explicit matching, not the model inferring relevance
Use directory-level CLAUDE.md when:
- The convention applies only within one subtree
- The relevant files all live under a single directory
- You want scoped loading without writing a glob pattern
Cross-module link: explicit matching beating inference is the same discriminator from Module 2's tool design guidance — a well-scoped path rule is doing for file conventions what a well-differentiated tool description does for tool selection: giving the model something to match against directly, rather than something to guess about.