How Claude Code works in large codebases: Best practices and where to start

Claude · article · 2026-05-14 source ↗ Reader 🖥️

Agent Governance (Internal)Agent Harness Agent Skills Agent Context Files (CLAUDE.md / AGENTS.md)Developer Experience & Flow MCP (Model Context Protocol)Progressive Disclosure Team Harness / Team-Layer Coding-Agent Platforms

At scale — multi-million-line monorepos, decades-old legacy systems, and organizations with thousands of developers — Claude Code's effectiveness is determined less by the underlying model than by a deliberately built harness (CLAUDE.md, hooks, skills, plugins, MCP servers, plus LSP integrations and subagents) and, just as importantly, by a durable organizational ownership structure (a dedicated owner or team, cross-functional governance, scheduled re-review as models evolve) that keeps good setups from staying tribal and adoption from plateauing.

practical · expository with illustrative narrative vignettes — An Anthropic blog post (credited to the Applied AI team via named acknowledgements) distilling patterns observed across enterprise Claude Code deployments in large codebases. Purely prescriptive/expository in structure, grounded in customer vignettes rather than controlled studies.

Structure

Part	Role
Framing: Claude Code in production at large-codebase scale	context
How Claude Code navigates large codebases: agentic search vs. RAG indexing	evidence / argument
'The harness matters as much as the model': five extension points plus LSP and subagents	taxonomy
Three patterns for making the codebase navigable at scale (CLAUDE.md layering, subdirectory initialization, scoped test/lint commands, ignore files, codebase maps, LSP)	practical guidance
Actively maintaining CLAUDE.md as model intelligence evolves	argument
Assigning ownership for Claude Code management and adoption	argument
Applying these patterns to your organization (scope caveats)	conclusion / caveat

Key terms

Agentic search
Claude Code's approach to codebase navigation: traversing the live file system, using grep, and following references the way a human engineer would, with no embedding pipeline or centralized index to build or maintain.
Harness Agent Harness
The ecosystem built around the model — specifically five extension points (CLAUDE.md, hooks, skills, plugins, MCP servers) plus two additional capabilities (LSP integrations, subagents) — that the article argues determines Claude Code's large-codebase performance more than the model itself.
Agent manager
An emerging, named organizational role: a hybrid PM/engineer function dedicated to managing an organization's Claude Code ecosystem — settings, permissions, plugin marketplace, CLAUDE.md conventions — as opposed to a single engineer's informal, part-time stewardship.
DRI (directly responsible individual)
The minimum-viable ownership structure for organizations without a dedicated agent-management team: one person with explicit authority over settings, permissions policy, the plugin marketplace, and CLAUDE.md conventions, and responsibility for keeping them current.
Progressive disclosure (for skills) Progressive Disclosure
Loading specialized expertise (a skill) only when the task at hand calls for it, rather than keeping all possible domain knowledge present in every session — the mechanism skills use to avoid context bloat in a codebase with many distinct task types.

Propositions

explicitClaude Code navigates large codebases the way a human engineer would — traversing the file system, using grep, following references on the live codebase — rather than via a pre-built embedding index, which avoids the staleness failure mode of RAG-based retrieval tools (returning a renamed function or a deleted module with no indication either is out of date) but trades that for a dependency on the codebase being well set up with layered context.conf: high
extendsAlex Wang's Post · p1 — Both agree CLAUDE.md should hold stable project context rather than procedure; this article adds the large-scale elaboration (root-vs-subdirectory layering, lean root file) of the same principle.
explicitThe harness built around the model — not the model's raw benchmark capability — determines how Claude Code performs in a large codebase more than the model alone; teams who evaluate only model benchmarks are focused on the wrong lever.conf: high
explicitThe harness has an intentional build order across five extension points — CLAUDE.md, hooks, skills, plugins, MCP servers — each layer building on what came before, plus two further capabilities (LSP integrations, subagents) that round out the setup.conf: high
supportsAgent Harness Engineering · p4 — Both converge on keeping CLAUDE.md lean and purposeful (every line earning its place) as a load-bearing principle of harness design, here generalized into guidance for layering root vs. subdirectory files.
explicitcorroboratedHooks' most valuable use is not preventing mistakes but making the setup self-improving — e.g. a stop hook that reflects on a session and proposes CLAUDE.md updates while context is fresh, or a start hook that dynamically loads the right team-specific context per module without manual configuration.conf: high
supports ←A harness for every task: dynamic workflows in Claude Code · p7 — Both describe the same self-improving loop — mining sessions/corrections to update CLAUDE.md — via different mechanisms (a stop hook there, an explicit mining workflow here); convergent evidence for 'self-updating context files' as an emerging pattern.
explicitdevelopedSkills exist to solve a scaling problem specific to large codebases: with dozens of distinct task types, loading all specialized expertise into every session would bloat context, so skills load on demand (progressive disclosure) and can be scoped to specific paths so they activate only for the team that owns that part of the codebase.conf: high
supportsAlex Wang's Post · p2 — Both agree repeatable procedures belong in skills, not CLAUDE.md, with this article adding the organizational rationale (context bloat across dozens of task types at scale) for why that separation matters more as codebases grow.
extends ←A harness for every task: dynamic workflows in Claude Code · p3 — Large-codebases piece frames skills as solving the scaling problem of loading only task-relevant specialized expertise; this article generalizes the same bounded-context principle into a full runtime-composed multi-agent harness, not just selective skill loading.
extends ←Agent Skills · p7 — That extraction notes skills can be path-scoped so they activate only for the team that owns that part of the codebase; this whitepaper generalizes the same idea into an explicit organizational principle (domain teams author and own domain skills, hours-to-days cycle) with a concrete comparison against centralized model-swap cycles (days-to-weeks).
explicitPlugins exist to solve an organizational, not technical, problem — that 'good setups can stay tribal' — by bundling skills, hooks, and MCP configurations into a single installable package so a new engineer gets the same context and capabilities on day one that existing users built up incrementally.conf: high
supportsAudit your Agent files · p2 — Plugins and centralized ownership are presented here as the organization-scale fix for the same tribal-knowledge/bloat dynamic that the other article's bloat-formation cycle describes at the scale of one developer's personal setup.
explicitLSP integration gives Claude symbol-level precision (distinguishing identically-named functions, following exact references) instead of text pattern-matching, and is one of the highest-value investments specifically for multi-language codebases — one enterprise software company deployed it org-wide before their Claude Code rollout specifically to make C and C++ navigation reliable at scale.conf: high
explicitAs models evolve, CLAUDE.md instructions and compensatory skills/hooks written for a weaker model's limitations can become unnecessary or actively counterproductive for a newer model — e.g. a rule forcing single-file refactors that blocks a newer model's legitimate coordinated cross-file edits — so teams should expect a meaningful configuration review every three to six months, and especially after major model releases.conf: high
explicitTechnical configuration alone does not drive large-scale adoption; the rollouts that spread fastest had a dedicated infrastructure investment (sometimes just one or two engineers, sometimes a whole team) wired up before broad access, so a developer's first experience with Claude Code was productive rather than frustrating.conf: high
explicitA new, hybrid PM/engineer role — 'agent manager' — is emerging in several organizations specifically to own the Claude Code ecosystem; organizations without a dedicated team should at minimum designate a DRI with explicit authority over settings, permissions policy, the plugin marketplace, and CLAUDE.md conventions.conf: high
explicitBottoms-up adoption generates enthusiasm but fragments without centralization — without someone actively assembling and evangelizing shared conventions, knowledge stays tribal and adoption plateaus, which the article frames as a specific organizational failure mode distinct from any technical limitation.conf: high
explicitIn large or regulated organizations, governance questions (who controls which skills/plugins are available, how to prevent thousands of engineers independently rebuilding the same thing, how AI-generated code goes through the same review process as human-generated code) come up early, and the smoothest deployments establish cross-functional working groups (engineering, information security, governance) before rollout rather than retrofitting governance afterward.conf: high
implicitThe article's whole harness-and-ownership prescription presupposes that engineering leadership is willing to fund a dedicated owner or team purely for agent-ecosystem management before usage data exists to justify the headcount — a resourcing commitment the article recommends but never quantifies in cost or ROI terms.conf: medium

Arguments

Organizations adopting Claude Code at scale should invest in a dedicated infrastructure/ownership function before broad rollout, not retrofit one after problems appear. strength: medium

Explicit premises:

Rollouts that spread fastest had dedicated infrastructure investment in place before broad access.
Bottoms-up adoption fragments without centralization, and knowledge stays tribal without someone assembling and evangelizing conventions.
In regulated organizations, governance questions come up early and are best addressed via cross-functional working groups established before rollout.

Implicit premises:

The cost of standing up a dedicated owner/team before usage data justifies it is lower than the cost of a fragmented, slow-adopting rollout — an assumption about relative costs the article doesn't quantify on either side.

Inferences:

An organization currently running a bottoms-up, ungoverned Claude Code rollout should expect to plateau, and should backfill a DRI or agent-manager role rather than waiting for the plateau to resolve itself.

Test, lint, and context configuration should be scoped per-subdirectory rather than applied uniformly at the repo root, especially in large monorepos. strength: high