Scope Claude Code rules to specific files with .claude/rules/ and paths frontmatter

Once a CLAUDE.md holds testing conventions, API design rules, and front-end styling guidance, it passes 200 lines quickly. The official docs say longer files reduce adherence, and loading rules for code you are not touching wastes context every session.

In short: move topics into Markdown files under .claude/rules/, and add paths frontmatter to the ones that only matter for certain files. Those rules then load only when Claude works with a matching file.

The basics of .claude/rules/

Put .md files in your project's .claude/rules/ directory, one topic per file, with descriptive names like testing.md or api-design.md. Files are discovered recursively, so subdirectories such as frontend/ and backend/ work too.

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── security.md

A rule without paths loads at session start with the same priority as .claude/CLAUDE.md. That only splits the file for organization; it does not save context. For savings, use paths.

Restricting a rule with paths

Start the rule file with YAML frontmatter listing glob patterns under paths.

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

# API Development Rules

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

Pattern syntax:

Pattern	Matches
**/*.ts	TypeScript files in any directory
src/**/*	everything under src/
*.md	Markdown files in the project root
src/components/*.tsx	React components in one directory

You can list several patterns and use brace expansion to cover multiple extensions.

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

A path-scoped rule loads when Claude reads a matching file, not on every tool use. As of v2.1.198 it also matches files reached through a symlinked path to the project directory.

User-level rules and sharing

Rules in ~/.claude/rules/ apply to every project on your machine. They load before project rules, so when the two conflict the project rule wins.

To reuse rules across projects, drop symlinks into .claude/rules/. Circular links are detected and handled.

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

Excluding project with --setting-sources skips project rules. Before v2.1.211, path-scoped and nested rules loaded even when project was excluded.

For procedures you only need occasionally, a skill is a better fit than a rule, because it loads only when invoked. What belongs in CLAUDE.md itself is covered in the hub article How to write CLAUDE.md, and splitting by directory in When does Claude Code load a CLAUDE.md in a subdirectory?.

Summary

• Put one topic per file under .claude/rules/. Rules without paths load at startup and save nothing
• A path-scoped rule loads only when Claude reads a file matching its globs
• Brace expansion is capped at 1,000 patterns and 4 MiB per rule; escape literal [
• ~/.claude/rules/ loads first, so project rules take priority
• Share rules with symlinks; move occasional procedures into skills