Path-Scoped .claude/rules/
Path-Scoped .claude/rules/
For larger projects, dumping everything into one CLAUDE.md is wasteful: API conventions load even when you're editing CSS. The .claude/rules/ directory splits instructions into topic files that can be scoped to specific paths, so they enter context only when Claude works with matching files.
Layout
Place markdown files under .claude/rules/. All .md files are discovered recursively, so you can nest them by area:
A rule without paths frontmatter loads at launch with the same priority as .claude/CLAUDE.md — i.e. it is an always-on instruction, just modularized.
YAML frontmatter + glob paths
Add a paths field in YAML frontmatter to make a rule conditional. It only applies when Claude reads files matching the glob(s):
You can list multiple patterns and use brace expansion:
Common globs: **/*.ts (all TS anywhere), src/**/* (everything under src/), *.md (markdown in the project root only), src/components/*.tsx (one directory). Path-scoped rules trigger when Claude reads a matching file, not on every tool use.
User-level rules and symlinks
Personal rules live in ~/.claude/rules/ and apply to every project. User-level rules load before project rules, so project rules have higher priority. The directory also supports symlinks, so a team can maintain one shared rule set and link it into many repos; circular symlinks are detected and handled gracefully.
Rules vs CLAUDE.md vs Skills
| Mechanism | Loads | Best for |
|---|---|---|
| CLAUDE.md | Every session, in full | Project-wide facts, "always do X" |
.claude/rules/ (no paths) | Every session | Modular always-on topics |
.claude/rules/ (with paths) | When matching files are touched | File-type / directory-specific conventions |
| Skills | Only when invoked or judged relevant | Multi-step procedures, large reference docs |
Path-scoped rules are the architect's main tool for shrinking the always-loaded context without losing coverage: the API rule is present exactly when Claude touches API files and absent otherwise. Use the InstructionsLoaded hook to log which rules fired if behavior surprises you.
Exam focus: .claude/rules/*.md are discovered recursively; no paths → always loaded at .claude/CLAUDE.md priority; paths: glob → conditional, triggered when Claude reads a matching file. User-level ~/.claude/rules/ load before (lower priority than) project rules. Reach for path-scoped rules — not @ imports — when you need to cut always-on context.*