How long should CLAUDE.md be? We measured 18 real instruction files

Every instruction file your agent loads at startup is in context in every session, before you type anything. So "how long should CLAUDE.md be" is really a question about budget: how much of the context window your standing rules take, and how many of those rules the model will actually follow. The official answer is short. The real-world answer, from repositories that maintain these files in the open, is more varied.

The official numbers

• Under 200 lines per file. Claude Code's memory docs say to "target under 200 lines per CLAUDE.md file", because longer files consume more context and reduce adherence. Claude Code warns at startup and in /status when a file is over the recommended length, and also when files that are each within it add up past a combined limit.
• 4 MiB hard stop. Claude Code skips a file over 4 MiB.
• 40,000 characters for files that load on demand. Since v2.1.309, a CLAUDE.md in a subdirectory, its imports and path-scoped rules are cut to their first 40,000 characters on a 200K context window (more on 1M context). The rest is only read if Claude opens the file itself.
• 32 KiB for Codex. OpenAI's Codex guide says Codex stops adding AGENTS.md files once the combined size reaches project_doc_max_bytes, 32 KiB by default.

@path imports don't help. Imported files load together with the CLAUDE.md that imports them, so splitting a long file into imports organizes it without making it any cheaper.

We measured 18 instruction files

We took the main agent instruction file from 16 well-known open-source repositories, plus the second file for nx and VS Code, as each file stood on 7 November 2026. Most are AGENTS.md rather than CLAUDE.md files; we include them because Claude Code reads AGENTS.md in place of CLAUDE.md when a project has no CLAUDE.md, so the same size question applies, and the two Copilot files because they are the main instruction file in VS Code's and TypeScript's repositories. CLAUDE.md files that only point at AGENTS.md (ruff's one-line import, the symlinks in pnpm and openai-agents-python) are left out, as are other secondary files such as Deno's .github/copilot-instructions.md. It is a small, hand-picked sample, not a survey. Lines are counted the way wc -l counts them.

What the numbers show

• The typical file is close to the guidance. The median is 158 lines and about 2,100 estimated tokens. Twelve of the 18 files are under 200 lines.
• Six are over it, some far over: Next.js at 538 lines and pnpm at 499. pnpm's AGENTS.md is 33,947 bytes, which on its own is just over Codex's default 32 KiB limit.
• Lines are a rough proxy for tokens. The average is about 13 estimated tokens per line, but openai-agents-python packs about 30 per line into 106 lines while Deno's 433 lines average about 7 and React's 13 lines about 6.5. In this sample, a 200-line file would cost anywhere from roughly 1,300 to 6,000 estimated tokens.
• Duplicates are real. nx keeps both a CLAUDE.md and an AGENTS.md, and 151 of the 155 non-blank lines in its AGENTS.md also appear in its CLAUDE.md. With Claude Code's default setting only the CLAUDE.md loads, but an agent that reads both pays for the same rules twice.

Small is also a valid choice. React's CLAUDE.md is 13 lines: what the repository is, which folder has its own instructions, and the current active work. VS Code's AGENTS.md is 5 lines that link to its Copilot instructions file; agents other than Copilot read that file only if they choose to follow the link.

How to trim without losing rules

Claude's docs suggest keeping CLAUDE.md to facts Claude should hold in every session: build commands, conventions, project layout and "always do X" rules. Everything else has a better home.

1. Scope it. Rules that matter only for part of the codebase go into .claude/rules/ files with a paths: list, which load when Claude works with a matching file, or into a CLAUDE.md in that package's folder, which loads when Claude works there.
2. Move procedures out. A multi-step release or migration recipe belongs in a skill, which loads only when you invoke it or Claude decides it is relevant.
3. Cut what the code already says. Full directory trees, dependency lists and long architecture overviews go stale and can be read from the repository; a few lines on where things live are enough. Claude Code's /doctor checkup proposes trims like these for a checked-in CLAUDE.md, and /doctor prompt-audit looks for outdated or contradictory instructions.
4. Hide maintainer notes. Block-level HTML comments in CLAUDE.md are stripped before the content reaches Claude, so notes for humans cost no tokens.
5. Keep one copy. If several agents need the same rules, keep them in one AGENTS.md and point CLAUDE.md at it, as described in AGENTS.md vs CLAUDE.md.

Measure your own

For a single file, wc -l CLAUDE.md gives the line count and wc -m CLAUDE.md the characters, which is the unit of the 40,000-character cut for subfolder files. For the total, run /context all in Claude Code and look under Memory files (files that load at launch; subfolder files load later). In a monorepo, measure from the folder where you usually start the agent, because each level above it adds its own files.

MonoVue, our VS Code extension, does that walk for the file you have open: pick an agent and it lists the instruction files that agent loads, with an estimated token count for each (the same estimator we used for the table above) and the total in the status bar. MonoVue Pro adds instruction health checks that flag duplicated rules, conflicts and paths that no longer exist.