What You Need to Know
Root CLAUDE.md loads for every session. A directory-level CLAUDE.md applies to files in that one directory. A path-specific rule loads its conventions only when you edit files that match its glob patterns (patterns that describe a set of file paths). A path-specific rule covers a case that neither CLAUDE.md handles well: one file type that is spread across many directories.
This lesson uses one made-up example throughout: a catering firm whose ordering system has team-wide standards and Terraform hosting files. Its test files sit beside source files in many folders.
How Path-Specific Rules Work
Rule files are in .claude/rules/. Each rule file starts with YAML frontmatter (a block of settings written in YAML) whose paths field lists glob patterns. The rules load only when you edit a matching file.
---
paths: ["terraform/**/*"]
---
# Terraform Conventions
- Use snake_case for all resource names
- Tag every resource with environment and team labels
- Never hardcode AMI IDs — use data sources
- All modules must have a variables.tf, outputs.tf, and README.mdEdit a file that matches terraform/**/* and these rules load automatically. Edit a React component or an API handler and they do not load. The catering firm's hosting conventions stay out of context while someone edits the menu pages.
Glob Patterns Match Across the Entire Codebase
In a glob, ** matches across directory levels. So **/*.test.tsx matches every test file in the codebase, wherever it is. Take a typical project structure:
src/
components/
Button.tsx
Button.test.tsx
api/
auth.ts
auth.test.ts
utils/
format.ts
format.test.ts
pages/
dashboard/
Dashboard.tsx
Dashboard.test.tsx
Test files are next to their source files in four directories. A rule with paths: ["**/*.test.tsx", "**/*.test.ts"] applies the same test conventions to every one of those test files, automatically.
Why Not Directory-Level CLAUDE.md?
A directory-level CLAUDE.md covers only its own directory. Test files across 50+ directories would need a CLAUDE.md in each. That means:
- 50+ copies of the same conventions
- Every new directory with tests needs a new copy
- Any convention change requires updating all 50+ files
- Inevitable differences between copies, as some copies become out of date
One rule file and one pattern avoid all four problems. The catering firm changes a test convention by editing one file.
Why Not Root CLAUDE.md?
Root CLAUDE.md loads in every session, whichever files you edit. Terraform conventions in root CLAUDE.md use tokens while you edit React components. Test conventions in root CLAUDE.md load while you write API handlers. The catering firm's hosting conventions would fill context during a menu fix.
Key Concept
Path-scoped rules are more token-efficient than root CLAUDE.md because they load only when you edit matching files. Less irrelevant context keeps the model focused on conventions that apply to the current work. In large projects with many convention categories, the saving is substantial.
Practical Rule File Examples
Test conventions across the entire codebase
---
paths: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"]
---
# Test Conventions
- Use describe/it blocks with descriptive names that read as sentences
- Each test file must have at least one happy path and one error case
- Use factory functions for test data, not inline object literals
- Mock external services at the module boundary, not individual functions
- Assert behaviour, not implementation detailsAPI conventions for any route handler
---
paths: ["src/api/**/*", "**/routes/**/*", "**/*.controller.ts"]
---
# API Conventions
- All endpoints return { data, error, metadata } response shape
- Use Zod schemas for request validation at the handler boundary
- Log request ID on every error response
- Rate limiting configuration must be explicit, not inherited from defaultsInfrastructure-as-code conventions
---
paths: ["terraform/**/*", "**/*.tf", "infrastructure/**/*"]
---
# Infrastructure Conventions
- State files must reference remote backends, never local
- Use workspaces for environment separation
- Every module must be versioned with a CHANGELOGWhen to Use Each Approach
| Scenario | Best approach |
|---|---|
| Universal team standards that apply to all code | Root CLAUDE.md |
| Conventions for one specific package directory | Directory-level CLAUDE.md |
| Conventions for a file type spread across many directories | Path-specific rules with glob patterns |
| Task-specific workflows invoked on demand | Skills in .claude/skills/ |
The catering firm puts team-wide standards in root CLAUDE.md, and its test and Terraform conventions in path-specific rules.
In the exam
The exam frequently presents test files that are next to their source files in many directories. The answer is always path-specific rules with glob patterns. Wrong options use root CLAUDE.md or a CLAUDE.md in every directory.
Path-specific rules are one of Domain 3's six task statements. As of 2026, Anthropic has no standalone Claude Code certification, and no other exam tests Claude Code as heavily as this one.
Exam Traps
Choosing directory-level CLAUDE.md over path-specific rules for cross-directory conventions
When conventions must apply to files spread across 50+ directories (like co-located test files), path-specific rules with glob patterns are correct. Directory-level CLAUDE.md would require placing a file in every directory, a massive maintenance burden.
Placing file-type-specific conventions in root CLAUDE.md
Root CLAUDE.md loads for every session regardless of which files you edit. Terraform conventions consume tokens when editing React components. Path-specific rules load only when editing matching files, preserving token budget.
Confusing skills with path-specific rules for automatic convention application
Both skills and .claude/rules/ can auto-activate via a paths field. But rules stay in context as guidance once Claude reads a matching file. So they shape every edit. Skills load on demand as task-style workflows. For automatic convention loading by file type, choose path-specific rules.
Practice Scenario
A codebase has test files co-located with source files throughout 50+ directories (e.g., Button.test.tsx next to Button.tsx). The team wants the same conventions for every test, regardless of location. It wants them loaded only when a test file is being worked on and with nothing for a developer to invoke. What is the most maintainable approach?
Build Exercise
Configure Path-Specific Rules with Glob Patterns
What you'll learn
- Write YAML frontmatter with glob patterns for conditional rule loading
- Apply path-specific rules to files spread across many directories
- Understand why path-specific rules are more token-efficient than root CLAUDE.md
- Distinguish when to use path-specific rules vs directory-level CLAUDE.md
- Verify conditional loading behaviour using the /context command
- Create .claude/rules/testing.md with YAML frontmatter paths: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"] and test conventions (naming, assertions, mocking patterns)
Why: Path-specific rules with glob patterns are the correct solution for conventions that apply to a file type spread across many directories. The exam favourite scenario is test files co-located with source files across 50+ directories.
You should see: A file at .claude/rules/testing.md with YAML frontmatter containing a paths array with glob patterns. The body contains at least three test conventions covering naming, assertions, and mocking.
- Create .claude/rules/api-conventions.md with paths: ["src/api/**/*", "**/routes/**/*"] and API conventions (response shape, validation, error handling)
Why: Separating API conventions into their own path-scoped rule means they only load when editing API files. This avoids consuming tokens with irrelevant context when working on frontend or infrastructure code.
You should see: A file at .claude/rules/api-conventions.md with YAML frontmatter paths targeting API directories. The body contains at least three API conventions.
- Create .claude/rules/terraform.md with paths: ["terraform/**/*", "**/*.tf"] and infrastructure conventions
Why: Infrastructure conventions are completely irrelevant when editing application code. Path-scoped rules ensure Terraform rules never consume tokens during React or API development sessions.
You should see: A file at .claude/rules/terraform.md with YAML frontmatter paths matching Terraform files. The body contains infrastructure-specific conventions.
- Run /context, then edit a test file and check the terminal to verify that testing rules load but API and Terraform rules do not
Why: This proves the conditional loading mechanism works. The exam tests whether you understand that path-specific rules load only for matching files. /context lists the CLAUDE.md and rules files loaded at launch. A path-scoped rule loads when Claude reads a matching file. Claude Code prints a one-line Loaded notice for it.
You should see: At launch, /context lists none of the three path-scoped rule files under Memory files. When Claude edits a .test.ts file, the terminal shows a Loaded line for .claude/rules/testing.md. No Loaded line appears for .claude/rules/api-conventions.md or .claude/rules/terraform.md.
- In a fresh session, edit an API handler and verify that API rules load while testing and Terraform rules do not
Why: This is the complementary verification. Switching contexts should swap which rules are loaded, confirming that the glob patterns correctly scope each rule file.
You should see: When Claude edits a file in src/api/, the terminal shows a Loaded line for .claude/rules/api-conventions.md. No Loaded line appears for the testing or Terraform rule files.
- Compare the number of tokens loaded when all conventions are in root CLAUDE.md versus split into path-specific rules
Why: Token efficiency is a key exam concept. Root CLAUDE.md loads all conventions for every session regardless of relevance. Path-specific rules load only matching conventions, reducing irrelevant context and preserving token budget for actual work.
You should see: With all conventions in root CLAUDE.md, /context lists the root file at launch, and it carries the full set of conventions even when editing a simple utility file. With path-specific rules, /context lists no scoped rule at launch, and only the matching rule loads later, with its Loaded notice. The token count for loaded configuration is measurably smaller when using path-specific rules for targeted editing sessions.