bereniketech/claude-md-routing

CLAUDE.md Routing

1. The Problem

CLAUDE.md is loaded into every session as the system prompt. Everything in it costs tokens every single turn. Bloated CLAUDE.md = context rot faster, worse performance, higher cost.

Rule: Keep CLAUDE.md at 150–200 lines maximum. If it grows past that, trim or route.

2. What Belongs Inline vs. Routed

| Inline (in CLAUDE.md) | Route to a separate file | |----------------------|--------------------------| | Project goal (2–3 lines) | Style guide (colors, fonts, component rules) | | Tech stack (1 line) | Business context (user personas, domain glossary) | | Key folder paths | API reference docs | | Active skill imports (@ paths) | Historical decisions / ADRs | | Critical rules Claude must never forget | Onboarding / setup steps | | Pointers to routed files | Long checklists |

3. File Structure Template

.claude/
├── CLAUDE.md              ← lean — 150 lines max
├── context/
│   ├── style-guide.md     ← design tokens, component conventions
│   ├── business.md        ← domain, personas, terminology
│   ├── api-reference.md   ← endpoint list and shapes
│   └── decisions.md       ← architectural decisions log
└── project-config.md      ← skill list, stack, agent roster

4. Routing Syntax in CLAUDE.md

Point to routed files with a single line so Claude knows where to look without loading the content:

## Reference Files
- Style guide: `.claude/context/style-guide.md`
- Business context: `.claude/context/business.md`
- API reference: `.claude/context/api-reference.md`

Claude reads these on demand. They don't load into every session — only when the task requires them.

5. Trim Checklist

Run this when CLAUDE.md exceeds 150 lines:

• [ ] Remove any section that duplicates information in the code itself
• [ ] Move any list longer than 10 items to a routed file
• [ ] Remove "how to run" instructions (put in README)
• [ ] Remove content that hasn't been referenced in the last 5 sessions
• [ ] Collapse multi-paragraph explanations to a single sentence + pointer

6. Skill Imports Stay Inline

@ import lines are not routable — they must stay in CLAUDE.md for Claude Code to resolve them. Keep skill imports short and targeted: 2–6 skills per project, only the ones active for current work.

Rule: Don't import a skill just because it exists. Import it when the project needs it, remove it when the work is done.