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 800 lines and ignores the rest.

There's a known ceiling, and it's lower than people think.

The 200-line rule

The community consensus that's hardened over the last six months: keep CLAUDE.md under 200 lines. Anthropic's own Claude Code best practices and HumanLayer's CLAUDE.md guide both land in the same place. Past that, the model treats the file the way you treat a 200-page Terms of Service — present, technically read, not actually attended to.

The cited number for how many instructions Claude reliably follows is around 150. Not lines — instructions. Each "do this," "never that," "use X not Y" is one instruction. A CLAUDE.md with 200 distinct rules already lives at the edge of what's tracked; 500 is comfortably past it.

This isn't model deficiency. It's 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 top

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

Our top-of-file in apps/landing/CLAUDE.md 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**: Railway = auto on push. Cloudflare = pnpm deploy script. npm publish = user approval.

Five rules, two-line each. They're at the top because if a session gets compacted and only the top stays, those five are the ones the agent needs.

What stays out

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

Database schema. Stripe webhook payload shape. The exact wrangler.toml syntax for our 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 doesn't care about Stripe.

# 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 `apps/landing/lib/db/schema.ts`.
Drizzle Studio: `pnpm drizzle-kit studio`.
For migration patterns → `docs/database.md`.

The file is a router. It says "here's what exists and how to find it," not "here's everything you'd ever need to know about it."

What stays in

Three categories survive every cut:

1. Build, run, deploy commands. "Use bun install not npm install." "Dev server: pnpm dev at root." "Deploy: pnpm --filter @otfdashkit/landing run deploy." The single most valuable thing in CLAUDE.md is the build commands — if the agent gets that right, the rest is recoverable.

2. Locked decisions. "We use Drizzle, not Prisma." "Auth is Better Auth, not NextAuth." "Tokens live in @otfdashkit/tokens, never inline hex." These prevent the agent from re-litigating choices we already made.

3. Forbidden patterns. "Never edit packages/ui/src/index.ts — barrel is hand-curated." "Never put hex in feature code." "Never call setTimeout for artificial delays." Forbidden lists are tighter than guidelines, and the model treats them tighter.

The pattern that worked

We split our CLAUDE.md into one root file + a docs/ directory with topic-specific files. Root is 187 lines. Each docs/<topic>.md 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.

That structure mirrors how a senior engineer onboards a junior: the README is the map, the docs are the deep-dives, and "go read the deep-dive for the system you're touching" is the rule.

How to know yours is too long

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're vague, generic, or miss your specific conventions — the file is too long, the model is summarising past the signal, and you're spending tokens on text the agent isn't using.

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