The CLAUDE.md problem — why per-developer context files fail at team scale

Every developer using Claude Code eventually writes a CLAUDE.md file. It takes about ten minutes, it immediately makes the AI better, and it feels like solving the problem.

For one developer, in one repo, using one tool — it is solving the problem.

Then a second developer joins. Then a second repo. Then someone on the team prefers Cursor. And the thing that worked so well starts failing in a specific, predictable way that has nothing to do with how well the file is written.

This is the CLAUDE.md problem: the right instinct implemented at the wrong scope.

What CLAUDE.md actually does

The mechanism is simple. Claude Code reads CLAUDE.md at the start of every session and treats its contents as standing instructions: this is the architecture, these are the conventions, run these commands, never touch that directory. A user-level file at ~/.claude/CLAUDE.md layers personal preferences across projects. The repo-level file gets committed to git, so teammates cloning the repo get it too.

It's a genuinely good design for its scope. The file is plain markdown, versioned with the code it describes, and requires no infrastructure. If you work alone, in one repository, with Claude Code as your only AI tool — stop reading, you're fine.

Teams are not fine. Four structural limits see to that.

Limit 1: one tool reads it

CLAUDE.md is a Claude Code convention. Cursor doesn't read it. Copilot doesn't read it. Gemini doesn't read it. A ChatGPT tab certainly doesn't read it.

Real teams run mixed toolchains — a 2025-vintage team plausibly has Claude Code in the terminal, Cursor as the editor, Copilot in reviews, and a chat tab open for everything else. Each tool has its own context convention: CLAUDE.md, .cursor/rules, custom instructions, project knowledge. Same knowledge, four formats, four places to update.

So the team's context becomes a matrix: tools × repositories, every cell hand-maintained. Nobody updates a matrix. They update one cell and move on, and now the tools disagree about how the codebase works — which is worse than no context, because each tool sounds equally confident.

Limit 2: one repo holds it

Whatever Claude learns in repository A stays in repository A. Your API conventions, your deployment gotchas, your "never do X in prod" rules — if they live in one repo's CLAUDE.md, every other repo starts from zero.

Teams respond by copy-pasting a template CLAUDE.md across repos. Now there are N copies, and copies drift. The moment someone fixes an instruction in one repo and not the other nine, the team has forked its own conventions. Nobody notices until two services ship inconsistent behavior and the postmortem traces back to two files that were identical eight months ago.

Cross-repo knowledge — the stuff that defines how a team works rather than how one service works — has no natural home in a per-repo file. That's not a criticism of the format. It's a statement of scope.

Limit 3: one person maintains it

Commit the file to git and everyone shares it — in theory. In practice three things leak:

• User-level files never sync. Everything in ~/.claude/CLAUDE.md is invisible to teammates by design. The senior engineer whose personal file contains the best debugging instructions on the team is sharing them with nobody.
• Local edits lag. Developers tweak the repo file mid-task and don't commit, or commit and don't announce it. Everyone's session starts from a slightly different brief.
• Knowledge accrues to whoever wrote it down. Each developer teaches their own AI something every week. Multiply by a team: everyone's AI knows something the others' don't, and there is no mechanism — none — for those learnings to merge.

The result has a name on every team that's hit it: N developers, N versions of the truth. The AI amplifies whichever version it was handed.

Limit 4: one context window loads it

CLAUDE.md is loaded in full, every session, no matter what the session is about. That has two costs.

The first is attention. Practitioners consistently converge on the same budget: roughly 80–120 high-signal lines before instruction-following degrades. Every line competes with every other line, so a 400-line file doesn't give you 400 lines of adherence — it gives you the model quietly deprioritizing some of your rules, and you don't get to pick which.

The second is tokens. The file rides along on every request whether it's relevant or not. Your database migration guide is in context while the AI writes CSS. At team scale, across thousands of sessions, "load everything always" is a real line item — and it buys worse adherence, not better.

So the file has a ceiling, and teams hit it precisely because they're doing the right thing: writing down what they know. The reward for documenting well is a file too big to obey.

The workarounds, and why they don't hold

Every team that hits these limits tries some of the same patches:

The template repo. One canonical CLAUDE.md, copied everywhere. Fails at limit 2 — copies drift, and pulling updates across N repos is a chore nobody owns.

Symlinks and includes. Clever, fragile, and still single-tool. Fails at limit 1 the day someone opens Cursor.

Per-editor rules, everywhere. Maintain CLAUDE.md and .cursor/rules and Copilot instructions in every repo. This is the matrix again, now with the maintenance burden made explicit. Teams that formalize it usually assign it to one unlucky person, which reintroduces limit 3.

The wiki. Put shared knowledge in Notion or Confluence and tell everyone to paste relevant bits into their AI. Accurate diagnosis, wrong delivery: knowledge no tool loads automatically is knowledge that's out of context exactly when it matters. Copy-paste is the failure mode we were trying to eliminate.

Each patch addresses one limit and leaves the others standing. That's the tell that the problem isn't the file's contents — it's the file's scope.

What a real fix has to look like

Work backwards from the four limits and the requirements write themselves:

1. Tool-agnostic. Context lives in one place that every AI tool loads — terminal, editor, chat — rather than in per-tool formats. In practice that means speaking a protocol tools already share, and MCP is that protocol.
2. Team-scoped, not repo-scoped. One source of truth above the repository level, so conventions exist once and every project inherits them.
3. Shared by default. When one person updates the context, every teammate's next session reflects it. No commit-and-announce, no personal files hoarding team knowledge.
4. Loaded by relevance. The AI gets the context the task needs, not the whole corpus on every request — which removes the size ceiling and the token overhead in one move.
5. Versioned with an audit trail. Teams need to see who changed the shared brief and roll it back — the git properties, kept, without the git scope.

Some of this genuinely exists piecemeal. Cursor's Team Rules give you enforcement — inside Cursor, on the Business plan. Vendor project features give you knowledge files — inside that vendor's app. Each solves its slice within its silo, which is rational for them and structurally incomplete for you.

This is the gap Contextium is built for: shared AI context infrastructure — one team-scoped, versioned source of truth that any MCP-compatible tool loads from, so teaching one AI teaches all of them. If your CLAUDE.md files are drifting apart, that's the specific comparison.

But the tool matters less than the diagnosis. If your team is maintaining the same knowledge in four formats across ten repos for five people — the file isn't the problem. The scope is. A per-developer file was never going to carry a team.

Keep the thin CLAUDE.md. Move the team's brain somewhere every tool can reach it.