TL;DR — Anthropic published a best-practices guide for Claude Code in large codebases this week. It's good. It also stops at the boundary of a single repo, which is exactly the point at which the actually hard problems begin. After a year of driving Claude Code through five sibling repos in production — daily, not as a demo — here is what the guide leaves on the floor.
What the guide gets right
The single-repo advice is solid and matches my own setup:
- A
CLAUDE.mdat the root that names the load-bearing rules, the gotchas that already cost me a half-day each, and the non-negotiables. Not a manifesto — a debugging checklist for future-me. - Per-subsystem
CLAUDE.mdfiles inside the directories that have their own model (an Electron main process, an MCP handler tree, an SSE bridge layer). The agent reads them as it descends. - Slash commands and skills for the operations I do more than three times a week.
- Plan mode for any change that touches more than one file in a way I can't fully hold in my head.
If your project is one repo, that's most of what you need. Take Anthropic's post, do the work, ship.
Where the guide stops being useful
My actual product is five sibling repos that talk to each other through a Supabase project, a local MCP server, and a handful of Realtime channels. A single feature — "post a chat message from the browser and have a desktop Claude Code instance write the reply" — touches code in three of those repos. There is no single root to drop a CLAUDE.md into. There is no single Claude Code instance that can hold the whole problem.
The guide treats the codebase as the unit. In real life, my codebase is a federation, and that federation has its own physics:
- Identical handlers in two different processes. Chat-write code lives in
setu-nextjs/lib/mcp/handlers/chat/(for external OAuth-attached clients) and insutra/src/main/mcp/lib/mcp/handlers/chat/(for the local desktop instance, which is where ~99% of my traffic lands). When I fix a bug in one, I have to remember to fix it in the other. No tooling enforces this. The single-repo advice has nothing to say about it. - Channel-level handoffs between Claude Code instances. I run four Claude Code instances at once, each bound to its own MCP channel (
setu-channelfor chat,sandesh-channelfor content,swayam-channelfor automation routines,sankalp-channelfor job applications). When one of them needs the other to do work, it calls a*_chat_sendtool that wakes the target instance. That's not a code path the guide imagines — that's a multi-agent control flow that I had to invent because no single CC session can hold all four jobs without attention drops. - Cross-repo invariants that no agent can see. The push-notification dispatcher must be called from every chat-write surface across both
setu-nextjsandsutra. There is no test that fails when you forget. The agent will happily ship a new chat handler that omits the push call, because the omission is correct locally.
The guide's mental model is "one agent, one repo, one careful operator." My mental model is "four agents, five repos, one operator who can only watch two terminals at once."
What actually works at this scale
A year in, the things that move the needle aren't in the guide:
- A keystone
CLAUDE.mdat the federation root. Mine is 200 lines, lives one level up from the individual repos, and exists for exactly one purpose: when a fresh session opens, it sets the trap-list. "There are two MCP servers — don't fix the bug in only one." "Supabase project id is X, the decoy is Y, never apply migrations to Y." "Push dispatch must fire at every chat-write." It is not architecture. It is landmines, with maps. - Twin-handler discipline as a written rule, not a tooling promise. I have given up trying to auto-enforce it. What works is calling it out in the relevant subdirectory's
CLAUDE.md("⚠ this file has a twin at<path>— change both") and trusting the agent to read its own context before editing. - Channel separation between agents, not topics. When I tried to do code edits and content drafting and routine fires in one CC session, per-task quality dropped within an hour. Moving each concern onto its own channel with its own
CLAUDE.mdbrain ended that. The federation isn't just code-shaped — the operator's attention is also a resource being multiplexed, and channels are how I keep that from interfering with itself. - A non-negotiables list at the top of every brain file. Not best practices. Not preferences. The things that have already cost a multi-hour debug session. The agent reads them, I reread them, and the same hole doesn't get dug twice.
Why this matters
The single-repo Claude Code workflow is a solved problem now, and Anthropic's post is the right reference for it. But the next bottleneck — for anyone actually shipping a real system, not a demo — is the federation case. Multiple repos, multiple agents, shared invariants no tool can see. Right now the only thing keeping that from being chaos is a hand-written set of written-down landmines and a careful operator. That's fine for me, today. It is not going to scale to the next person who picks up this codebase, and it isn't going to scale to a team. The vendor guides are going to need to catch up to where the actual work happens.
Until they do, write your landmines down. The hard part of Claude Code in a large codebase isn't getting it to read the code. It's keeping it from quietly breaking the invariants the code can't tell it about.