How I Organized My CLAUDE.md in a Monorepo with Too Many Contexts

Problem

My Claude Code show a warning because my CLAUDE.md was 47k words - far above the recommended 40k.
Ideally, a CLAUDE.md should stay under 10k words for best performance
That's touch in a monorepo containing frontend, backend and core services

Insight / Fix

I realized each service doesn’t need all context at once. Backend components don’t need frontend guides, and vice versa.  
So I looked for ways to split CLAUDE.md into smaller, relevant pieces that load only when needed.

Method 1 — Split with @ References

Move long sections into separate docs and reference them using the @ syntax:

## Frontend
Use @docs/frontend-guideline.md for detailed frontend guidelines.

This improves organization but doesn’t reduce load. The referenced content still loads into memory at startup.

Method 2 — Conditional Loading

Reference docs but let Claude load them only when needed:

## Testing
See docs/testing-principles.md for comprehensive guide.

This keeps startup light and lets Claude decide when to load extra context.

Method 3 — Multiple CLAUDE.md Files per Service

Use one CLAUDE.md per service:

CLAUDE.md           ← Always loaded
frontend/CLAUDE.md  ← Auto-loads in frontend/
backend/CLAUDE.md       ← Auto-loads in backend/
core/CLAUDE.md    ← Auto-loads in core/

This way, only the relevant service context loads automatically when Claude edits that folder.

Result

I reduced the main CLAUDE.md from 47k to 9k words (-80%) - well under the 10k guideline.

CLAUDE.md (8,902 chars)
frontend/CLAUDE.md (8,647 chars)
backend/CLAUDE.md (7,892 chars)
core/CLAUDE.md (7,277 chars)

TL;DR

Use a hierarchical CLAUDE.md structure to load the right context per folder.
Split guidelines into separate docs and let Claude load them when needed.
@ helps organize content but doesn’t reduce loaded context.

This setup made Claude Code feel faster and more predictable. It’s a small change that helps keep large monorepos maintainable.