Apply Path-Specific Rules for Conditional Convention Loading
This module is about loading the right context only when they are relevant.
Claude Code’s docs say .claude/rules/ lets larger projects organize instructions into multiple files. Path-scoped rules load only when Claude works with files matching the configured path patterns, reducing noise and saving context space. (Claude)
1. Core Mental Model
Use path-specific rules when an instruction should apply to a few directories, but not the whole project.
Root CLAUDE.md:
Always-loaded project-wide instructions.
Directory CLAUDE.md:
Instructions for a subtree, such as packages/api/.
.claude/rules/*.md with paths:
Conditional rules for file types, patterns, or cross-cutting conventions.
2. What a Path-Specific Rule Looks Like
Rules are markdown files under:
Each rule can include YAML frontmatter with a paths field.
Example:
---
paths:
- "**/*.test.tsx"
- "**/*.spec.tsx"
---
# React Test Rules
- Use React Testing Library.
- Prefer user-visible assertions over implementation details.
- Avoid snapshot tests unless explicitly justified.
- Mock network calls at the boundary, not inside components.
This rule should apply to test files regardless of where they are located.
Claude Code docs show the same pattern: a paths field in YAML frontmatter, using glob patterns such as src/api/**/*.ts, controls when the rule applies. Rules without a paths field load unconditionally. (Claude)
3. Why Path-Scoped Rules Matter
Without path-specific rules, large repos often end up with a bloated CLAUDE.md:
This causes two problems:
1. Irrelevant instructions consume context.
2. Claude may apply the wrong convention to the wrong file.
Claude Code docs explicitly warn that longer always-loaded files consume more context and may reduce adherence. They recommend path-scoped rules when instructions are growing large, because those rules load only when Claude works with matching files, which keeps irrelevant material out of the context window. (Claude)
4. Path-Specific Rules Vs Directory-Level CLAUDE.md
4.1 Directory-Level CLAUDE.md
Best when the convention maps cleanly to a directory.
Example:
Good for:
- All API package code
- All backend service conventions
- A package-specific build command
- A subsystem-specific architecture note
4.2 Path-Specific Rule
Best when the convention maps to a filetype or naming pattern across many directories.
Example, files with .test.tsx name in any directory:
Good for:
- Tests spread across packages
- Terraform files in multiple infra directories
- Migration files in several services
- Markdown docs across repo
- Generated schema files
- React components in multiple apps
Anthropic’s Claude Code blog gives the same practical guidance: choose a path-scoped rule over a nested CLAUDE.md when the instruction concerns a cross-cutting file pattern that appears in multiple, but not all, parts of the codebase. (Claude)
7. Good Rule Design
7.1 One Topic Per Rule File
Good:
.claude/rules/testing.md
.claude/rules/api-handlers.md
.claude/rules/terraform.md
.claude/rules/migrations.md
.claude/rules/react-components.md
Bad:
Claude Code docs recommend descriptive filenames such as testing.md or api-design.md, and note that all markdown files under .claude/rules/ are discovered recursively, so you can organize them into subdirectories like frontend/ or backend/. (Claude)
7.2 Keep Paths Precise
Too broad:
Better:
Why?
7.3 Avoid Conflicting Rules
Bad:
Better:
Claude Code docs warn that conflicting instructions can cause Claude to pick one arbitrarily. (Claude)
7.4 Keep Rule Text Actionable
Weak:
Strong:
# Test Rules
- Add regression tests for bug fixes.
- Prefer behavior-focused assertions over implementation details.
- Avoid broad snapshots unless the component is intentionally snapshot-tested.
- Put tests next to the file under test unless the package already uses a separate test directory.
Path-specific rules are still instructions, not hard enforcement. If a behavior must be guaranteed, you need hooks or permissions, not just a rule.
Claude Code docs state that CLAUDE.md and related instruction files are context rather than enforced configuration; hooks or settings are needed for deterministic blocking. (Claude)
8. Choosing the Right Mechanism
| Scenario | Best mechanism |
|---|---|
| “Use pnpm in this repo.” | Root CLAUDE.md |
| “API package uses standard error envelope.” | packages/api/CLAUDE.md or path rule for API handlers |
“All *.test.tsx files use Testing Library conventions.” |
Path-specific rule |
“Terraform files live in infra/ and deploy/.” |
Path-specific rule |
| “All backend package code uses repository pattern.” | Directory packages/api/CLAUDE.md |
| “All migration files are append-only, wherever they live.” | Path-specific rule |
| “Run release checklist.” | Skill or slash command |
| “Block destructive Bash commands.” | Settings/hooks/permissions, not rules |
10. Common Traps
10.1 Trap 1: Using Directory CLAUDE.md for Cross-Cutting Files
Scenario:
Wrong:
Create apps/web/CLAUDE.md, packages/api/CLAUDE.md, and services/billing/CLAUDE.md with duplicate test rules.
Right:
10.2 Trap 2: Making the Glob Too Broad
Wrong:
Right:
10.3 Trap 3: Expecting Path Rules to Run Commands
Wrong expectation:
Correct:
Rules guide behavior. They do not enforce command execution. Use hooks for deterministic enforcement.
10.4 Trap 4: Using Path Rules for Procedural Workflows
Wrong:
---
paths:
- "**/*.ts"
---
# Release Workflow
1. Generate release notes.
2. Update changelog.
3. Tag release.
4. Deploy.
Better:
Path rules are for conditional conventions, not occasional workflows.