How Claude Code Works in Large Codebases: Anthropic's Official Best Practices Guide

Anthropic Publishes Its Definitive Guide to Claude Code at Scale

On May 14, 2026, Anthropic published "How Claude Code works in large codebases: Best practices and where to start," a comprehensive guide covering how Claude Code performs in production-scale engineering environments — multi-million-line monorepos, distributed architectures spanning dozens of repositories, and organizations with thousands of developers.

The article frames Claude Code's approach as fundamentally different from RAG-based retrieval systems: rather than requiring centralized indexes, Claude Code navigates codebases agenically — reading files locally, running grep searches, and following symbol references. The quality of results depends heavily on how well the harness is configured.

The Five-Part Harness

The guide introduces a structured framework for extending Claude Code in large codebases, built from five complementary extension points:

CLAUDE.md Files

CLAUDE.md files provide session-level context that Claude loads automatically. Anthropic recommends keeping root-level CLAUDE.md files to roughly 2,500 tokens (~100 lines), noting that signal degrades past 200 lines. Subdirectory-level CLAUDE.md files work well for service-oriented codebases where each directory has its own build and test commands.

Context should be layered by directory: global conventions at the root, service-specific commands at the component level, and task-specific instructions within feature directories. Content that once guided Claude through patterns it struggled with may become unnecessary — or actively constraining — as new models ship, so periodic pruning is advised.

Hooks

Hooks are scripts that fire at key moments in Claude Code's execution lifecycle. Anthropic draws a sharp distinction between two hook use cases: preventing incorrect actions (the common interpretation) and continuous improvement (the more valuable one). A stop hook can reflect on what happened during a session and propose CLAUDE.md updates while the context is still fresh. The guide states plainly: "If an action must always happen, do not rely on CLAUDE.md. Use hooks. Memory is probabilistic; hooks are deterministic."

Skills

Skills package specialized task instructions that load on demand, rather than bloating every session with context that's only relevant to specific workflows. In large codebases with dozens of distinct task types, Anthropic recommends progressive disclosure: keep each session lean and let Claude invoke skills as needed, rather than front-loading all possible expertise.

Plugins and MCP Servers

Plugins bundle working configurations — CLAUDE.md content, hooks, skills, MCP server connections — into installable packages that can be distributed organization-wide. MCP servers connect Claude Code to internal tools and APIs, enabling it to query internal documentation systems, CI/CD pipelines, or proprietary data sources as part of a session.

Organizational Patterns

The guide identifies three configuration patterns that successful large-scale rollouts share: making codebases navigable from the first session, treating CLAUDE.md as a living document that evolves with each model update, and assigning clear ownership of the Claude Code setup through a dedicated infrastructure team or designated DRI.

A key finding: "The rollouts that spread fastest had a dedicated infrastructure investment before broad access." Teams that established cross-functional working groups — addressing engineering, security, and governance requirements — before opening access to all developers saw significantly faster adoption and fewer friction points.

Subagents for Context Isolation

The guide endorses subagents as "one of the most powerful tools available" for large codebase work. When Claude researches a codebase, it reads many files — all of which consume context. Subagents handle exploration in isolated instances, returning only what the primary session needs and keeping the working context clean for editing tasks.