Skip to main content

3.3 Path-specific rules for conditional convention loading

Rule files in .claude/rules/ take a YAML frontmatter paths field with glob patterns. The rule loads only when editing matching files — cutting irrelevant context and token usage.

.claude/rules/testing.md
---
paths: ["**/*.test.tsx", "**/*.test.ts", "**/__tests__/**/*"]
---

- One `describe` per exported symbol; test names read as sentences.
- Use the shared factories in `test/factories`, never inline fixture literals.
- Assert on observable behaviour, never on internal call counts.
.claude/rules/terraform.md
---
paths: ["terraform/**/*"]
---

- Every resource carries the standard tag block.
- No inline credentials; reference the `secrets` data source.

Glob rules vs directory CLAUDE.md​

The deciding question

Are the files spread across directories?

Test files sitting next to the code they test (Button.test.tsx beside Button.tsx) are spread throughout the codebase. A directory-level CLAUDE.md is directory-bound and cannot follow them. A glob rule (**/*.test.tsx) applies by file type regardless of location — and it does so automatically, which skills (manual invocation) and a monolithic CLAUDE.md (relies on the model inferring which section applies) do not.

OptionVerdict for cross-cutting conventions
.claude/rules/ with paths globsCorrect — automatic, path-matched, deterministic
One root CLAUDE.md with headers per areaRelies on inference — unreliable
Skills per code typeRequires invocation — not automatic
A CLAUDE.md per subdirectoryDirectory-bound — cannot cover spread-out files

Quiz​

  1. Question 1

    Your codebase has distinct conventions per area, and test files sit next to the code they test (Button.test.tsx beside Button.tsx). You want all tests to follow the same conventions regardless of location, applied automatically. What is the most maintainable approach?

  2. Question 2

    The repository keeps Terraform under infra/, Python services under services/, and test files beside the code they test as *_test.py throughout services/. You want Terraform naming rules loaded only when a Terraform file is edited, and pytest fixture conventions loaded only when a test file is edited, with no unrelated context in either case. Which configuration achieves this?

  3. Question 3

    Migration files live in db/migrations/, but three packages keep their own under packages/*/migrations/. The conventions that must apply — transactional wrapping, reversible down steps — apply to all of them and to nothing else. New packages are added every few months. What configuration fits?

  4. Question 4

    Your team maintains nine convention documents totalling about 1,800 lines, each applying to a distinct slice of the codebase, and all nine are currently @imported into CLAUDE.md. What does converting them to path-scoped .claude/rules/ files buy?