Path-Specific Rules

Estimated time: 20 minutes

Path-specific rules attach instructions to file patterns rather than directories. They load only when files matching the glob are touched, which keeps Claude's context lean and relevant. This is the right tool when conventions span multiple directories.

The .claude/rules/ Pattern

Place rule files in .claude/rules/ with YAML frontmatter specifying glob patterns:

---
paths:
  - "**/*.test.tsx"
  - "**/*.spec.ts"
---
# Test File Conventions

All test files must follow Arrange-Act-Assert.
Use describe blocks to group related tests.
Mock external services with jest.mock at the top of the file.
Avoid sleep() — use jest.useFakeTimers() for time-dependent code.

Why Path-Specific Beats Subdirectory CLAUDE.md

If your convention is "all test files follow AAA pattern", you have three options:

  1. Project-level CLAUDE.md. Loaded for every interaction, even when editing non-test files. Wastes tokens and pollutes context.
  2. Subdirectory CLAUDE.md. Loaded only when working in that subdirectory. But tests live in src/__tests__/, frontend/tests/, AND backend/tests/ — three copies to maintain.
  3. Path-specific rule. Loaded when files matching the glob are touched. One file. Works across all three test directories.

Path-specific wins for cross-directory conventions.

Token Budget Awareness

Every loaded CLAUDE.md or rule eats tokens from Claude's context window. A 1000-line project CLAUDE.md is 1000 lines that the model carries on every turn. Path-specific rules narrow the load — only relevant rules show up when relevant files are involved.

Glob Pattern Reference

PatternMatches
**/*.test.tsxAny .test.tsx file at any depth
terraform/**/*Anything inside terraform/ at any depth
src/api/**/*.tsAny .ts file inside src/api/ at any depth
{frontend,backend}/tests/**Anything inside frontend/tests or backend/tests

Multiple Rules, Multiple Files

Don't pile every convention into a single rule file. Split by concern: testing.md, api-conventions.md, terraform-style.md. Each has its own glob. When Claude touches a file matching multiple rules, all matching rules load — but you don't pay the cost when working outside their scope.

Skills to Develop

  1. Recognize when a convention spans multiple directories — that's the signal for a path-specific rule.
  2. Write specific glob patterns rather than overly broad ones (**/* defeats the purpose).
  3. Split rules by concern so each file is focused and small.
Exam tip: If a question mentions test conventions across multiple directories, the answer is path-specific rules. Subdirectory CLAUDE.md would require duplication; project CLAUDE.md wastes tokens on non-test work.
← Back to Module