A single CLAUDE.md is one of the best things you can add to a repo. One developer, one repo, one agent: the file captures your build commands, your conventions, the shape of the project, and Claude Code starts every session already knowing them. It works beautifully — right up until your team grows past one of those three.
This is the wall almost every team hits with single-file agent context, whether it's CLAUDE.md, AGENTS.md, .cursorrules, or copilot-instructions.md. Here's exactly where it breaks, the patterns people reach for, and what actually scales.
The one-file setup that works great — until it doesn't
The magic of a context file is that it's read automatically and treated as always-true. You write "use pnpm, never npm" once and every session respects it. For a solo developer in a single repo, there's nothing better.
The trouble starts the moment you add a second of anything: a second teammate, a second repo, a second agent. Each one multiplies the file instead of sharing it.
Failure mode 1 — Drift
Five developers don't share one CLAUDE.md. They produce five slightly different ones, because everyone tweaks their local copy and not all of it gets committed. Now the agent gives different answers depending on whose machine — or whose branch — it's running on.
It gets worse with more than one tool. A team running both Claude Code and Codex keeps a CLAUDE.md and an AGENTS.md, and the two slowly diverge. A wrong instruction is worse than no instruction: the agent confidently follows a rule you abandoned last quarter. (If you're choosing between those two files, see AGENTS.md vs CLAUDE.md — but note the drift problem is the same for both.)
Failure mode 2 — No cross-repo memory
A CLAUDE.md lives inside a repository. By design, it cannot hold a decision that spans services. When your platform is 15+ repos and you're losing context across them, there is no single file every agent in every repo reads. You copy-paste the same conventions into a dozen files, and the day one changes, the other eleven are stale.
The obvious workaround — "just point one agent at all the repos" — hits the context-window wall fast, and even when it fits, dumping a dozen repos into one prompt doesn't tell the agent why a cross-cutting decision was made or who owns the part it's about to change.
Failure mode 3 — No ownership or review
A context file is a flat config. Anyone can edit it; no one owns it; there's no review gate. So nobody trusts it enough to put the important decisions in it — and the important decisions are exactly what an agent needs to act like a teammate instead of a very fast intern. Multiply that by N repos and you have an N× maintenance tax on knowledge nobody owns.
The patterns teams reach for — and where each stops
- Symlinks /
@import. Symlink a shared file into each repo, or use import directives. Helps with duplication, but it's still a flat file with no ownership, no review, and no structure — and it breaks the moment a repo needs to differ. - A
CONTEXT.mdsingle-source-of-truth with pointers. Better: one canonical doc, thin pointers in each repo. But it's still one big flat document that grows until no one (and no agent) reads to the bottom. - Vector / RAG memory. Embeds your docs so the agent can retrieve them. Good for recall over large corpora, but it answers "what did we write?" not "what did we decide, and who owns it?" — and retrieval is fuzzy where you need authority.
Each helps with one symptom. None gives you owned, reviewed, structured knowledge that every agent reads the same way.
What actually scales — a shared, owned context tree
The fix isn't a bigger file or a third file. It's moving the durable, cross-cutting knowledge out of any single repo into a layer above all of them: a context tree.
- Many small Markdown nodes, organized by domain — not one growing file.
- Owned. Every node has an owner (think CODEOWNERS, for knowledge).
- Reviewed. Changes go through draft → review → merge, like code, so the tree stays trustworthy.
- Agent-agnostic. It's plain Markdown over Git/HTTP, so any agent — Claude Code, Codex, Cursor, your in-house one — reads the same source.
- Cross-repo by default. It lives above your repos, so a decision that spans services has somewhere to live.
This is what First-Tree is built around. CLAUDE.md (and AGENTS.md) stay tight and per-repo; the tree holds the shared knowledge that would otherwise drift across a dozen files. We publish an open eval of how agents perform on shared-context tasks, and the deeper thinking behind it — the bottleneck was never intelligence, it was memory.
Migrating from per-repo CLAUDE.md to shared context
You don't rip out your CLAUDE.md files. You demote them:
- Leave a thin pointer in each repo. Keep the local, stable facts (commands, layout) in
CLAUDE.md; have it reference the shared tree for everything cross-cutting. - Promote the durable decisions up. The "why we chose X", "who owns the billing domain", "the rule that spans three services" — move those into owned nodes in the tree.
- Use one litmus test. If an agent needs it to design a task → it belongs in the shared tree. If it only needs it to execute in one repo → it stays in that repo's
CLAUDE.md.
The result: each repo's file gets shorter and more stable, the cross-cutting knowledge lives once, and every agent — in every repo — starts from the same ground.
FAQ
Does Claude Code read AGENTS.md?
Claude Code reads CLAUDE.md natively. AGENTS.md is the cross-tool open standard read by Codex, Cursor, Gemini CLI and others. Teams using both often keep one canonical file and point the other at it — see AGENTS.md vs CLAUDE.md.
CLAUDE.md or AGENTS.md — which should I use?
If you only run Claude Code, CLAUDE.md is fine. If you run more than one agent, make AGENTS.md the canonical file so every tool reads the same context. Either way, neither scales across repos on its own.
Can I share CLAUDE.md across multiple repos?
Not cleanly — it lives inside one repo, so you end up copy-pasting and the copies drift. Cross-repo knowledge belongs in a shared context tree every agent in every repo reads.
How do I stop CLAUDE.md from drifting?
Keep it minimal and local, move durable decisions into one owned, reviewed source, and treat that source like code (ownership + review). See writing a CLAUDE.md that works.
What goes in CLAUDE.md vs the shared tree?
Stable, local facts (commands, conventions, layout) stay in CLAUDE.md. Cross-cutting, evolving knowledge — rationale, ownership, how domains relate — goes in the shared tree.
First-Tree — Shared Context for Agent Teams. Run your agents on context that scales past one repo → first-tree.ai/agent-teams
