A long CLAUDE.md costs context on every request. The .claude/rules/ directory lets you split instructions into topic files and, with a paths field in frontmatter, load a rule only when Claude works on matching files. Rules without paths load at launch like the main file.
Setting up the directory
Put markdown files in .claude/rules/ in your project. Each file should cover one topic, such as testing.md or api-design.md. Anthropic's memory documentation says all .md files are discovered recursively, so you can group them in folders like frontend/ and backend/.
Rules without paths frontmatter are loaded at launch with the same priority as .claude/CLAUDE.md. That is a tidy way to organize, but it does not save any context by itself.
Scoping a rule to files
The saving comes from the paths field. A rule file starts with YAML frontmatter between three-dash markers:
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
A path-scoped rule loads when Claude uses the Read, Write or Edit tool on a matching file. The docs say it also loads when Claude views a matching file with a single-file Bash read such as cat or head.
Glob patterns work as you would expect: a double-star pattern for all files of a type, a directory prefix for everything under it, and brace expansion for several extensions in one pattern. The documentation adds a guard rail: a rule's whole paths list shares one budget of 1,000 expanded patterns, so avoid piling up brace groups.
What paths is and is not
paths is the only field Claude Code reads from a rule's frontmatter. Other fields are ignored without an error. If the YAML does not parse, Claude Code ignores the frontmatter and loads the rule as though it had no paths, which means a typo can quietly turn a scoped rule into an always-on one. The docs suggest running Claude Code with its debug option to see the parse error.
Sharing rules between projects
The directory supports symlinks, so you can keep a shared rule set in one place and link it into several repositories. A symlink whose target is outside your working directory counts as an external import. Those rules do not load until the project approves external imports, and after that only the ones without paths load. For shared rules without the approval step, keep them in ~/.claude/rules/, where they apply to every project on your machine.
Rules, skills or CLAUDE.md
- Facts needed in every session: CLAUDE.md.
- Instructions that matter only for some files: a path-scoped rule.
- Multi-step procedures needed on request: a skill, which loads only when invoked.
Quick check
Does splitting CLAUDE.md into rules files reduce context use?
Only if the rules are path-scoped. Rules without paths load at launch like the main file.
What happens if my rule frontmatter has a YAML error?
Claude Code ignores the frontmatter and loads the rule as if it had no paths, so it applies everywhere.
Sources
Last reviewed: 19 October 2026.
