Twelve Unscoped Rules Files Waste 78% of Your Context Budget

The .claude/rules/ directory lets you split a monolithic CLAUDE.md into topic-specific files. But splitting alone solves only half the problem — maintainability. Without paths frontmatter, every rules file loads for every edit, dumping irrelevant conventions into context. The real power is separate files plus scoped loading.

How It Works

Drop markdown files into .claude/rules/. Claude Code recursively discovers them — no @import, no registration, no explicit reference needed.

.claude/rules/
├── code-style.md
├── testing.md
├── security.md
└── api/
    └── rest-conventions.md

Subdirectories are supported. Files inside api/ are discovered just like files at the root of rules/.

Each file can optionally include YAML frontmatter with a paths field:

---
paths:
  - "src/frontend/**"
---
React component conventions go here.

With paths, the file loads only when the edited file matches the glob. Without paths, the file loads for every edit — same as putting the content in root CLAUDE.md.

The Anti-Pattern: Rules Without Scoping

A project has 12 rules files, none with paths. Every edit loads all 12 — about 4,500 tokens. On average, only 2-3 files are relevant to any given edit (~1,000 tokens). That means 78% of the rules context is wasted on conventions the developer does not need right now.

Adding paths frontmatter to each file drops the average from 4,500 to ~1,000 tokens. The rules are still there — they just load only when they matter.

Combining files into fewer, larger files does not help. Four big files without scoping still load everything for every edit. The total token count stays the same. Fewer files just means bigger, harder-to-maintain blobs that still lack scoping.

Correct Organization Pattern

Distinguish between technology-specific and cross-cutting rules:

Technology rules scope to their directories. Cross-cutting rules (testing, security, API design) apply everywhere because they are relevant regardless of technology. React rules never load when editing Terraform. Terraform rules never load when editing React. But security rules are always present.

Glob Patterns for Cross-Directory Files

Test files often live in every module directory: src/auth/auth.test.ts, src/billing/billing.test.ts, lib/utils/utils.test.ts. You cannot scope by directory because tests are everywhere.

The glob **/*.test.ts matches all test files regardless of directory depth. One rules file with this pattern replaces what would otherwise require a CLAUDE.md in every module directory — each containing identical test conventions, each requiring separate updates when conventions change.

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---
Testing conventions here.

This is why .claude/rules/ with paths is more flexible than subdirectory CLAUDE.md. Directory-level files scope by location. Glob-scoped rules scope by file pattern — they reach across the entire project tree.

Debugging: Rules Not Loading

If a rules file exists with correct content but conventions are not applied, check the paths glob. A pattern like terraform/*.tf misses files in terraform/modules/networking.tf — you need terraform/**/*.tf with the recursive wildcard. This is the most common failure mode: the file is there, the content is right, but the glob does not match the files being edited.

Rules files do not need @import to be discovered. If the file is anywhere under .claude/rules/, Claude Code finds it. If it is not loading, the issue is the paths pattern, not a missing reference.

Migration from Monolithic CLAUDE.md

A 400-line CLAUDE.md covering 6 topics migrates in one step: extract each section into its own file under .claude/rules/, add paths frontmatter where appropriate, remove the content from CLAUDE.md.

Preserve the original wording. The content was refined over time — rewriting from scratch risks losing nuanced conventions. The improvement is structural (modularity and scoping), not editorial.

Do not keep both the CLAUDE.md content and the rules files active simultaneously. Duplicate config risks contradictions and double-loads the same rules.

Things That Do Not Exist

• Multiple CLAUDE.md files in the same directory — Only one CLAUDE.md per directory level is recognized.
• Scoping by section headers — Section headers inside one file do not control which parts load. The whole file loads or it does not.
• Priority ordering — Rules files do not have higher or lower priority than @import references. They are different mechanisms, both project-level.
• File count limits — There is no practical limit on how many files .claude/rules/ can contain.

One-liner: Separate files for modularity, paths frontmatter for scoped loading — without both, you either have a monolith or a directory full of files that all load everywhere.