The Claude Code Rules Directory: Split a Bloated CLAUDE.md Into Path-Scoped Files

The Claude Code rules directory is a .claude/rules folder inside your project holding one Markdown file per topic. All .md files are discovered recursively, so you can nest them into subdirectories like frontend and backend and they still get picked up. A rule file with no frontmatter loads at launch with the same priority as .claude/CLAUDE.md, which means moving a section out of CLAUDE.md and into a rule file changes nothing about how it is applied.

That alone is worth doing for maintainability. A repo where testing conventions live in testing.md and security requirements live in security.md is one where a teammate can find and edit the right rule without reading 400 lines to locate it. But the reason to move is the next part: once instructions are in separate files, you can scope them.

Add a YAML frontmatter block with a paths field and the rule stops loading unconditionally. Instead it enters context only when Claude works with files matching your glob patterns. A rule scoped to src/api/**/*.ts costs nothing on a session spent in the frontend, and shows up automatically the moment Claude opens an API handler.

The trigger is specifically Claude reading a matching file, not every tool use, so the rule arrives at the point where it is relevant rather than sitting in context all session. Matching also works when Claude reaches a file through a symlinked path into the project directory, which used to be a gap on symlinked checkouts and was fixed in v2.1.198.

Rules with no paths field are loaded unconditionally and apply to everything, so the field is opt-in. Start by moving your longest, most situational section into a scoped rule and leave the genuinely universal rules unscoped.

Glob syntax treats an opening square bracket as the start of a bracket expression like [abc]. A pattern containing a square bracket that cannot be read that way, such as a directory literally named photos [2024, is invalid: it matches nothing at all, while the rule's other patterns carry on working. Escape it as photos \[2024/** to match the real folder name. Before v2.1.207, a single invalid pattern was worse than useless, because it made the Read tool fail for every file the rule was evaluated against.

The second trap is brace expansion getting away from you. Each brace group multiplies the pattern count, so src/*.{ts,tsx} becomes two patterns and {a,b}/{c,d}/*.{ts,tsx} becomes eight. A rule's whole paths list shares one budget of 1,000 expanded patterns and 4 MiB. Exceed it and the pattern is used unexpanded, at which point its literal braces match no files and the rule quietly stops firing. Patterns with no braces do not count against the budget.

Personal rules go in ~/.claude/rules/ and apply to every project on your machine. They load before project rules, which gives project rules the higher priority when the two disagree - the right way round, since a repo's conventions should beat your habits.

The dividing line between a rule and a skill is whether the instruction needs to be present or merely available. A convention Claude should honor whenever it touches a file is a rule. A procedure Claude should follow when you ask for that specific job is a skill. Putting a long procedure in a rule is the most common way people end up back where they started, with a bloated context and no idea which instruction is being ignored.

Project-root CLAUDE.md survives compaction. After /compact, Claude Code re-reads it from disk and re-injects it into the session, so your core instructions come back automatically. Nested CLAUDE.md files in subdirectories and rules with paths frontmatter are not re-injected: they reload the next time Claude reads a file in that subdirectory or a file matching the rule's patterns.

In practice that is fine, because the reload trigger is the same event that made the rule relevant in the first place. It is only confusing if you compact mid-task and expect a scoped rule to still be in play before Claude has touched a matching file again. If an instruction absolutely must survive every compaction, it belongs in the project-root CLAUDE.md, not in a scoped rule.

Here is the pass we run on any repo whose CLAUDE.md has crept past 200 lines. Read the file and mark every section with one of three labels: universal, situational, or procedural. Universal stays in CLAUDE.md. Situational moves to a .claude/rules file with a paths glob covering exactly the area it describes. Procedural becomes a skill. Then start a fresh session, run /context, and compare the memory footprint against where you started.

The reason this is worth an hour is that context is not free and adherence is not linear. A shorter file is followed more reliably than a long one, so trimming CLAUDE.md is not only a token optimization, it measurably changes how often your conventions actually get respected. Most repos we run this on come out with a CLAUDE.md under half its old length and three or four scoped rules that never load unless they matter.