Monolith vs Modular Rules

A single giant CLAUDE.md feels tidy, but every token in it is loaded into the context window on every single request of every session.

If your file holds 4,000 lines covering the backend, the iOS app, CSS conventions, and your release checklist, Claude pays that cost even when it is only fixing one CSS rule. That wasted context crowds out the code and history that actually matter.

This lesson is about splitting a monolith into modular rules that load only when relevant.

The win is simple: load rules on demand instead of always.

• A monolithic CLAUDE.md ships its entire body with every turn.
• Modular rule files in .claude/rules/ can declare which paths they apply to, so they load only when you edit a matching file.

Less always-on text means more room for the task, and fewer tokens billed per request. This directly serves Domain 5: Context Management & Reliability.

Before splitting, know the layers Claude Code reads from:

• User-level ~/.claude/CLAUDE.md — personal, NOT shared via VCS. New teammates never see it.
• Project-level ./CLAUDE.md or .claude/CLAUDE.md — shared via version control, so the whole team gets it.
• Directory-level — a CLAUDE.md scoped to a subtree, loaded when you work inside it.

Team-wide rules belong at project level. Anything in user-level is invisible to others.

The first splitting tool is the @path import. Keep a lean CLAUDE.md that pulls in detail files only where needed.

This keeps the top-level file readable and lets you reuse standards across projects. Note: an imported file still loads when the importing CLAUDE.md loads — imports organize content, they do not gate it by path.

The real token saver is .claude/rules/ files with YAML frontmatter. A paths glob tells Claude Code to load the rule only when you edit a file that matches.

Editing a .tsx component? The React rule loads. Touching only SQL? It stays out of context entirely. This is conditional loading versus the monolith's always-on cost.

Not everything should be path-scoped. The core CLAUDE.md should keep rules that apply everywhere, every time:

• Project overview and architecture summary.
• How to build, run, and deploy.
• Cross-cutting safety rules (e.g. "never run the OTA deploy without explicit approval").

Push domain-specific detail — language conventions, per-framework patterns, subsystem quirks — out into path-scoped rules. Core = universal; rules = situational.

A clean modular layout separates the always-on core from the on-demand rules and standards:

The lean root file orients Claude; rules/ files activate by path; standards/ files are imported where relevant. New teammates get all of it through VCS.

When you split, decide scope deliberately. A rule a teammate must follow belongs in a project-level file or .claude/rules/, checked into VCS.

A purely personal preference — your editor habits, your local shortcuts — belongs in user-level ~/.claude/CLAUDE.md. Putting a shared standard there is a classic mistake: it silently fails to reach the rest of the team.

There is a reliability reason to split too, not just cost. Models attend most to the start and end of context and least to the middle — the "lost-in-the-middle" effect.

A 4,000-line monolith buries critical rules in that low-attention middle. Smaller, path-scoped files keep each rule near the top of what loads, so the instructions that apply right now are far more likely to be followed.

You don't have to hand-edit these files blindly. Inside Claude Code, /memory opens and edits CLAUDE.md and persists the change across sessions.

Be careful with /compact: it compresses the running context and can make specific numbers, dates, and thresholds vague. It is not a substitute for structurally splitting your rules — compaction summarizes the conversation, modular files reduce what loads in the first place.

To split an existing monolith without losing rules:

• Keep universal rules (overview, build, deploy, safety) in the core CLAUDE.md.
• Group the rest by domain — one rule file per language or subsystem.
• Add a paths glob to each so it loads only on matching edits.
• Import shared standards with @path where they apply broadly.
• Verify nothing was dropped — every former rule should live somewhere reachable via VCS.

Your CLAUDE.md has grown to ~3,500 lines covering five languages and a deploy runbook. Most sessions touch only one language at a time, and context is running tight. As the architect, what is the best restructuring?

Key takeaways:

• A monolithic CLAUDE.md loads fully on every request, wasting tokens and burying rules in the low-attention middle.
• .claude/rules/ files with a paths frontmatter glob load only when matching files are edited — the core token saver.
• @path imports modularize and reuse standards; the core file keeps universal rules (overview, build, deploy, safety).
• Share team rules at project level via VCS; keep only personal preferences in user-level ~/.claude/CLAUDE.md.
• /memory edits persist; /compact is not a replacement for structurally splitting rules.