CLAUDE.md is one of the best ideas in AI-assisted development. A project-level instruction file the agent reads before every session — architecture overview, tech stack, constraints, conventions. For small projects and short contexts, it works well.
At scale it breaks. Here's exactly where, why, and what to use instead.
The three failure modes
Failure 1: Attention dilution past ~300 tokens
Language models don't read flat files the way humans do. They weight content throughout the context, and that weighting isn't uniform — content earlier in a long file tends to receive more attention than content buried in the middle.
Past about 300 tokens (roughly 50-60 lines), a CLAUDE.md becomes a competition. The specific architectural constraint you need the agent to apply right now is competing for attention with the boilerplate at the top, the tech stack list, the deployment instructions, the conventions section.
The result: the agent reads the file but acts on the parts that got weighted highest — which may not be the parts relevant to your current task.
Failure 2: Stale context mixed with current context
CLAUDE.md files accumulate. You add the new constraint when it's established. You rarely remove the old one when it's superseded. Six months in, the file contains:
- Constraints that no longer apply (the auth approach you changed in February)
- Architectural decisions that have been superseded (the caching strategy you replaced)
- Notes that were relevant during one sprint but shouldn't be shaping AI behavior now
- Actual current constraints buried among the outdated ones
The agent can't distinguish fresh from stale. It treats a constraint from eight months ago with the same weight as one established last week, unless you've carefully dated and annotated everything — which adds length and compounds the attention problem.
Failure 3: One file can't serve multiple retrieval needs
Different sessions need different context. A session working on the auth flow needs auth architecture, the security constraints, the token handling decisions. A session working on the data pipeline needs schema decisions, the ETL constraints, the performance requirements.
A flat CLAUDE.md either includes everything (long, diluted) or misses something (short, incomplete). There's no way to load exactly what's relevant for the current session without pre-loading everything and hoping attention lands on the right parts.
The breaking point
In practice, CLAUDE.md works reliably up to about 50-80 lines (300-500 tokens). Most projects hit this limit within the first two months. After that, adding more content actively degrades the context quality — longer file, more competition, worse attention on the sections that matter.
The symptom: the agent starts making suggestions that violate constraints you know are in the file. Not because it didn't read it — because the constraint was weighted below the threshold of effective influence.
The replacement: entry file + knowledge graph
The pattern that scales is a short entry file that boots traversal into a structured knowledge graph. Instead of one long file the agent reads linearly, you give it a 50-line entry point that points to exactly what it needs.
The entry file (CLAUDE.md) — stays short, always:
# [Project Name]
## Start here
1. Read [[Session State — Project Name]] → current position, next step, open questions
2. Read [[Active Constraints — Project Name]] → non-negotiable limits for this project
3. Navigate to [[Project Hub]] for architecture and decisions
## Quick reference
- Stack: React 18 + FastAPI + Cloudflare Workers
- Repo: ~/repos/project-name
- Deploy: `npm run build && wrangler deploy`
- Tests: `pytest` (backend) / `npm test` (frontend)
## Agent behavior
Load session state before proposing anything.
Check active constraints before suggesting solutions.
Do not re-propose items in decision logs marked as rejected.
That's the whole CLAUDE.md. 30 lines. Clear traversal instructions. No content — only pointers.
The knowledge graph (in Obsidian or any linked markdown system):
Session State — Project Name.md ← 5-field operational record, updated every session
Active Constraints — Project Name.md ← deployment, compliance, architecture, scope limits
Project Hub.md ← links to all decision logs, architecture notes, open work
Decision Log — Auth Layer.md ← decision + reasoning + rejected alternatives
Decision Log — API Gateway.md
Architecture — Data Pipeline.md
Open Questions — Project Name.md
Each file is focused. Each file is current — because you update the specific file when something changes, not the monolithic CLAUDE.md. The agent reads only what's relevant to the current session.
How the agent traverses it
At session start, the agent reads the entry file (30 lines, under 200 tokens). The entry file points to session state and active constraints — the two files relevant to every session. The session state points to the project hub; the hub points to the specific decision logs and architecture notes relevant to what you're working on.
The agent follows links. Two or three hops reaches any relevant context. No attention dilution — it's loading targeted files, not scanning a wall of text.
Migration: what to pull out of CLAUDE.md
If you have a long CLAUDE.md that's already hitting these failure modes, migration is straightforward:
| What's in your CLAUDE.md | Where it goes |
|---|---|
| Current project state |
Session State — update it every session |
| Non-obvious rules and limits |
Active Constraints — organized by category |
| Architectural decisions |
Decision Log — [Topic] — with reasoning and rejected alternatives |
| Out-of-scope items |
Active Constraints → Scope Boundaries section |
| Tech stack / quick reference | Stays in CLAUDE.md — this is genuinely useful at the top level |
| Deployment commands | Stays in CLAUDE.md
|
After migration, your CLAUDE.md should be under 50 lines. If it's still longer than that, you haven't moved enough out.
The compounding benefit
The graph structure doesn't just fix the scale problem — it builds compounding context. Each decision log entry becomes a durable record. The session state carries the project forward. The constraints file stays current as the project evolves.
Six months in, you have an accumulated record of every decision, every rejected alternative, every constraint — all retrievable in two hops, all informing every session. The context quality improves continuously as you work, not just when you remember to update CLAUDE.md.
The Obsidian vault template that ships with this graph structure — entry file pattern, session-state format, active constraints template, decision log format, hub template, skill guides — is $49.
→ https://pharosml.gumroad.com/l/kvbhdo
If you're hitting CLAUDE.md length problems on your current project, the migration takes an afternoon. The template has the target structure ready to populate.
