Your CLAUDE.md is too long. The 200-line ceiling that actually works.

Most CLAUDE.md files we see are too long. Five thousand lines, six thousand. Every team rule, every legacy comment, every "I once tried this and it didn't work" footnote. The author feels productive writing them. The model reads the first stretch and skims the rest.

There is a ceiling, and it is lower than people think. Teams converge on it from experience, not from a spec sheet: keep CLAUDE.md under 200 lines, with the non-negotiables at the top. Everything else lives in docs the agent can pull on demand.

The 200-line ruleCopy Anchor Link

The number did not come from Anthropic. It hardened as community practice over months of teams watching long context files get ignored: past roughly 200 lines, the model treats the file the way you treat a 200-page Terms of Service — present, technically read, not actually attended to.

The mechanism behind it is documented. Anthropic's Claude Code best practices describe how context fills fast in long sessions and performance degrades as earlier instructions get compacted away — the top of the file survives verbatim while later sections get summarised. HumanLayer's guide to writing a good CLAUDE.md makes the complementary point: agent memory is explicit, not ambient, so an onboarding file has to say WHAT the project is, WHY conventions exist, and HOW to work — and anything beyond that is freight on every session. Cite those two for the mechanism, not the number: the 200-line ceiling itself is lore that works, not guidance Anthropic published.

A related number floats around alongside it: roughly 150 instructions is the most a CLAUDE.md can carry before rules start getting dropped. Not lines — instructions. Each "do this," "never that," "use X not Y" is one instruction. A file with 200 distinct rules already lives at the edge of what gets tracked; 500 is comfortably past it. Treat both numbers as a budget, the way you would a performance budget: the point is not the exact figure, it is that every line spends something.

This is not model deficiency. It is the same attention budget you have when someone hands you a 12-page onboarding doc on day one. You read the first page carefully, skim the middle, glance at the end.

What goes at the topCopy Anchor Link

Claude Code reads the file top to bottom. Long sessions get compacted; later sections get summarised; the top stays verbatim. The rule that follows: put the non-negotiables at the top, every time.

Our top-of-file reads:

# AGENTS.md

> **Maintenance rule**: under 200 lines. Domain-specific deep dives go to docs/.
> **Docs rule**: design decisions and lessons → docs/lessons.md. Read it first.
> **Lessons-first rule (HARD STOP)**: grep docs/lessons.md for your symptom BEFORE writing infra.
> **Phase rule**: active work is in .todo/phase-N-*/PRD.md, not invented sub-phases.
> **Deploy rule**: auto-deploy on push; manual publishes need user approval.

Five rules, two lines each. They sit at the top because if a session gets compacted and only the top survives, those five are the ones the agent needs. Note the shape: each rule is a pointer or a prohibition, never an explanation. Explanations live downstream; the top of the file is a control panel, not a textbook. The same discipline applies to Cursor rules for Next.js projects — the file that wins is the one the agent can hold in working memory, not the one that documents everything.

What stays outCopy Anchor Link

The biggest reduction we made was a category of content that felt important but was hurting more than helping: task-specific knowledge that does not apply to most tasks.

Database schema. Webhook payload shapes. Exact deploy-config syntax for one specific account. Per-component prop tables. The migration history of an old refactor.

That content has a home — docs/. It does not have a home in CLAUDE.md, because it gets injected into every session, including the ones where the user wants to fix a CSS bug and does not care about webhooks.

# Before (anti-pattern, do NOT do this)
## Database
Our posts table has columns: id, slug, title, description...
[200 more lines]

# After
## Database
Schema lives in the Drizzle schema file, not here.
Drizzle Studio for inspection; migration patterns → docs/database.md.

The file is a router. It says "here is what exists and how to find it," not "here is everything you would ever need to know about it." This is the same principle behind an agent-readable repository structure: flat layouts, meaningful names, and explicit conventions beat exhaustive documentation because the agent can navigate instead of memorise.

What stays inCopy Anchor Link

Three categories survive every cut:

1. Build, run, deploy commands. "Use bun install, not npm install." "Dev server runs at the repo root." "Manual publishes need approval." The single most valuable thing in CLAUDE.md is the build commands — if the agent gets that right, the rest is recoverable. Get them wrong and the agent burns a whole session fighting tooling before writing a line of code.

2. Locked decisions. "We use Drizzle, not Prisma." "Auth is Better Auth, not NextAuth." "Design tokens live in the tokens package, never inline hex." These prevent the agent from re-litigating choices the team already made. Every locked decision in the file is one yak-shave the agent never starts.

3. Forbidden patterns. "Never edit the hand-curated barrel file." "Never put hex values in feature code." "Never add artificial delays." Forbidden lists are tighter than guidelines, and the model treats them tighter. A prohibition is one instruction that covers a whole class of mistakes; a guideline is a paragraph the agent has to interpret.

Notice what the three categories share: they are all load-bearing on nearly every task. Commands, stack decisions, and prohibitions apply whether the agent is fixing CSS or migrating a database. Anything that only matters to one kind of task gets demoted to a topic doc.

Let topics graduate to their own filesCopy Anchor Link

The structural fix is one root file plus a docs/ directory of topic-specific files. Root stays under 200 lines. Each docs/<topic>.md carries 100–400 lines of deep context. The agent loads root every session and pulls a specific doc only when its task touches that area — and the root file tells it exactly which doc maps to which area.

That structure mirrors how a senior engineer onboards a junior: the README is the map, the deep-dives are the territory, and "go read the deep-dive for the system you are touching" is the rule. Nobody hands a new hire a 6,000-line onboarding doc and expects retention; agent context deserves the same respect. If your sessions already run long, pairing a lean context file with agent-session prompting habits compounds the gain — short memory plus sharp instructions beats either one alone.

One maintenance habit keeps the split working: whenever a topic doc stops being read, that is signal. Either the root pointer is unclear or the topic does not need a doc. Prune on evidence, the same way you would prune any documentation nobody opens.

The pattern that workedCopy Anchor Link

We split our CLAUDE.md into one root file plus the docs/ directory. Root is 187 lines. Each topic doc is 100–400 lines of deep context. The agent loads root every session and pulls a specific doc only when its task touches that area.

The measurable difference: compaction stopped eating our deploy rules, because the deploy rules sit in the top twenty lines instead of line 3,000. Sessions that previously drifted into re-litigated stack decisions stopped drifting, because the locked decisions are three lines the agent always sees. Token spend per session dropped as a side effect — hundreds of lines of Stripe payload shapes no longer ride along on CSS fixes.

How to know yours is too longCopy Anchor Link

A quick diagnostic: ask Claude Code to summarise your CLAUDE.md in 10 bullet points without looking at the file. If the bullets accurately reflect the rules you care about, the file is doing its job. If they are vague, generic, or miss your specific conventions — the file is too long, the model is summarising past the signal, and you are spending tokens on text the agent is not using.

The fix is not "write more." It is the opposite — cut everything that does not pass the "would a new senior engineer need this on day one?" test. The agent's bar is the same as theirs.

Short context files are one half of an agent-ready codebase; the other half is a repo the agent can navigate. Our full-stack kits ship with both: lean agent-context files, flat layouts, and conventions your coding tools actually respect — so you spend sessions shipping instead of re-explaining your repo.

SourcesCopy Anchor Link

• Claude Code best practices — context-window management and degradation in long sessions; cited for the compaction mechanism.
• Writing a good CLAUDE.md — WHAT/WHY/HOW onboarding pattern and explicit agent memory; cited for the router structure.
• Cursor rules for Next.js — keeping agent rule files within working memory.
• Agent-readable repository structure — flat layouts and explicit conventions over exhaustive docs.