When CLAUDE.md Stops Scaling
A CLAUDE.md (or .cursorrules, or AGENTS.md) in each repo is real shared context, and for one agent on one repo it's genuinely enough — don't buy anything. This page is honest about exactly where that breaks: not for a solo dev, but for a team. And what teams use instead.
The honest version
• One agent, one repo? A CLAUDE.md is enough. It's local,
versioned with your code, and the agent reads it every run. You don't need
First-Tree, and we'd rather say so.
• It stops scaling on a team. The file grows past a few
hundred lines and degrades; it's one flat file with no ownership; it's
vendor-specific (CLAUDE.md, .cursorrules, AGENTS.md — duplicated, drifting);
five people edit it five ways; a second repo means several stale copies of
one opinion.
• That's the line. First-Tree is shared context for agent
teams — small Markdown nodes, per-node ownership, PR review, read by
any agent. Use both: CLAUDE.md for repo-local execution, First-Tree for
team-wide context.
First: when a CLAUDE.md is genuinely enough
We'll start where most comparison pages won't: if you're one developer
working in one repository with one agent, a CLAUDE.md is the right
tool and you should not buy anything. It lives next to your code,
it's versioned by Git, and your agent reads it on every run. The same is
true of .cursorrules for Cursor or AGENTS.md for
Codex. It is real shared context, it costs nothing, and adding a platform
on top would only be overhead.
First-Tree is built for teams running agents across repos — not for the solo, single-repo case. If that's you, keep your CLAUDE.md and come back when your setup grows. The rest of this page is about the point where it does.
Where it stops scaling
A CLAUDE.md is one flat Markdown file. That's a feature at small scale and a constraint at team scale. Four things break, in roughly this order, as a team grows:
- The file degradesPast a few hundred lines, one flat file is harder for an agent to attend to evenly — the context exists but stops reliably landing.
- No ownershipIt's a single file with no per-section owner. Nobody is accountable for keeping the auth rules current versus the billing rules.
- Vendor-specific copiesCLAUDE.md for Claude, .cursorrules for Cursor, AGENTS.md for Codex — the same opinion, duplicated per tool, drifting apart.
- Per-developer driftFive people edit the file five different ways; add a second repo and you now have several stale copies of one decision.
None of these are bugs in CLAUDE.md — they're the inherent limits of putting team-wide context in a single per-repo, per-vendor file. The fix isn't a better file. It's moving that context up a layer.
What First-Tree is (and isn't)
First-Tree is not a replacement for your repo-local file, and it isn't a framework. It's a context tree: a Git repository where every directory is a domain and every file is a small Markdown node capturing a decision, a constraint, or who owns what. Instead of one flat file per repo, your team's shared context becomes many small nodes, organized by concern, that any agent reads — Claude Code, Codex, Cursor — with no lock-in to one vendor's file format.
Crucially, each node has an owner declared in its frontmatter, and changes go through pull request review like any other code. So the three things a flat file can't give you — per-node ownership, review, and one source of truth across repos and tools — come for free from the workflow you already use.
CLAUDE.md → First-Tree
| Dimension | CLAUDE.md / .cursorrules / AGENTS.md | First-Tree |
|---|---|---|
| Shape | One flat file per repo | Many small Markdown nodes, by domain |
| Best for | One agent, one repo (genuinely enough) | A team of agents across repos |
| Ownership | None — whole file, no owner | An owner per node (declared in frontmatter) |
| Changes reviewed | Informal, whoever edits | Via pull request, by node owner |
| Vendor | One file per tool (drifting copies) | One source, read by any agent |
| At a few hundred lines | Degrades — attention thins out | Stays scoped — agent reads only its nodes |
| Second repo | Another stale copy to maintain | Same nodes, no duplication |
| Lock-in | Vendor-specific format | None — plain Git, any agent, any language |
Use them together — different layers
This isn't a rip-and-replace. CLAUDE.md and First-Tree sit at different layers, and the clean split is by purpose:
- CLAUDE.md staysRepo-local, execution-level instructions: the build command, the test runner, the one gotcha specific to this service.
- First-Tree takes the restCross-cutting, team-wide context: decisions and their rationale, constraints, cross-domain relationships, ownership.
- The litmus testIf an agent needs it to design a task, it belongs on the tree. If only to execute one in this repo, it stays in CLAUDE.md.
In practice your CLAUDE.md gets shorter and points at the tree for anything shared. The file keeps doing what it's good at; the tree absorbs what made the file degrade. Because the tree is plain Git, your per-repo file and your shared nodes both live under the same review, history, and ownership.
The dividing line: a CLAUDE.md is for one repo; First-Tree is shared context for agent teams.
Keep the file for repo-local execution. When the same opinion starts living — and drifting — across several repos and several agents' config files, that's the signal to move it onto the tree: one set of owned, reviewed nodes every agent reads, instead of N stale copies. Open source and free.
The bigger picture
Per-repo agent files were the first version of shared context, and they worked — which is exactly why teams hit their ceiling. The durable version of the same idea keeps the small, local file and adds a shared, owned, reviewed layer above it. That's the foundation of running real AI agent teams, and how agentic coding holds up once more than one person and one agent are involved.
See also: writing a good CLAUDE.md, First-Tree vs the Claude Agent SDK (the SDK builds the agent; the tree gives it your team's context), and First-Tree vs Pydantic AI.