The exact token ranges that work — and the ones that cause Claude to start ignoring the bottom of your file.
Most CLAUDE.md files should be 400 to 1,500 tokens. That's roughly 250 to 1,100 words. Below 400 tokens and you're probably leaving context on the table. Above 1,500 tokens and position bias starts degrading the bottom of your file.
| Token range | Approximate words | Best for |
|---|---|---|
| 200–400 | 150–300 | Single-role users: writers, researchers |
| 400–800 | 300–600 | Most knowledge workers |
| 800–1,200 | 600–900 | Multi-role professionals, consultants |
| 1,200–1,500 | 900–1,100 | Technical specialists with specific constraints |
| 1,500–2,000 | 1,100–1,500 | Edge case — use only if your file is well-structured |
| 2,000+ | 1,500+ | Almost always too long — rules at the end get ignored |
Why position bias matters
Claude reads CLAUDE.md as context, top to bottom. Rules near the bottom receive less consistent attention — especially if the conversation has already accumulated context. A rule at line 3 might get applied 90% of the time. A rule at line 50 might get applied 40% of the time.
This isn't a bug — it's how language models weight context. You can test it yourself: put a clearly wrong rule at the end of a long CLAUDE.md and ask Claude to do something that should trigger it. It often won't.
1,500 tokens is the working ceiling for reliable behavior across the full file. At this length, you have room for:
That's enough for most users. If you need more, you're probably writing descriptions where you should write constraints — or you have too many rules, not enough specificity.
You don't need a long CLAUDE.md if you're doing one thing.
A writer using Claude to edit prose and nothing else needs three lines:
You are a line editor for technical writing.
Remove filler phrases: "in order to," "in order that," "in order for."
Kill every passive construction you find.
That's 75 tokens. It works. A 1,500-token file with guidance on project structure, API conventions, and error handling would actively hurt this writer's workflow — Claude would spend more time reading rules than producing useful output.
Technical specialists with specific constraints sometimes need length. A backend engineer with a monorepo, nested module conventions, and three different testing standards might genuinely need 1,200+ tokens — if each section is tight and non-redundant.
The test: every section in your CLAUDE.md should contain at least one rule Claude could violate. If a section could be deleted without changing behavior, it's taking up space.
Run this regularly on any CLAUDE.md over 600 tokens:
Redundant rules at the bottom of a long file are the main reason people think "CLAUDE.md stopped working." It didn't stop — it's just that the rules are past the position bias threshold and aren't being applied.
A 400-token CLAUDE.md with direct, actionable constraints gets read and applied. A 3,000-token CLAUDE.md with a mix of descriptions, aspirational guidelines, and rules-thatsorta-matters gets partially ignored — and the user doesn't know which parts are being skipped.
Claude's job is to be useful. Help it by being specific and concise. Constraint beats description every time.
Is there a minimum length?
No. A CLAUDE.md can be three lines and work fine. The minimum is "whatever gives Claude enough to not waste your time." For one-off tasks, a 50-token role statement is fine. For recurring work, a 200-token file with key constraints is enough.
What if I have more than 1,500 tokens of useful content?
Use nested CLAUDE.md files. In Claude Code, subdirectory CLAUDE.md files are read in addition to the root file. Your root file sets project-wide defaults; a /docs/CLAUDE.md handles documentation-specific conventions. This is how you handle monorepos and multi-specialist teams without bloating one file.
Does the token count include the template structure?
Yes. The tokens Claude counts include everything in the file: frontmatter, section headers, comments, examples, and the rules themselves. A file with a lot of example blocks will hit the ceiling faster than a file with sparse, directive rules.
What about the /docs directory?
CLAUDE.md reads /docs/CLAUDE.md for documentation-specific guidance — this doesn't count against your root file's token budget, but it does count in Claude's total context. The combined total should still stay under 2,000 tokens for reliable behavior.
My current CLAUDE.md is 2,500 tokens. Should I panic?
Run the pruning test before rewriting anything. If the bottom third of the file isn't being applied, cut it or move it to a nested file. If it is being applied and working, the length is justified — just monitor for drift over time.
Can CLAUDE.md have a maximum length enforced by Claude?
Not a hard maximum. The practical limit is position bias, which becomes noticeable above 1,500 tokens and severe above 2,000. There's no enforcement — it depends on how much conversation context precedes the CLAUDE.md rules in the prompt.
How do I count tokens?
Use a tool like Token Counter or paste your CLAUDE.md into any GPT-class tokenizer tool. Most editors have token-count plugins. As a rough rule: count characters, divide by 4, and you're close enough for planning.
Not sure if your CLAUDE.md is the right length? The Optimize tab at CoworKit analyzes your current file and tells you if it's too long, too vague, or structurally misaligned — with a rewritten version that fits the target token range. Free, no signup.
Practical guides and prompt patterns — no fluff, unsubscribe any time.