Path-Specific Rules
Load conventions only when they matter by scoping rule files to file globs — the fix for conventions scattered across dozens of directories.
Some conventions apply to a *file type* rather than a folder — test files, Terraform, migrations — and those files are scattered across the tree. Path-specific rules solve this by loading a rule file only when you touch matching paths, keeping irrelevant guidance out of context the rest of the time.
How they work
Rule files live in .claude/rules/. Each carries YAML frontmatter with a paths field listing glob patterns. When you edit a file that matches a pattern, that rule loads automatically; otherwise it stays invisible. A rule scoped to terraform/**/* never surfaces while you edit React components.
---
paths: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"]
---
# Test Conventions
- Use describe/it blocks with descriptive names.
- Cover the happy path plus at least one error case.
- Build test data with factory functions.
- Mock external services at module boundaries.
- Assert behavior, not implementation details.Why globs beat the alternatives
Root CLAUDE.md loads for *every* session regardless of what you edit, so putting file-type rules there wastes tokens during unrelated work. Directory-level CLAUDE.md works when conventions map to one folder, but if the same rule applies across 50+ directories you would need a duplicate file in each — a maintenance nightmare. A single glob-scoped rule catches them all at once.
| Scenario | Best tool |
|---|---|
| Universal standards for all code | Root CLAUDE.md |
| Conventions for one package folder | Directory-level CLAUDE.md |
| A file type spread across many folders | Path-specific rules (globs) |
| On-demand task workflow | .claude/skills/ |
Root CLAUDE.md = everywhere. Directory CLAUDE.md = one folder. Path rules = a file pattern across many folders. Skills = on-demand workflow.
Copy the same test conventions into a directory-level CLAUDE.md in every folder that holds tests — 50 identical files to keep in sync.
packages/api/tests/CLAUDE.md
packages/web/tests/CLAUDE.md
packages/cli/tests/CLAUDE.md # ...and 47 moreWrite one path-specific rule in .claude/rules/ whose paths glob matches the file type wherever it lives.
# .claude/rules/tests.md
---
paths: ["**/*.test.ts", "**/*.spec.ts"]
---
- Cover the happy path plus one error case.When conventions apply to a file type scattered across dozens of directories, path-specific rules with globs are correct — not directory-level CLAUDE.md, which would force a duplicate file in every folder.
A path rule quietly guides matching edits; a skill is a workflow you invoke. Don't reach for a skill when you just need always-on-for-this-file-type guidance.
How the exam will try to trick you
The distractors below look right under time pressure — learn the tell.
- The trap
For test conventions shared across 50+ directories, drop a
CLAUDE.mdinto every directory that holds tests.Correct answerWrite one path-specific rule in
.claude/rules/whosepathsglob (e.g.["**/*.test.tsx"]) matches those files anywhere.Why: Duplicating a directory-level file everywhere is a maintenance burden that invites drift.
- The trap
Put file-type conventions like Terraform rules in the root
CLAUDE.md.Correct answerUse a path-scoped rule that loads only when you edit matching files.
Why: Root
CLAUDE.mdloads every session, so those rules burn tokens even while editing unrelated React code. - The trap
Use a
.claude/skills/skill to auto-load conventions whenever a file type is edited.Correct answerUse path-specific rules for background guidance that activates automatically on matching edits.
Why: Skills require invocation; only rules load automatically as Claude reads a matching file.
Key takeaways
- Path-specific rules live in .claude/rules/ with a paths glob in frontmatter.
- Matching rules load only when you edit matching files.
- Globs beat duplicating directory-level CLAUDE.md across many folders.
- File-type rules in root CLAUDE.md waste tokens every session.
- Rules are always-on background for matches; skills are on-demand workflows.
Frequently asked questions
What are path-specific rules in Claude Code?+
They are rule files in .claude/rules/ whose YAML frontmatter lists glob patterns in a paths field. Claude loads a rule automatically only when you edit a file matching one of those patterns, keeping unrelated conventions out of context.
When should I use a glob rule instead of a directory CLAUDE.md?+
Use a glob rule when the same conventions apply to a file type scattered across many directories, such as test files. A directory-level CLAUDE.md would require an identical copy in every folder, whereas one glob-scoped rule covers them all.