Originally published at https://aicoding-guide.com.
As you keep adding to CLAUDE.md, it gets hard to tell how much detail is too much. Longer feels more thorough, but it works the other way around: an oversized CLAUDE.md is a common reason instructions get ignored.
The documented target is specific: under 200 lines per file. This article explains what that number actually means, how it differs from the 4 MiB limit, and how to decide between trimming, splitting and moving content.
Key point
What you will learn
- What the 200-line target means, and how the 4 MiB number differs
- How much of the context window
CLAUDE.mdconsumes at startup- Whether to trim, split or move content when the file grows
Two numbers show up in the documentation, and they behave differently.
| Number | Kind | What happens past it |
|---|---|---|
| 200 lines | Recommended target | Still loads, but consumes more context and reduces adherence |
| 4 MiB | Actual limit | The whole file is skipped and never loads |
The documentation phrases the first as: target under 200 lines per CLAUDE.md file, because longer files consume more context and reduce adherence. Nothing breaks at line 201 — the cost grows gradually.
The 4 MiB figure is a real behavioral boundary: Claude Code loads a CLAUDE.md file of up to 4 MiB in full and skips a larger one. Plain prose will never reach that, but pasting a large log or generated artifact into the file can.
Don't confuse this with the auto memory limit
The rule that only the first 200 lines or 25KB are loaded, whichever comes first, applies to auto memory's MEMORY.md. The documentation states explicitly that this limit applies only to MEMORY.md. Your CLAUDE.md is not truncated at 200 lines. The same number means two different things depending on which file you are talking about.
The documentation includes an interactive simulation of what loads when a session begins. The values it uses as an example are:
| What loads | Example tokens shown |
|---|---|
| System prompt | 4,200 |
Project CLAUDE.md |
1,800 |
~/.claude/CLAUDE.md (user scope) |
320 |
Auto memory ( MEMORY.md ) |
680 |
| Skill descriptions | 450 |
These are illustrative figures from the simulation, not measurements of your files. They do give you the scale: a project CLAUDE.md costing roughly 1,800 tokens against a 200,000-token window.
The part people miss is subagents. A subagent loads CLAUDE.md into its own context. As the documentation puts it, the subagent loads CLAUDE.md too: same file, same content, but it counts against the subagent's context rather than yours. The built-in Explore and Plan agents skip it to keep their context smaller. If your workflow leans on subagents, the length of CLAUDE.md effectively multiplies.
To see the real numbers for your setup, run /context and read the Memory files section.
/context
Once you are past 200 lines, you have three moves. They do not have the same effect, so consider them in order.
The best practices page suggests testing each line with one question: would removing this cause Claude to make mistakes? If not, cut it. It also warns that bloated CLAUDE.md files cause Claude to ignore your actual instructions.
The documentation splits content this way:
| Include | Exclude |
|---|---|
| Bash commands Claude can't guess | Anything Claude can figure out by reading code |
| Code style rules that differ from defaults | Standard language conventions Claude already knows |
| Testing instructions and preferred test runners | Detailed API documentation (link to it instead) |
| Repository etiquette (branch naming, PR conventions) | Information that changes frequently |
| Architectural decisions specific to your project | Long explanations or tutorials |
| Developer environment quirks (required env vars) | File-by-file descriptions of the codebase |
| Common gotchas or non-obvious behaviors | Self-evident practices like "write clean code" |
For a checked-in CLAUDE.md, /doctor proposes trims: it cuts content Claude can derive from the codebase, such as directory layouts, dependency lists and architecture overviews, and keeps pitfalls, rationale and conventions that differ from tool defaults. The trim check requires Claude Code v2.1.206 or later.
Pulling sections into separate files with @path imports makes the file easier to read. It does not reduce context. The documentation is explicit: imported files are expanded and loaded into context at launch, and splitting into imports helps organization but doesn't reduce context.
Use it for readability, not for budget. The syntax and its pitfalls are covered in the Claude Code documentation on imports.
This is the option that actually reduces tokens.
.claude/rules/ with a paths field only enters context when Claude reads a matching file. See CLAUDE.md
The documentation gives the same advice: if an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule.
In a monorepo where other teams' files are being picked up, exclude them instead of shrinking your own file. See Stop Claude Code other teams' CLAUDE.md files. For managing context during a session rather than at startup, see Managing context in Claude Code.
Glossary
Context window: the total amount of text the model can reference in one exchange, including the conversation, every file read, and every command output. Accuracy degrades as it fills.
Block-level HTML comments in a CLAUDE.md are stripped before the content reaches Claude's context.
<!-- Note for human maintainers; never reaches Claude's context -->
## Tests
- Unit tests: `pnpm test`
The documentation describes this directly: block-level HTML comments are stripped before the content is injected into Claude's context, so you can leave notes for human maintainers without spending context tokens on them. Comments inside code blocks are preserved, and opening the file with the Read tool shows them.
One caveat: reducing line count without reducing content does not save tokens. Collapsing several lines into one long line changes nothing. Delete the content you do not need.
MEMORY.md, not @ imports does not reduce context; path-scoped rules and skills do/doctor and /context