Path-specific rules for conditional loading

What you’ll be able to do

• Create a .claude/rules/ file with YAML frontmatter paths so it loads only for matching files
• Write glob patterns that target files by type regardless of directory (e.g. **/*.test.tsx)
• Explain how path-scoped loading reduces irrelevant context and token usage
• Choose path-specific rules over subdirectory CLAUDE.md files for conventions spread across the codebase

What you need to know

A rule file that loads only when it’s relevant

Lesson 3.1 introduced .claude/rules/ as a way to split CLAUDE.md into topic files. Path-specific rules add a condition. Give a rule file YAML frontmatter with a paths field containing glob patterns, and the rule loads only when Claude is editing a file that matches.

A session spent editing React components never loads these Terraform conventions. A session that opens terraform/modules/network/main.tf does. The conventions stay in the repository, versioned and shared like any other project configuration, but they're in context only when they apply.

Why conditional loading matters

Everything loaded into a session takes context space and tokens, and it competes for Claude's attention. A root CLAUDE.md that holds Terraform rules, API rules, testing rules, and migration rules loads all of them into every session, whatever the session is doing. That has two costs:

• Wasted context and tokens. Hundreds of lines of irrelevant convention load in every session.
• Weaker application. If every area's rules sit in one file under headings, Claude has to infer which section applies to the current file. Inference is less reliable than an explicit match.

Path-scoped rules replace that inference with a deterministic match on the file path. The right conventions load for the file being edited, and nothing else does.

Globs target file types, not just folders

The glob can describe a directory subtree, a file type anywhere in the tree, or both. That is what makes path-specific rules useful for conventions that cut across the directory structure.

• paths: ["terraform/**/*"] — everything under one top-level directory.
• paths: ["**/*.test.tsx"] — every React test file, wherever it sits.
• paths: ["src/api/**/*"] — the API layer only.
• paths: ["**/migrations/*.sql"] — migration files in any service's migrations directory.

Watch the anchoring. migrations/*.sql matches only a migrations folder at the top of the repository. If each service keeps its own migrations folder, you need the leading **/ to match all of them.

Path rules vs directory-level CLAUDE.md

A directory-level CLAUDE.md is tied to one directory. It suits facts that really are local to one subtree, such as a package's own build step or the module that owns a particular integration.

It's the wrong tool when the files a convention governs are spread across the codebase. Test files that sit next to the code they test are the standard example. With directory-level files, every directory that contains a test would need its own CLAUDE.md carrying the same testing conventions, perhaps forty copies that drift as soon as one is edited. One rule file with paths: ["**/*.test.tsx"] covers every test file in the tree, now and in the future, from one place.

Picking the mechanism

• Applies everywhere, all the time → project-level CLAUDE.md, or a rule file without path scoping.
• Applies only to one subtree → a path rule such as terraform/**/*, or a directory-level CLAUDE.md if it's a local fact about that package.
• Applies to a kind of file wherever it lives → a path rule with a type-based glob such as **/*.test.tsx.
• A workflow someone runs on demand → a skill (3.2), not a rule.

Key concept

Give a .claude/rules/ file a paths: glob and it loads only when Claude edits matching files. That cuts irrelevant context, and a type-based glob such as **/*.test.tsx reaches files anywhere in the tree, which directory-level CLAUDE.md files can’t do without copies.

When a scenario's convention follows a file type rather than a folder, the answer is almost always a path-scoped rule.

Practice scenario

Build exercise — Convert area sections into path-scoped rules

Intermediate · 25 min

What you’ll learn

• Writing paths frontmatter with directory-based and type-based globs
• Checking that a rule loads for matching files and stays out otherwise
• Spotting conventions that belong to a file type rather than a directory

1. Pick two area-specific sections of a CLAUDE.md: one tied to a directory (for example infrastructure) and one tied to a file type (for example tests). Move each into its own .claude/rules/ file with a paths glob.

   • Why: The two cases need different glob shapes, and writing both shows the difference.
   • You should see: Something like paths: ["infra/**/*"] for one and paths: ["**/*.test.*"] for the other.

2. Start a session and edit a file that matches neither glob, then one that matches each.

   • Why: You’re confirming that loading is conditional, which is where the context and token savings come from.
   • You should see: The test conventions applied only when editing a test file, and the infrastructure conventions only under the infrastructure directory.

3. Search the repository for directory-level CLAUDE.md files that repeat the same convention, and replace the copies with one path-scoped rule.

   • Why: Duplicated directory files are the usual sign that a convention follows file type, not location.
   • You should see: Several near-identical files collapse into one rule whose glob reaches every place the copies covered.

Exam traps

Copying a cross-cutting convention into a CLAUDE.md in every directory that contains matching files

Directory-level files are tied to one directory. For files spread across the tree, one rule with a glob like **/*.test.tsx replaces all the copies.

Leaving area-specific conventions in the root CLAUDE.md, where they load in every session

Root CLAUDE.md content loads every time, whether it’s relevant or not. Path-scoped rules load only when matching files are edited, which saves context and tokens.

Writing a glob anchored to one directory when the files are spread throughout the tree

migrations/*.sql matches only a root-level folder. Use a leading **/ to match the pattern at any depth.

Relying on Claude to infer which section of a large CLAUDE.md applies to the current file

Headings only invite inference. A paths glob gives an explicit, deterministic match.

Packaging file-type conventions as skills, which apply only when someone invokes them

Skills load on demand. Conventions that must apply automatically whenever a matching file is edited belong in path-scoped rules.

Sources

• Claude Code Docs
• Anthropic, Claude Certified Architect – Foundations Exam Guide v1.0 (July 2026)