Claude Code Configuration & Workflows/Configuration
Intermediate8 min

Path-Specific Rules with .claude/rules/

Scoping Claude behavior to specific file patterns using .claude/rules/ with YAML frontmatter glob paths. When to use path-specific rules vs directory CLAUDE.md, glob pattern syntax, and strategies for reducing irrelevant context.

Quick Reference

  • →Rules files live in .claude/rules/ and are plain Markdown with optional YAML frontmatter
  • →The paths field in frontmatter takes an array of glob patterns that determine when the rule loads
  • →Rules without a paths field load unconditionally -- they behave like additional project-level CLAUDE.md
  • →Glob patterns use standard syntax: ** matches any directory depth, * matches any filename
  • →Rules load dynamically when Claude edits files matching the glob patterns
  • →Path-specific rules reduce token waste by loading only when relevant files are being edited
  • →Use glob patterns for cross-cutting concerns (tests, configs) spread across many directories
  • →Use directory CLAUDE.md for rules that apply to all files within a specific subtree
  • →Multiple rules files can match the same file -- their instructions are merged additively
  • →Rules are committed to git and shared with the team, just like project-level CLAUDE.md

Why Path-Specific Rules?

Not every rule applies to every file. Testing conventions matter when writing tests, but waste context tokens when editing a database migration. Terraform style guides are irrelevant when working on React components. Path-specific rules solve this by loading instructions conditionally based on which files Claude is currently editing.

Without path-specific rules, you have two suboptimal choices: (1) put everything in the root CLAUDE.md and consume tokens on every turn regardless of relevance, or (2) create directory-level CLAUDE.md files, which only work for rules scoped to a single directory tree. Path-specific rules give you a third option: rules that activate based on glob patterns, regardless of where matching files live in the directory structure.

Key Insight

Test files (*.test.ts) are scattered across src/auth/, src/api/, src/utils/, and dozens of other directories. A directory-level CLAUDE.md cannot cover them all without duplication. A single .claude/rules/testing.md with paths: ['**/*.test.ts'] covers every test file in the entire project.