Claude Code: Ditch Monolithic CLAUDE.md for Rules

Source: pub.spillwave.com

TL;DR

The story at a glance

Rick Hightower's article critiques how CLAUDE.md files in Claude Code projects balloon with mixed instructions, wasting context on irrelevant rules. It promotes splitting into a .claude/rules/ directory with path-scoped markdown files, where rules load conditionally based on file paths. This is reported amid growing use of Claude Code for development, as projects scale and context limits bind.[[1]](https://medium.com/@richardhightower/claude-code-rules-stop-stuffing-everything-into-one-claude-md-0b3732bca433)

Key points

Details and context

CLAUDE.md is a project root file that Claude Code automatically loads as high-priority memory for instructions on coding standards, architecture, and workflows. As projects grow, it becomes unwieldy, mixing frontend patterns with backend rules, all competing for Claude's attention regardless of task.[[1]](https://medium.com/@richardhightower/claude-code-rules-stop-stuffing-everything-into-one-claude-md-0b3732bca433)[[4]](https://kirill-markin.com/articles/claude-code-rules-for-ai)

The .claude/rules/ system, part of Claude Code's memory architecture, allows modular .md files organized by subdirectories like frontend/ or backend/. Path scoping uses YAML frontmatter like `paths: ["*/.tsx"]`, triggering on file reads to apply rules precisely.[[3]](https://rahuulmiishra.medium.com/your-claude-md-is-doing-too-much-heres-how-to-fix-it-2cc495ed3599)[[5]](https://agentfactory.panaversity.org/docs/General-Agents-Foundations/claude-code-teams-cicd/path-specific-rules-with-glob-patterns)

This addresses context token costs and improves adherence, as Anthropic recommends concise files; rules load with same priority as CLAUDE.md but conditionally.[[6]](https://claudefa.st/blog/guide/mechanics/rules-directory)

Key quotes

"Your CLAUDE.md file started small. A few build commands, a note about the test framework, a reminder about naming conventions. Then it grew... Now it is 400 lines long, and every single line loads into context every session." — Rick Hightower[[1]](https://medium.com/@richardhightower/claude-code-rules-stop-stuffing-everything-into-one-claude-md-0b3732bca433)

"Instead of one massive file, you split instructions into focused rule files scoped to specific file types. Your migration rules load only when Claude touches migration files." — Rick Hightower[[1]](https://medium.com/@richardhightower/claude-code-rules-stop-stuffing-everything-into-one-claude-md-0b3732bca433)

Why it matters

Large CLAUDE.md files dilute Claude's focus across growing codebases, raising token costs and reducing output quality in AI-assisted development. Developers save context space and enforce standards precisely, making Claude Code more reliable for teams on complex projects. Watch Anthropic updates on rule loading behaviors, like read-only triggers, as they may evolve with bug fixes.[[3]](https://rahuulmiishra.medium.com/your-claude-md-is-doing-too-much-heres-how-to-fix-it-2cc495ed3599)

What changed

(Article describes no concrete before/after shift in Claude Code features; it advises a practice shift from monolithic to modular files.)

FAQ

Q: What causes CLAUDE.md files to become problematic?

A: They start with basics like build commands but accumulate diverse rules such as API guidelines, React patterns, and security notes, reaching 400 lines. All content loads every session, flooding context with irrelevant instructions for the current task.[[1]](https://medium.com/@richardhightower/claude-code-rules-stop-stuffing-everything-into-one-claude-md-0b3732bca433)

Q: How does the .claude/rules/ directory work?

A: It holds modular .md files for instructions like testing or API design, loaded recursively by Claude Code. Files without path scoping load always; others use YAML frontmatter to scope by file paths.[[2]](https://codewithmukesh.com/blog/anatomy-of-the-claude-folder)[[3]](https://rahuulmiishra.medium.com/your-claude-md-is-doing-too-much-heres-how-to-fix-it-2cc495ed3599)

Q: What is path scoping in rules?

A: YAML frontmatter with a `paths` array of glob patterns (e.g., "*/.tsx") makes rules load only when Claude reads matching files. This keeps irrelevant rules out of context for other tasks.[[3]](https://rahuulmiishra.medium.com/your-claude-md-is-doing-too-much-heres-how-to-fix-it-2cc495ed3599)

Q: What should stay in CLAUDE.md versus rules?

A: Keep CLAUDE.md lean (under 200 lines) for universal project info like tech stack and builds. Move domain-specific sections longer than 15-20 lines to path-scoped rules files.[[2]](https://codewithmukesh.com/blog/anatomy-of-the-claude-folder)

[[1]](https://medium.com/@richardhightower/claude-code-rules-stop-stuffing-everything-into-one-claude-md-0b3732bca433)