Running Coding Agents in Large Codebases and Monorepos

This skill distills Anthropic's official guidance on making Claude Code effective in multi-million-line monorepos: how agentic search works and why it beats RAG indexing, how to layer CLAUDE.md files hierarchically, how to cut noise with exclusions, when to reach for LSP, subagents, hooks, skills, plugins, and MCP servers, and how enterprises structure ownership of the rollout. Anthropic's framing: "the harness matters as much as the model."

When to use

• You are working inside a large codebase or monorepo (many services, hundreds of top-level folders, multi-million lines) or a distributed architecture spanning dozens of repositories, and need to navigate, scope, or configure an agent session.
• You are setting up or tuning the Claude Code harness for a big repo: CLAUDE.md files, hooks, skills, plugins, LSP integrations, MCP servers, subagents.
• You are planning an org-wide agent deployment across thousands of developers.
• Legacy stacks: the source says Claude Code performs better than most teams expect in C, C++, C#, Java, and PHP, particularly as of recent model releases — do not assume these need special treatment beyond LSP.

Do NOT lean on this skill for non-conventional environments: the guidance assumes code written mainly by engineers, versioned in Git, and organized in standard directory layouts. Game engines with large binary assets, unconventional version control, or non-engineer contributors need additional configuration work beyond these patterns. Extreme cases — hundreds of thousands of folders and millions of files — can break even the hierarchical CLAUDE.md approach; the source defers those edge cases to future coverage, so treat them case by case.

Rules

1. Navigate agentically; never build or depend on an embedding index. Traverse the file system, read files, grep for exactly what you need, and follow references across the codebase — the way a software engineer would. RAG indexes go stale because embedding pipelines can't keep up with active teams: by query time the index may point at a function renamed two weeks back or a module deleted a sprint ago, and nothing flags the result as stale. Agentic search works from the live codebase with no pipeline to maintain.
2. Treat CLAUDE.md as lean and layered. "The root file should be pointers and critical gotchas only; everything else drifts into noise." Put local conventions in subdirectory CLAUDE.md files. Files load additively as the agent moves through the tree, and they load at every session start no matter the task — restrict them to what applies broadly, or they gradually tax performance.
3. Initialize in subdirectories, not at the repo root. When a session starts deeper in the tree, Claude walks upward and picks up each CLAUDE.md along the path, so nothing defined at the root is lost. This works especially well in service-oriented codebases where each directory carries its own test and build commands.
4. Scope test and lint commands per subdirectory. Record the commands that apply to each section in its CLAUDE.md. Kicking off the repo-wide suite after touching a single service invites timeouts and floods the context with output unrelated to the change.
5. Exclude noise, and version-control the exclusions. Use .claudeignore files to exclude generated files, build artifacts, and third-party code. Commit permissions.deny rules in .claude/settings.json so the exclusions travel with the repo and each developer inherits the same noise reduction with zero per-machine setup.
6. Give the agent a table of contents when structure is unconventional. A lightweight markdown file at the repo root listing each top-level folder with a one-line description lets the agent scan before opening files. With hundreds of top-level folders, layer it: keep only the top-most structure in the root file and push the next level of detail into subdirectory CLAUDE.md files that load on demand. For simpler cases, @-mentioning the specific files or directories does the same job.
7. Use LSP for symbol-level precision in typed and compiled languages. LSP gives go-to-definition and find-all-references: follow a call to its definition, trace references across files, distinguish identically named symbols. Without it the agent pattern-matches on text — grep for a common name returns thousands of hits and context burns while opening files to sort them out; LSP returns only references to the actual symbol, so filtering happens before anything is read. Setup requires the code intelligence plugin plus the language server binary per language. One enterprise software company rolled out LSP integrations across the org ahead of Claude Code itself, precisely so C and C++ navigation would hold up at scale.
8. Split exploration from editing with subagents. A subagent is a separate Claude instance in its own context window: it takes an assignment and hands back only the end result, keeping intermediate exploration out of the parent's context. Proven pattern: dispatch a read-only subagent to survey a subsystem and record findings in a file, then have the main agent make the edits informed by that map — the main context window stays free for the edit.
9. Enforce mechanical rules with hooks, not instructions. For checks like linting and formatting, hooks apply the rules deterministically and produce more consistent results than relying on the agent to remember an instruction. A stop hook can look back over the session and suggest CLAUDE.md edits before context goes stale; a start hook can pull team-specific context in dynamically so each developer gets the right setup for their module.
10. Offload specialized workflows into skills via progressive disclosure. In a codebase with dozens of task types, not all expertise belongs in every session. Skills load domain knowledge only when the task calls for it, and can be scoped to paths: a payments team can attach its deployment skill to its own directory so it stays dormant when work happens elsewhere in the monorepo.
11. Distribute working setups as plugins. A plugin bundles skills, hooks, and MCP configurations into one installable package — a new engineer installing it on day one gets the same context and capabilities as existing users. Manage updates through a marketplace.
12. Connect internal systems through MCP servers. The deepest integrations expose structured search as an MCP tool the agent invokes directly; lighter patterns wire in internal documentation, ticketing systems, or analytics platforms. Example from the source: a large retail organization built a skill connecting Claude to its internal analytics platform and distributed it as a plugin before broad rollout.
13. Review the harness configuration every three to six months, and whenever performance plateaus after a major model release. Instructions written for the current model can work against a future one — guidance for patterns an old model struggled with becomes unnecessary or actively constraining. Example: a hook that forced p4 edit before file writes in a Perforce codebase stopped being needed once Claude Code shipped native Perforce mode. Remove constraints that block coordinated cross-file edits newer models handle well.
14. Invest in the organizational layer before broad access. Successful enterprise rollouts had dedicated infrastructure investment first — a small team, sometimes one person, wiring up tooling so Claude fit developer workflows from first touch. Minimum viable structure: a DRI with ownership over configuration, settings, permissions policy, the plugin marketplace, and CLAUDE.md conventions, plus authority to make calls and responsibility to keep them current. Some orgs add an "agent manager" — a hybrid PM/engineer role managing the ecosystem. Without central coordination, know-how stays locked inside individual teams and adoption levels off.
15. In regulated industries, gate the rollout. Establish cross-functional working groups early (engineering, information security, governance). Begin with an approved skill set, mandatory code-review processes, and a small initial user group; widen access as confidence builds.
16. Sequence adoption: CLAUDE.md first, then hooks, skills, plugins, LSP, MCP servers. CLAUDE.md files are the highest-leverage first step because they load automatically at every session start; the rest layer on top.

Checklist

Working a task in a large repo:

• Start the session in the relevant subdirectory, not the repo root.
• Confirm CLAUDE.md files loaded up the tree; check subdirectory files for local conventions and commands.
• Search with grep/file traversal from the live tree; follow references instead of guessing paths.
• Run only the subdirectory-scoped test/lint commands for the code you changed.
• For a large unfamiliar subsystem, dispatch a read-only subagent to map it and write findings to a file before editing.
• Prefer LSP go-to-definition / find-all-references over text matching when the integration is available.

Configuring the harness for a big repo:

• Root CLAUDE.md contains pointers and critical gotchas only; details pushed to subdirectory files.
• .claudeignore excludes generated files, build artifacts, third-party code.
• permissions.deny rules committed in .claude/settings.json.
• Repo-root table-of-contents markdown exists if the directory structure is unconventional.
• Per-directory test/lint commands documented in each section's CLAUDE.md.
• Hooks enforce lint/format deterministically; stop hook proposes CLAUDE.md updates; start hook loads module context.
• Specialized workflows moved into path-scoped skills; setups bundled as plugins for distribution.
• LSP plugin + language server binaries installed for typed/compiled languages (C, C++, C#, Java, PHP included).
• Configuration review scheduled every 3–6 months and after major model releases.
• A DRI owns configuration, permissions policy, plugin marketplace, and CLAUDE.md conventions.

Anti-patterns

• Building a RAG/embedding index over the codebase. It is stale by query time on an active team and adds a pipeline to maintain; agentic search from the live tree avoids both.
• A fat root CLAUDE.md. Everything beyond pointers and critical gotchas drifts into noise and drags on every session.
• Running the full test suite for a one-service change. Invites timeouts and burns context on unrelated output.
• Text pattern-matching where symbols matter. Without LSP the agent can land on the wrong identically-named symbol.
• Relying on the agent to remember mechanical rules. Lint/format instructions in prose are less consistent than deterministic hooks.
• Loading all expertise into every session. Skills exist so specialized workflows load only when the task calls for them.
• Per-developer, un-versioned exclusions and configs. Commit them so the whole team gets the same noise reduction; distribute via plugins.
• Letting the configuration fossilize. Old constraints (e.g., the Perforce p4 edit hook) become redundant or actively harmful as models and the harness improve.
• Broad rollout with no owner. Without a DRI and central coordination, know-how stays siloed and adoption levels off.
• Assuming the patterns transfer to non-conventional setups. Game engines with large binary assets, non-Git VCS, or non-engineer contributors need extra configuration work.

Source

• How Claude Code works in large codebases: Best practices and where to start — https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start — 2026-05-14

Distilled from the official document(s) above on 2026-08-12. If this skill and the source disagree, trust the source.