Path-Scoped Rules with .claude/rules/

The Problem with One Big File

As a project grows, CLAUDE.md tends to accumulate instructions that are only relevant some of the time. API design conventions matter when Claude is working on API endpoints. Frontend component rules matter when Claude is editing React files. Database migration conventions matter only when Claude is writing migrations. Keeping all of these in a single always-loaded CLAUDE.md means you are paying context cost for API rules when Claude is working on UI code, and paying for UI rules when Claude is working on migrations.

Path-scoped rules solve this by loading instructions only when they are relevant — specifically, only when Claude reads files that match specified path patterns. The result is a CLAUDE.md that stays lean while still providing the right guidance for every part of the codebase.

The Three-Tier Context Loading Hierarchy

Before diving into rules files, it helps to see how they fit into the larger architecture. There are three tiers of persistent instructions in Claude Code, each with different loading behavior:

Choosing the right tier is about how often the instruction is needed. If it applies every session, use CLAUDE.md. If it applies only when working with specific file types or directories, use path-scoped rules. If it applies only for specific tasks you explicitly request, use a skill.

Setting Up .claude/rules/

Place markdown files in your project's .claude/rules/ directory. Each file should cover one topic, with a descriptive filename like testing.md, api-design.md, or security.md. All .md files in the directory are discovered recursively, so you can organize rules into subdirectories like frontend/ or backend/.

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

Rules files without a paths frontmatter field load unconditionally at session start, the same as .claude/CLAUDE.md. This is useful for instructions that apply to all files but are better kept in a separate file for organizational clarity.

Path-Scoped Rules with YAML Frontmatter

To make a rule file conditional, add YAML frontmatter with a paths field:

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

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format defined in src/api/errors.ts
- Include OpenAPI documentation comments above each handler

This rule file only enters context when Claude reads a TypeScript file under src/api/. While Claude is working on frontend code or database migrations, these API rules are invisible — they are not consuming context tokens at all.

An important detail: the trigger is a file read, not a tool use. The rule loads when Claude reads a matching file, not when it runs a Bash command or uses another tool. If Claude runs a script that modifies API files without reading them first, the rule may not be in context. For most workflows this is fine — reading a file before modifying it is the normal pattern.

Glob Pattern Reference

The paths field accepts glob patterns that match against full file paths:

• **/*.ts — all TypeScript files in any directory
• src/**/* — all files under the src/ directory
• *.md — markdown files in the project root only
• src/components/*.tsx — React components in a specific directory

You can specify multiple patterns and use brace expansion to match multiple extensions:

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

User-Level Rules and Sharing

Personal rules that apply across all your projects belong in ~/.claude/rules/. These load before project rules in every session, giving project rules higher priority. Use them for personal workflow preferences that are not project-specific — your preferred debugging approach, your personal code review checklist, your tool usage habits.

The .claude/rules/ directory supports symlinks, making it straightforward to share a common set of rules across multiple projects. A symlink to a shared directory or individual file is resolved and loaded normally:

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

Monorepo Exceptions with claudeMdExcludes

In large monorepos, Claude Code walks up the directory tree and can pick up CLAUDE.md files from other teams' projects — files that contain conventions relevant to their code but irrelevant or conflicting for yours. The claudeMdExcludes setting lets you skip specific files by path or glob.

Add it to .claude/settings.local.json so the exclusion stays on your machine rather than being committed to the repository:

{
"claudeMdExcludes": [
"**/other-team/CLAUDE.md",
"/home/user/monorepo/other-team/.claude/rules/**"
]
}

Patterns match against absolute file paths. The setting can also be placed in user, project, or managed settings — arrays merge across layers, so a team-level exclusion and a personal exclusion can coexist without one overwriting the other. Managed policy CLAUDE.md files cannot be excluded, ensuring organization-wide instructions always apply regardless of individual settings.