Skip to content

Apply Path-Specific Rules for Conditional Convention Loading

This module is about loading the right conventions only when they are relevant.

In D3.1, we covered CLAUDE.md hierarchy. In D3.3, the key mechanism is:

.claude/rules/*.md

with YAML frontmatter like:

---
paths:
  - "**/*.test.tsx"
---

Claude Code’s docs say .claude/rules/ lets larger projects organize instructions into multiple files, and 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

v Use path-specific rules when an instruction should apply to 3.., 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.

The exam shortcut:

Convention applies everywhere? CLAUDE.md.
Convention applies to one directory tree? Directory-level CLAUDE.md.
Convention applies to files scattered across the repo? Path-specific rule.

2. What a path-specific rule looks like

Rules are markdown files under:

.claude/rules/

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)

[!CAUTION] Exam answer vs. real-world reliability. The official guide and the exam use the paths: frontmatter field, so on the exam paths: is the correct answer. In current Claude Code, however, the globs: frontmatter field is the more reliably-working one for path scoping. The paths: form has documented loading bugs, and paths: rules placed in ~/.claude/rules/ (user scope) are known to be silently ignored. If a rule is not loading as expected in practice, switching the frontmatter key from paths: to globs: (and moving the rule to project scope rather than user scope) is the pragmatic fix. (See anthropics/claude-code GitHub issues #17204, #22170, and #13905.)

Summary: exam answer = paths:; real-world reliability caveat = globs:.

3. Why path-scoped rules matter

Without path-specific rules, large repos often end up with a bloated CLAUDE.md:

# CLAUDE.md

## API Rules
...

## React Rules
...

## Terraform Rules
...

## Test Rules
...

## Database Migration Rules
...

## Deployment Rules
...

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

This is the main exam distinction.

Directory-level CLAUDE.md

Best when the convention maps cleanly to a directory.

Example:

packages/api/CLAUDE.md

Good for:

All API package code
All backend service conventions
A package-specific build command
A subsystem-specific architecture note

Path-specific rule

Best when the convention maps to a file type or naming pattern across many directories.

Example:

.claude/rules/react-tests.md

with:

---
paths:
  - "**/*.test.tsx"
  - "**/*.spec.tsx"
---

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)

5. Glob pattern examples

Claude Code supports glob-style path patterns in the paths field. The docs show examples such as **/*.ts, src/**/*, *.md, src/components/*.tsx, and brace expansion like src/**/*.{ts,tsx}. (Claude)

Common exam patterns

All TypeScript tests

---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"
  - "**/*.spec.tsx"
---

# Test Rules

- Follow existing test style in the nearest package.
- Prefer behavior-focused assertions.
- Add regression tests for bug fixes.

Terraform files anywhere

---
paths:
  - "terraform/**/*"
  - "**/*.tf"
  - "**/*.tfvars"
---

# Terraform Rules

- Do not hardcode secrets.
- Prefer module variables over duplicated literals.
- Run terraform fmt after editing.
- Document new variables.

Database migrations

---
paths:
  - "**/migrations/**/*"
  - "**/*.migration.ts"
  - "**/*.sql"
---

# Migration Rules

- Treat applied migrations as append-only.
- Do not edit historical migrations unless explicitly instructed.
- Include rollback guidance when the migration framework supports it.
- Keep data migrations idempotent where possible.

API handlers across multiple packages

---
paths:
  - "packages/*/src/api/**/*.ts"
  - "services/*/handlers/**/*.ts"
  - "**/*.handler.ts"
---

# API Handler Rules

- Validate input at the boundary.
- Use the standard error response format.
- Do not access the database directly from handlers; use service/repository layers.
- Add or update route-level tests for behavioral changes.

React components in multiple apps

---
paths:
  - "apps/*/src/components/**/*.tsx"
  - "packages/ui/**/*.tsx"
---

# React Component Rules

- Prefer design-system primitives before creating new components.
- Keep components accessible by default.
- Avoid business logic inside presentational components.
- Add story or test coverage for reusable UI components.

6. When rules load

Path-specific rules are conditional.

If the file path matches the rule’s paths pattern:
  the rule can load.

If the file path does not match:
  the rule stays out of context.

Claude Code docs say path-scoped rules trigger when Claude reads files matching the pattern, not on every tool use. Rules without paths are loaded unconditionally and apply to all files. (Claude)

Exam implication

If Claude is editing:

packages/web/src/components/Button.test.tsx

then this rule should apply:

---
paths:
  - "**/*.test.tsx"
---

But it should not apply while Claude is editing:

packages/web/src/components/Button.tsx

unless you also include a component path pattern.

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/rules/all-rules.md

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:

---
paths:
  - "**/*.ts"
---

for API handler rules.

Better:

---
paths:
  - "src/api/**/*.ts"
  - "**/*.handler.ts"
---

Why?

The broader pattern may load API rules for utility files, tests, scripts, and generated code.

7.3 Avoid conflicting rules

Bad:

testing.md:
  Use Jest.

api-tests.md:
  Use Vitest.

Better:

testing.md:
  Use the test runner configured by the package.

api-tests.md:
  API tests use Vitest.

Claude Code docs warn that conflicting instructions can cause Claude to pick one arbitrarily. (Claude)

7.4 Keep rule text actionable

Weak:

# Test Rules

Write good tests.

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

9. Example repository layout

repo/
  CLAUDE.md
  .claude/
    rules/
      testing.md
      terraform.md
      migrations.md
      api-handlers.md
      frontend/
        react-components.md
  apps/
    web/
      src/
        components/
          Button.tsx
          Button.test.tsx
  services/
    billing/
      src/
        handlers/
          refund.handler.ts
      migrations/
        20260627_add_refund_reason.sql
  infra/
    terraform/
      main.tf

Example rules:

# .claude/rules/testing.md
---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"
  - "**/*.spec.tsx"
---

# Testing Rules

- Add regression coverage for bug fixes.
- Prefer behavior-oriented assertions.
- Follow the nearest package’s existing test framework.

# .claude/rules/api-handlers.md
---
paths:
  - "services/*/src/handlers/**/*.ts"
  - "**/*.handler.ts"
---

# API Handler Rules

- Validate request input at the boundary.
- Return errors using the standard error envelope.
- Avoid raw database calls from handlers.

# .claude/rules/terraform.md
---
paths:
  - "infra/terraform/**/*"
  - "**/*.tf"
  - "**/*.tfvars"
---

# Terraform Rules

- Do not hardcode secrets.
- Run formatting after edits.
- Prefer variables for environment-specific values.

10. Common exam traps

Trap 1: Using directory CLAUDE.md for cross-cutting files

Scenario:

Tests are colocated with source files across apps/, packages/, and services/.

Wrong:

Create apps/web/CLAUDE.md, packages/api/CLAUDE.md, and services/billing/CLAUDE.md with duplicate test rules.

Right:

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

Trap 2: Forgetting YAML frontmatter

Wrong:

paths:
  - "**/*.test.tsx"

# Test Rules
...

Right:

---
paths:
  - "**/*.test.tsx"
---

# Test Rules
...

The paths field belongs in YAML frontmatter.

Trap 3: Making the glob too broad

Wrong:

---
paths:
  - "**/*"
---

for deployment rules.

Right:

---
paths:
  - ".github/workflows/**/*"
  - "deploy/**/*"
  - "**/*.deploy.yml"
---

Trap 4: Expecting path rules to run commands

Wrong expectation:

A Terraform rule says “run terraform fmt,” so formatting is guaranteed.

Correct:

Rules guide behavior. They do not enforce command execution. Use hooks for deterministic enforcement.

Trap 5: Using path rules for procedural workflows

Wrong:

---
paths:
  - "**/*.ts"
---

# Release Workflow

1. Generate release notes.
2. Update changelog.
3. Tag release.
4. Deploy.

Better:

Create a release skill or slash command.

Path rules are for conditional conventions, not occasional workflows.

11. Scenario-based practice questions

Question 1

A monorepo has tests colocated with source files across apps/, packages/, and services/. The team wants Claude to apply the same testing conventions to all *.test.tsx files.

What is the best configuration?

A) Add test conventions to root CLAUDE.md.
B) Duplicate test conventions in every package-level CLAUDE.md.
C) Create .claude/rules/testing.md with paths: ["**/*.test.tsx"].
D) Add a slash command called /test.

Answer

C. The convention applies to a file pattern across multiple directories. A path-specific rule is better than duplicating directory-level files or loading the rule globally.

Question 2

A team creates this rule file:

paths:
  - "terraform/**/*"

# Terraform Rules

- Do not hardcode secrets.

Claude does not load the rule as expected. What is wrong?

A) The file needs YAML frontmatter delimiters.
B) Terraform rules cannot be path-scoped.
C) The rule must be in ~/.claude/CLAUDE.md.
D) Glob patterns are unsupported.

Answer

A. The paths field must be inside YAML frontmatter:

---
paths:
  - "terraform/**/*"
---

Question 3

A rule applies only to files under src/api/**/*.ts.

Which rule frontmatter is best?

A)

---
paths:
  - "src/api/**/*.ts"
---

B)

---
path: "src/api/**/*.ts"
---

C)

---
files:
  - "src/api/**/*.ts"
---

D)

---
include: true
---

Answer

A. The exam expects YAML frontmatter with a paths field containing glob patterns.

Question 4

A backend package has conventions that apply to every file under packages/api/, including build commands, service-layer boundaries, and package-specific test commands.

What is the best place?

A) packages/api/CLAUDE.md
B) .claude/rules/testing.md
C) ~/.claude/CLAUDE.md
D) A path rule for **/*.md

Answer

A. The convention maps cleanly to one directory subtree. Directory-level CLAUDE.md is appropriate.

Question 5

A convention says: “Migration files are append-only.” Migration files appear under multiple services:

services/billing/migrations/
services/accounts/migrations/
services/orders/migrations/

What is the best configuration?

A) Put the rule only in services/billing/CLAUDE.md.
B) Put the rule in every service’s CLAUDE.md.
C) Create .claude/rules/migrations.md with a glob like services/*/migrations/**/*.
D) Put the rule in ~/.claude/CLAUDE.md.

Answer

C. This is a cross-cutting file-pattern convention. A path-specific rule avoids duplication and irrelevant loading.

Question 6

A .claude/rules/security.md file has no paths frontmatter.

What happens?

A) It is never loaded.
B) It is loaded unconditionally like a global project rule.
C) It loads only for .security files.
D) It loads only after a Bash command.

Answer

B. Rules without paths load unconditionally and apply to all files. Use paths when the rule should be conditional.

Question 7

Claude applies React component rules while editing backend service files. The React rules are in root CLAUDE.md.

What is the best fix?

A) Move React-specific rules into a path-scoped rule matching React component paths.
B) Add “do not apply this to backend files” five times.
C) Move all backend code into the frontend directory.
D) Delete all rules.

Answer

A. Frontend rules are not project-wide if they only apply to component files. Path-scoped rules reduce irrelevant context and wrong convention application.

Question 8

A team wants Markdown documentation style rules to apply to all docs, but not to source code.

Which pattern is best?

A)

---
paths:
  - "**/*.md"
  - "docs/**/*"
---

B)

---
paths:
  - "**/*.ts"
---

C) No paths field.
D) Put the rule in packages/api/CLAUDE.md.

Answer

A. The convention applies to Markdown/documentation files. A path-specific rule scoped to Markdown and docs paths is appropriate.

Question 9

A team split a huge root CLAUDE.md into multiple .claude/rules/*.md files, but all rule files lack paths.

What is the likely result?

A) The rules are conditional and load only when needed.
B) The rules load unconditionally, so context savings may be limited.
C) The rules are ignored.
D) The rules become slash commands.

Answer

B. Rules without paths load at launch. To get conditional context loading, add path-scoped frontmatter.

Question 10

A release checklist is used only when cutting a release. The team puts it in a path-scoped rule for package.json.

What is the better mechanism?

A) A skill or slash command for the release workflow.
B) A test-file path rule.
C) User-level preferences.
D) A Terraform rule.

Answer

A. A release checklist is a procedural workflow, not a file-specific convention. Use a skill or slash command.

12. Final D3.3 checklist

Memorize this:

1. Path-specific rules live under .claude/rules/.
2. Rules are markdown files with optional YAML frontmatter.
3. Use paths: [...] to scope a rule to matching files.
4. paths values are glob patterns.
5. Rules without paths load unconditionally.
6. Path-scoped rules load only when Claude works with matching files.
7. Use path rules to reduce irrelevant context and token usage.
8. Use directory-level CLAUDE.md when rules map cleanly to a subtree.
9. Use path-specific rules when conventions span multiple directories.
10. Test files spread across the repo are a classic path-rule use case.
11. Terraform, migrations, docs, generated files, and route handlers are also strong path-rule candidates.
12. Keep rule files topic-specific and descriptive.
13. Avoid overly broad globs.
14. Do not use path rules for occasional workflows; use skills or commands.
15. Rules guide behavior; they do not hard-enforce actions.

D3.3 mental model

CLAUDE.md answers: “What should Claude always know here?”
Directory CLAUDE.md answers: “What applies to this subtree?”
Path-specific rules answer: “What applies only to files matching this pattern?”
Skills/commands answer: “What workflow should Claude run on demand?”

The exam’s favorite distinction is:

If the convention applies to files spread throughout the codebase, use a path-specific rule with glob patterns instead of duplicating directory-level CLAUDE.md files.