Path-Scoped Rules in .claude/rules/: paths Frontmatter and Glob Patterns

1.From one CLAUDE.md to a rules directory

Your project CLAUDE.md loads in every session. That's what you want for build commands and conventions that apply everywhere. It's wasteful for guidance that only matters when Claude touches one kind of file, such as API handler rules, testing conventions or infrastructure-as-code standards. If all of that sits in one file, Claude carries every instruction into every conversation, even when it's editing a README.

The .claude/rules/ directory lets you split instructions into topic files. Each rules/*.md file is committed with the project like CLAUDE.md, and the same mechanism also exists at the global level. The documentation shows a project where the main CLAUDE.md sits next to a rules/ folder holding separate files for code style, testing and security.

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

Splitting files alone doesn't change what lands in context. A rule file with no frontmatter loads every session, just like CLAUDE.md. The difference comes from the optional paths field, covered in the next section. The features overview places rules between CLAUDE.md, which is always on, and skills, which load on demand:

Sources12

2.Scoping a rule with paths frontmatter

To make a rule conditional, start the file with a YAML frontmatter block that contains paths. According to the .claude directory reference, paths is the only frontmatter field a rule file takes. Its value is a set of glob patterns. The rule applies only to files that match one of them. The memory documentation's example limits API rules to TypeScript files under src/api/:

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

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

The field is optional. It accepts glob patterns that scope the rule to matching files, written as a YAML list, as shown above, or as a single comma-separated string. Everything after the closing --- is ordinary markdown, so the body can use the same headers and bullets you'd use in CLAUDE.md. The same pattern works for any area of the codebase. For infrastructure conventions, for example, you could gate a rule on everything under a terraform/ directory with a pattern of the src/**/* form, such as terraform/**/*. Then Terraform guidance enters context only when Claude is working on Terraform files.

Glob-pattern rules also have an advantage over directory-level CLAUDE.md files. A CLAUDE.md lives inside one directory and loads when Claude starts there or reads a file there, so its conventions follow a folder. Many conventions follow a file type instead. Test files, for example, sit beside the code they test in many different directories. Covering them with directory CLAUDE.md files would mean a copy in every one of those directories. A single path-scoped rule in the central .claude/rules/ folder, with a pattern like **/*.test.tsx, loads whenever Claude works with a matching file, wherever it lives. Choose per-directory CLAUDE.md when the directory's owners maintain their own conventions, and a path-scoped rule when the same rule applies to scattered paths.

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

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

Sources34

3.Glob patterns: matching by type or by location

Which pattern you write decides whether a rule follows a file type or a location. A leading **/ matches at any depth, so **/*.ts covers TypeScript files wherever they live. A directory prefix fixes the location: src/**/* covers everything below src/, and src/components/*.tsx covers only the components in that one folder. A bare *.md stays at the project root.

Type-based matching is what makes rules useful for conventions that don't follow your folder layout. Test files are the classic case, because they usually sit next to the code they test, all over the tree. Use the same form as **/*.ts, the any-depth wildcard plus a filename suffix, and write **/*.test.tsx. That one pattern then reaches every React test file in any directory.

One rule can list several patterns, and brace expansion lets one pattern cover more than one extension. The documentation's multi-pattern example combines a brace pattern, a second directory and a test-file suffix:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

Sources3

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Any file placed in .claude/rules/ loads only when relevant files are opened.Why is that wrong?

   Conditional loading needs a paths field. Rules without one load every session, and after compaction they're re-injected along with the project-root CLAUDE.md.

   Covered in From one CLAUDE.md to a rules directory

2. 2.To apply test-file conventions across a codebase, put a CLAUDE.md in every directory that contains tests.Why is that wrong?

   A directory CLAUDE.md follows a folder, so scattered test files would need many copies. One path-scoped rule with a glob such as **/*.test.tsx covers them all from a single central file.

   Covered in Scoping a rule with paths frontmatter

3. 3.A pattern like *.md or src/components/*.tsx matches files at any depth.Why is that wrong?

   Only a ** segment crosses directory levels. *.md matches Markdown files in the project root only, and **/*.ts is the form that matches a type anywhere.

   Covered in Glob patterns: matching by type or by location