How big should your CLAUDE.md actually be?

There's no token count that makes a CLAUDE.md "ideal." Anthropic's own guidance targets under 200 lines, and that's a line count, not a token budget - a 200-line file of dense prose and a 200-line file of terse bullets cost very different amounts. What actually matters is what the file costs a session to carry, and that number holds a surprise: even a genuinely bloated 12,000-token file costs about 27 cents over a 100-turn session at current Sonnet 5 rates. The reason to trim a CLAUDE.md was never the dollar bill.

Is there an ideal size for a CLAUDE.md file?

Not as a token count, no. Anthropic's own memory documentation gives one concrete number: "target under 200 lines per CLAUDE.md file... Longer files consume more context and reduce adherence." That's the only official size guidance that exists, and it's worth reading exactly as written - it's a line count, not a token or KB figure, and it comes with a mechanism attached (adherence), not just a limit.

Lines are a rough proxy for tokens at best. A line of dense prose and a line of a fenced code block cost different amounts per character, and a 200-line file that's mostly short bullet points can sit at a fraction of the token count of a 200-line file full of long paragraphs. The docs even draw a second distinction worth knowing: CLAUDE.md files load in full regardless of length - there's no truncation - while Claude's own auto-memory file (MEMORY.md) has a hard 200-line-or-25KB read limit, past which content silently stops loading. CLAUDE.md has no such safety net. Whatever you write, all of it loads, every session, no matter how long the file gets.

So "how big should it be" is really two different questions wearing one sentence: what does this file cost per session (a token and dollar question, answered below), and does its content earn a place that loads every single time regardless of what you're doing (an adherence question, answered further down). Neither one is answered by a line count alone.

What five real file sizes actually cost, computed

Three of those five token counts are this project's own measured numbers - its project CLAUDE.md (89 tokens), the AGENTS.md it imports (3,011 tokens), and its global ~/.claude/CLAUDE.md (6,344 tokens), all pulled from this site's real setup and already published in CLAUDE.md best practices. The 1,500-token and 12,000-token rows are labeled tiers, not measurements, standing in for a lean single-file project and a file well past the 200-line target.

The dollar figures are computed, not billed - Sonnet 5's published per-token rates run through a 40-turn session (one 5-minute cache write for the first turn, then 39 cache reads), the same rate mechanics covered in Claude Code's cost per token, rate by rate. None of these numbers move the needle on a bill. Even the bloated tier is a fraction of a cent per turn.

Why the cost compounds instead of adding up once

The number that actually grows isn't dollars, it's re-billed tokens - the same file, re-sent and re-priced as a cache read, every turn after the first. Claude Code has no memory between API calls: each turn resends everything already in context, and content that hasn't changed since the last turn comes back at the 0.1x cache-read rate instead of full price. Cheap per token, but it never stops accruing for as long as the session runs, and it stacks with everything else sitting in context at the same time - rules, imported files, prior tool output, the conversation itself.

That's the honest answer to "does CLAUDE.md size drastically impact usage," a question that shows up unanswered in more than one of the threads ranking for this topic: the per-token cost barely moves, but the tokens spent holding a file in place across a long session add up to something real even while the dollars stay small. A 12,000-token file re-bills nearly 1.2 million tokens of pure re-send by turn 100 - tokens that never bought a single new instruction, just carried the same one forward.

The point where a bigger file stops paying for itself

Given how small the dollar cost stays, the actual decision rule has nothing to do with a token threshold. It's whether a section is a standing rule a fresh session always needs, or something that only applies sometimes - and the second kind is exactly what Claude Code's .claude/rules/*.md with paths: frontmatter and Skills exist to hold instead, loading only when Claude actually touches a matching file or invokes the skill.

This project's own global CLAUDE.md is a real example of how much of a typical file is actually the second kind: of its 6,344 measured tokens, about 64% was trigger-gated workflow content - instructions that only apply in specific situations - rather than rules a session needs regardless of the task. That's not a guess; it's the split behind the same measured file shown in the table above.

Two more concrete checks, both straight from Anthropic's own docs: run /doctor on a checked-in CLAUDE.md and it proposes specific trims for content Claude can already derive from the codebase - directory layouts, dependency lists, architecture overviews - while keeping the pitfalls and conventions that don't come from reading the repo. And splitting a file with @import organizes it; it does not shrink what loads, since "imported files still load and enter the context window at launch" per the docs - a common assumption worth correcting before it drives a restructuring effort that saves nothing.

How to check your own file's real cost

The fastest way to get a number for your own setup: paste your CLAUDE.md or AGENTS.md into the token counter and it estimates the total plus which sections read as conditional rather than standing, the same heuristic this guide's own computed figures are built on. It's a text-paste estimate, not a billed number - for the real, measured figure from your actual session history, run npx usagecut and let the free scan read your real transcripts directly instead of estimating from pasted text.

Either way, the number to act on isn't the total - it's the conditional share. A large file that's almost entirely standing rules earns its size. A smaller file that's mostly "when running X, do Y" is paying full-session rent on content that only matters some of the time.

When trimming isn't actually the fix

If your CLAUDE.md is small and Claude still isn't following it, size was never the issue - vague instructions cost the same tokens as specific ones and get followed less reliably either way. Anthropic's own troubleshooting guidance points at conflicting instructions across files, content that never actually loaded (check with /context), or a rule stated once in conversation rather than written down, before it points at length. And if the goal is an enforced rule rather than a followed one - a lint check that must run before every commit, a command that must never execute - that belongs in a hook, not a CLAUDE.md line of any size.

FAQ

• What's the ideal size for a CLAUDE.md file? There's no ideal token count. Anthropic's own guidance targets under 200 lines, with the reasoning attached: longer files consume more context and reduce how reliably Claude follows them. Lines aren't a token count, so two 200-line files can carry very different token costs.
• Does the size of CLAUDE.md drastically impact usage and cost? The dollar cost stays small even at a bloated size - computed at Sonnet 5's rates, a 12,000-token file costs about $0.05 to $0.27 across a 10- to 100-turn session. What actually grows is the re-billed token count from carrying the same file across every turn, and the adherence cost documented directly in Anthropic's docs.
• Does splitting CLAUDE.md into smaller files with @import save tokens? No. Imported files are expanded and loaded into context at launch alongside the file that references them - splitting changes organization, not what loads every session.
• How do I know which parts of my CLAUDE.md are worth their tokens? Check whether each section is a rule every session needs regardless of the task, or one scoped to a specific situation. The second kind belongs in a path-scoped .claude/rules/*.md file or a Skill, which load only when relevant instead of every time.
• Will Claude Code tell me if my CLAUDE.md is too big? /doctor audits a checked-in CLAUDE.md and proposes trims for content Claude can already derive from the codebase, while keeping the conventions and pitfalls that differ from tool defaults.
• Is a bigger CLAUDE.md always worse than a smaller one? No - a larger file made entirely of standing rules a session actually needs earns its size. The problem is never length by itself; it's conditional content sitting in the always-on tier when it only applies sometimes.

None of this requires guessing at your own file's real number - the token counter estimates it from a paste in a few seconds, and the free scan reads your actual Claude Code session history for the measured version instead of an estimate. For what to actually move out of an oversized file and where it goes instead, CLAUDE.md best practices covers the mechanics section by section.

Made by Neo

UsageCut by ClockedCode - not affiliated with Anthropic. The figures on this page are measured on real Claude Code sessions and labeled measured or estimated where it matters.