3.3 Path-Specific Rules for Conditional Convention Loading

What You Need to Know

Path-specific rules apply conventions conditionally, based on which files you’re editing. They solve something neither root CLAUDE.md nor directory-level CLAUDE.md handles well: conventions that must apply to one file type scattered across many directories.

How Path-Specific Rules Work

Rule files live in the .claude/rules/ directory. Each file carries YAML frontmatter with a paths field specifying glob patterns. The rules inside load only when you’re editing files that match those patterns.

---
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.md

Edit a file matching terraform/**/* and these rules load automatically. Edit a React component or an API handler and they don’t. The rules stay invisible until they’re relevant.

Glob Patterns Match Across the Entire Codebase

This is where they earn their keep. A glob like **/*.test.tsx catches every test file in the codebase, wherever it sits. 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 sit next to their source files across four directories. A path-specific rule with paths: ["**/*.test.tsx", "**/*.test.ts"] applies the same test conventions to every one of them, automatically.

Why Not Directory-Level CLAUDE.md?

A directory-level CLAUDE.md applies to files in that one directory. To cover test files spread across 50+ directories, you’d have to drop a CLAUDE.md into every single directory that holds tests. 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 drift as some copies fall behind

Path-specific rules with glob patterns eliminate this entirely. One file, one pattern, universal coverage.

Why Not Root CLAUDE.md?

Root CLAUDE.md loads for every session, regardless of which files you edit. Put your Terraform conventions in the root CLAUDE.md and they burn tokens even while you’re editing React components. Put your test conventions there and they load while you’re writing API handlers.

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 details

API 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 defaults

Infrastructure-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 CHANGELOG

When 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 exam frequently presents the scenario of test files co-located with source files across many directories. The answer is always path-specific rules with glob patterns.

Exam Traps

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 all tests to follow the same conventions regardless of location. What is the most maintainable approach?

A. Create a rule file in .claude/rules/ with YAML frontmatter paths: [“/*.test.tsx”, “/*.test.ts”] holding the test conventions for the repo
B. Place a CLAUDE.md file in every directory that contains test files, each carrying a copy of the team test conventions
C. Add all the test conventions to the root CLAUDE.md file so they are loaded into context for every session
D. Create a skill in .claude/skills/ that includes the test conventions and instruct developers to invoke it before writing or editing any tests

Answer & explanation

Correct: A

A — Glob patterns in .claude/rules/ match files by pattern across the entire codebase. The conventions load automatically when editing any test file, regardless of directory. One file covers all 50+ directories with zero maintenance as new test files are added.
B — With 50+ directories, this creates massive duplication. Every convention change requires updating 50+ files. New directories need new copies. Drift is inevitable.
C — Root CLAUDE.md loads for every session. Test conventions would consume tokens even when editing non-test files. Path-specific rules are more token-efficient.
D — This approach relies on developers remembering to invoke the skill for every test edit — human discipline is the weak link. Skills can also auto-activate via a paths frontmatter, but even then they load on-demand as a task-style workflow rather than as always-in-context guidance. Test conventions should shape every edit to a matching file, which is exactly what .claude/rules/ with path scoping provides — automatic context-level loading with no human step.

Sources

Claude Code Memory and Rules Documentation — Anthropic
Claude Certified Architect Foundations Exam Guide — Task Statement 3.3 — Anthropic
Claude Certified Architect Foundations Exam Guide — Sample Question 6 — Anthropic

Exam Simulator

Five exam-style multiple-choice questions on Path-Specific Rules for Conditional Convention Loading. Pick an answer, then open the explanation.

Question 1

A. Create a skill in .claude/skills/ that includes the test conventions and instruct developers to invoke it before writing tests
B. Place a CLAUDE.md file in every directory containing test files
C. Add all test conventions to the root CLAUDE.md file
D. A rule file in .claude/rules/ with frontmatter paths: [“/*.test.tsx”, “/*.test.ts”]

Answer & explanation

Correct: D

A is wrong: This approach relies on developers remembering to invoke the skill for every test edit — human discipline is the weak link. Skills can auto-activate via a paths frontmatter, but even then they load on-demand as a task-style workflow rather than as always-in-context guidance. Path-specific rules in .claude/rules/ load into context automatically when Claude reads a matching file, with no human step.
B is wrong: With 50+ directories, this creates massive duplication. Every convention change requires updating 50+ files. New directories need new copies. Drift is inevitable.
C is wrong: Root CLAUDE.md loads for every session. Test conventions would consume tokens even when editing non-test files like API handlers or database models.
D is correct: Glob patterns in .claude/rules/ match files by pattern across the entire codebase. The conventions load automatically when editing any test file, regardless of directory. One file covers all 50+ directories with zero maintenance as new test files are added.

Question 2

A project has Terraform infrastructure files in terraform/ and application code in src/. The Terraform conventions include specific resource naming rules that are irrelevant to application code. Where should these conventions be configured for maximum token efficiency?

A. In root CLAUDE.md so they are always available
B. In .claude/rules/terraform.md with paths: [“terraform//*”, “/*.tf”] in the YAML frontmatter
C. In a directory-level CLAUDE.md placed inside terraform/ alongside the module definitions themselves
D. In a skill at .claude/skills/terraform/SKILL.md that developers invoke before editing any module

Answer & explanation

Correct: B

A is wrong: Root CLAUDE.md loads for every session. Terraform naming rules would consume tokens when editing React components or API handlers – completely wasted context.
B is correct: Path-specific rules with glob patterns cover both the terraform/ directory tree and any .tf files anywhere in the codebase. They load only when editing matching files, providing maximum token efficiency.
C is wrong: A directory-level CLAUDE.md only covers the terraform/ directory. If .tf files exist elsewhere in the codebase (infrastructure-as-code modules in other locations), they would not be covered.
D is wrong: Skills load on-demand as task-style workflows rather than as always-in-context guidance. Infrastructure conventions should shape every edit to an infrastructure file, which is exactly what .claude/rules/ with path scoping provides.

Question 3

A developer is editing a file at src/api/auth.ts. The project has three rule files: .claude/rules/testing.md (paths: [“/*.test.ts”]), .claude/rules/api-conventions.md (paths: [“src/api//”]), and .claude/rules/terraform.md (paths: [“terraform/**/”]). Which rules are loaded?

A. Only api-conventions.md, because the file matches src/api/**/*
B. All three, because they are all in the .claude/rules/ directory
C. api-conventions.md and testing.md, because the file is in src/
D. None, because path-specific rules require explicit invocation

Answer & explanation

Correct: A

A is correct: src/api/auth.ts matches the pattern src/api/**/* in api-conventions.md. It does not match /*.test.ts (not a test file) or terraform//* (not in the terraform directory).
B is wrong: Path-specific rules only load when the file being edited matches the glob patterns in the frontmatter. Being in .claude/rules/ does not mean automatic loading for all files.
C is wrong: testing.md requires files matching **/*.test.ts. auth.ts is not a test file, so testing rules do not load.
D is wrong: Path-specific rules load into context automatically when Claude reads a matching file. They do not require explicit invocation. Skills, by contrast, load on-demand as task-style workflows.

Question 4

A team moves all their conventions from root CLAUDE.md into path-specific rules in .claude/rules/. When a developer edits a utility function in src/utils/format.ts, they notice that the general coding standards (naming, error handling) no longer apply. What went wrong?

A. Path-specific rules cannot contain general coding standards
B. The developer needs to run /memory to reload the configuration
C. The glob misses utility files, or they belong in the root
D. .claude/rules/ files only work for test and infrastructure files

Answer & explanation

Correct: C

A is wrong: Path-specific rules can contain any type of convention. The issue is how the glob patterns are defined.
B is wrong: /memory is a diagnostic tool that shows loaded files. It does not reload or trigger loading.
C is correct: If general coding standards apply to ALL files, they either need a glob pattern like [“**/*”] or they should remain in root CLAUDE.md. Moving universal standards to path-scoped rules without a catch-all pattern breaks their universal application.
D is wrong: .claude/rules/ files work for any file type. The glob pattern determines which files trigger loading, not the content of the rules.

Question 5

Which of the following is the primary advantage of path-specific rules over root CLAUDE.md for file-type-specific conventions?

A. Path-specific rules are version-controlled while root CLAUDE.md is not
B. They load only when editing matching files, saving context tokens
C. Path-specific rules support YAML frontmatter while root CLAUDE.md does not
D. Path-specific rules can be shared via git while root CLAUDE.md cannot

Answer & explanation

Correct: B

A is wrong: Both path-specific rules and root CLAUDE.md are version-controlled when placed in the repository.
B is correct: Token efficiency is the primary advantage. Path-specific rules load only for matching files, so Terraform conventions do not consume tokens when editing React components. Root CLAUDE.md loads everything for every session.
C is wrong: While path-specific rules use YAML frontmatter for path scoping, this is a mechanism, not the primary advantage. The advantage is the conditional loading that the frontmatter enables.
D is wrong: Both root CLAUDE.md and .claude/rules/ files are inside the repository and shared via git.