Most CLAUDE.md files I've seen are too long. 200 lines of coding conventions, API patterns, project context, debugging notes, and deployment steps all in one place. It works until you realize Claude is reading all 200 lines to answer a question about button spacing.
Claude reads CLAUDE.md on every single turn. If yours is 200 lines, that's 4-6k tokens gone before the agent does anything. Most of it won't be relevant to whatever task is actually running.
The routing pattern
Keep CLAUDE.md short and have it point to other files.
# CLAUDE.md
Read these before anything else:
- rules.md — coding conventions and things not to do
- context/architecture.md — how the system is structured
- context/api.md — external API contracts and auth patterns
- sops/ — step-by-step guides for common tasks
Load only the files relevant to your current task.
That's 12 lines. Claude reads it, gets oriented, then pulls only what the task calls for.
Why it works
Claude doesn't need your deployment runbook to fix a CSS bug. When everything is in one file, it loads everything every time. When you split it out, it loads what's relevant.
The other thing: a 200-line CLAUDE.md goes stale fast. When you split by concern, updating the API notes means editing context/api.md, not hunting through a wall of text for the right paragraph. Changes stay local and the whole thing is easier to maintain.
The file structure
your-project/
├── CLAUDE.md # 10-15 lines, hub only
├── rules.md # Hard rules: naming, what to avoid
├── context/
│ ├── architecture.md # System overview, key decisions
│ ├── api.md # External services, auth patterns
│ └── data-models.md # Core types and their relationships
└── sops/
├── add-feature.md # How to add a feature here
├── debug-db.md # How to debug database issues
└── deploy.md # Deploy steps and gotchas
The SOPs folder is where this compounds over time. When Claude does something exactly right, write the steps down immediately and drop them in sops/. Next time you want the same outcome, paste that SOP into context. You're not re-explaining the same workflow from scratch every session.
Pair it with .claudeignore
The routing pattern handles what Claude should read. .claudeignore handles what it shouldn't.
A tight CLAUDE.md means useful instructions. A .claudeignore means Claude doesn't burn context reading package-lock.json, build output, or test fixtures. If you haven't set one up, I wrote about what actually goes in it.
The anti-pattern
I call it the monolith CLAUDE.md. It starts at 30 lines and ends up at 400. Every time Claude does something wrong, someone adds another rule. The file becomes load-bearing and unreadable, and nobody touches it because they're worried about breaking something.
The routing pattern forces a small decision before you write anything: is this a rule, some context, or a procedure? That decision makes the writing better too. Rules written for rules.md tend to be tighter than rules buried in a general-purpose config blob.
Getting started
If you have an existing long CLAUDE.md, this takes about 15 minutes:
- Go through the file and mark each section: rule, context, or procedure
- Create the folder structure above
- Move content to the right files
- Replace CLAUDE.md with the 12-line hub
The first task after migration will feel the same. By the 10th you'll notice the difference.
Part of a series on getting more out of Claude Code. Previous: What to put in .claudeignore
Want the full Claude Code playbook?
I put together everything I've learned about context management, CLAUDE.md patterns, .claudeignore setup, and autonomous agent workflows into one guide.
The Claude Code Playbook — $29, pay once, use forever.
Top comments (0)