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.md consumes at startup Whether to trim, split or move content when the file grows 200 lines is a target, 4 MiB is the limit 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. What it costs at startup 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 Three options when it gets long Once you are past 200 lines, you have three moves. They do not have the same effect, so consider them in order. 1. Trim (the biggest win) 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. 2. Split (does not reduce tokens) 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. 3. Move (loads conditionally) This is the option that actually reduces tokens. Path-scoped rules: a rule in .claude/rules/ with a paths field only enters context when Claude reads a matching file. See Scope Claude Code rules to specific files Skills: these load when you invoke them or when Claude judges them relevant, so multi-step procedures belong here rather than in 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 loading 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. Keeping notes without spending tokens 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. Summary The target is under 200 lines per file; going over still loads, but adherence drops The point where a file stops loading entirely is 4 MiB The "200 lines or 25KB" read limit belongs to auto memory's MEMORY.md, not CLAUDE.md Splitting with @ imports does not reduce context; path-scoped rules and skills do Trim by asking whether removing a line would cause mistakes, then verify with /doctor and /context