Field guide · Claude Code at scale ✦ Anthropic blog
How the most successful Claude Code deployments are built — five extension points, layered in the right order.
01 — How Claude reads code
Claude Code walks the file system, reads files, greps for what it needs, and follows references across the tree. There is no index to build, maintain, or upload. Every instance works from the live codebase on your machine.
That choice — agentic search instead of retrieval over a pre-built index — is the foundation everything else rests on. Flip between the two approaches below to see why it matters as a codebase grows and changes.
No pipeline, no central index. The same files the team committed five minutes ago are the files Claude reads. Nothing to fall out of date. The tradeoff: Claude needs enough starting context to know where to look — which is what the rest of this page is about.
Embeddings lag behind a busy team. At scale, the pipeline can't re-embed fast enough. Retrieval hands back a function renamed two weeks ago, or a module deleted last sprint — with no flag that either is stale.
returns: getUserToken() — renamed 14 days agoThe quality of Claude's navigation is shaped by how well the codebase is set up. Teams that invest in setup see better results.
Ask it to find a vague pattern across a billion lines and you'll hit context limits before the work starts. The fix isn't a bigger model — it's giving Claude a map. That map is the harness.
02 — The five extension points
The most common misconception is that Claude Code's ability is defined by the model alone. In practice the ecosystem around the model — the harness — determines performance more than the model does.
Five extension points, plus two capabilities that round out the setup. Order matters: each layer builds on the one before it. Tap any row to expand it.
A root file for the big picture, subdirectory files for local conventions. They give Claude the codebase knowledge it needs to do anything well.
Because they load every session regardless of task, keep them focused on what applies broadly — or they become a drag on performance.
Most teams think of hooks as guardrails that stop Claude doing something wrong. The more valuable use is continuous improvement: a stop hook can reflect on a session and propose CLAUDE.md updates while context is fresh; a start hook can load team-specific context dynamically.
For linting and formatting, hooks enforce rules deterministically — more consistent than asking Claude to remember an instruction.
In a codebase with dozens of task types, not all expertise belongs in every session. Skills use progressive disclosure — specialized workflows load only when the task calls for them. A security-review skill loads when assessing vulnerabilities; a doc-processing skill loads when a change needs docs updated.
Skills can be scoped to paths: a payments team binds their deploy skill to that directory, so it never auto-loads elsewhere in the monorepo.
Good setups tend to stay tribal. A plugin bundles everything so a new engineer gets the same context and capabilities on day one. Updates distribute org-wide through managed marketplaces.
The Language Server Protocol is what powers "go to definition" and "find all references" in your IDE. Surfaced to Claude, it gives symbol-level precision: follow a call to its definition, trace references across files, distinguish identically named functions. Without it, Claude pattern-matches on text and can land on the wrong symbol.
For multi-language codebases (especially C / C++), this is one of the highest-value investments. LSP is accessed through the plugin layer.
The Model Context Protocol is how Claude reaches internal documentation, ticketing systems, or analytics platforms. The most sophisticated teams build MCP servers exposing structured search as a tool Claude calls directly.
A subagent is an isolated Claude instance with its own context window. It takes a task, does the work, and returns only the final result to the parent. Once the harness is in place, spin up a read-only subagent to map a subsystem and write findings to a file — then the main agent edits with the full picture.
03 — Making code navigable
Too much context in every session degrades performance; too little leaves Claude navigating blind. These are the upfront investments that make a codebase legible. Tap each one as you put it in place.
One caveat: even the hierarchical CLAUDE.md approach has edge cases — codebases with hundreds of thousands of folders, or legacy systems on non-Git version control. Those are coming in future installments of the series.
04 — Maintenance over time
As models improve, instructions written for today's model can work against a future one. A rule that kept an earlier model on track can stop a newer one from doing work it now handles well. Toggle the model below and watch the same rule flip from helpful to harmful.
The same applies to skills and hooks built to compensate for a specific limitation. A hook that intercepted writes to enforce p4 edit in a Perforce repo became redundant the moment Claude Code shipped native Perforce mode.
Plan a real configuration review every three to six months — and whenever performance feels like it's plateaued after a major model release.
05 — The organizational layer
The rollouts that spread fastest made a dedicated infrastructure investment before broad access. A small team — sometimes one person — wired up the tooling so Claude already fit developer workflows on first contact. First experiences were productive, and adoption spread from there.
Bottoms-up enthusiasm fragments without someone to centralize what works. Someone has to assemble and evangelize the conventions — a standardized CLAUDE.md hierarchy, a curated set of skills and plugins. Without that, knowledge stays tribal and adoption plateaus.
06 — Governance, early
In large organizations — especially regulated ones — governance questions surface fast. Three come up almost every time:
The pattern that works: start with a defined set of approved skills, required code-review processes, and limited initial access — then expand as confidence builds. The smoothest deployments stood up a cross-functional working group early, bringing engineering, infosec, and governance together to define requirements and build a rollout roadmap.
07 — Check yourself
Three questions. The traps are the real-world confusions the article calls out.
1. You have reusable expertise for security reviews. Where does it belong?
Right: skills use progressive disclosure. Putting it in CLAUDE.md loads it every session and competes for context — the most common mistake.
2. In a monorepo, where should you initialize Claude for a task?
Right: scoping to the relevant subdirectory keeps Claude focused. It automatically walks up the tree and loads every CLAUDE.md along the way, so nothing is lost.
3. Performance plateaus right after a major model release. First move?
Right: instructions written for an older model can fight a newer one. A config review every 3–6 months — and after big releases — is the recommended habit.