.claude/rules/: Scoped by Frontmatter, Not by Folder

A Second, Narrower Layer of Rules

CLAUDE.md is the always-on baseline -- it loads into every session, unconditionally. Rules instruction files are a distinct mechanism that adds a narrower layer on top of that baseline: they let a piece of guidance apply only where it's relevant, instead of loading into every session and diluting the file that's supposed to hold universal context.

Rules files live in a project's .claude/rules/ directory, one Markdown file per rule (or per related group of rules), each with a YAML frontmatter block at the top.

Scope Comes From Frontmatter, Not From Where the File Sits

This is the one fact worth knowing cold: a rules file's scope is controlled entirely by a paths glob declared in its YAML frontmatter -- not by which subdirectory of .claude/rules/ the file happens to live in. Placing a file at .claude/rules/database/transactions.md versus .claude/rules/transactions.md has zero effect on when it loads; only the paths field does that.

---
paths:
  - "src/db/**/*.sql"
---
All SQL in this module must include an explicit transaction boundary.

A rule scoped this way enters context only when Claude Code is actually working with a file matching that glob -- e.g., something under src/db/ ending in .sql. The rest of the codebase never pays the context cost of a rule that doesn't apply to it.

**Critically: a rules file with no paths frontmatter at all loads unconditionally, at session start, with the same standing as CLAUDE.md.** Omitting paths doesn't mean "loads nowhere" -- it means "loads everywhere, always," exactly like the project's CLAUDE.md. Subdirectory organization under .claude/rules/ is purely cosmetic bookkeeping for humans browsing the folder; it carries no scoping meaning to Claude Code itself.

Where Each Piece of Guidance Belongs

Broad, universal constraints belong in CLAUDE.md. Narrow, path-specific guidance belongs in a rules file scoped with paths -- that's what keeps CLAUDE.md from growing into an undifferentiated pile that dilutes the instructions that actually matter on any given task.

Common exam traps

• Assuming a rules file's location inside .claude/rules/ determines its scope. It doesn't -- only the paths frontmatter field does. A file sitting in a database/ subfolder with no paths key still loads unconditionally, for every task, everywhere.
• Assuming a rules file with no paths field simply doesn't load. The opposite is true: without paths, it loads exactly like CLAUDE.md -- unconditionally, at session start.