Anthropic’s Claude Code Harness: Best Practices for AI Coding in Large Codebases

How Claude Code navigates large codebases

Claude Code traverses the file system, reads files, performs precise grep searches, and follows references, mirroring a human engineer’s workflow. It runs locally on the developer’s machine and does not require a pre‑built or maintained code index .

This contrasts with mainstream Retrieval‑Augmented Generation (RAG) pipelines that embed the entire codebase and retrieve snippets at query time. Because the embedding pipeline cannot keep up with commit velocity, indexes may lag by days or weeks, returning references to renamed or deleted symbols without indicating staleness.

Agentic search avoids the stale‑index failure mode by eliminating the embedding step and central index; each developer’s instance operates directly on the live codebase in real time.

The trade‑off is the need for sufficient initial context to guide the search. Attempting to locate “all similar patterns” in a billion‑line repository quickly exceeds the model’s context window, making a hierarchical context layer essential for effective navigation.

Seven‑layer extension system (Claude Code harness)

CLAUDE.md (layer 1) : Automatically loaded context file placed at the repository root (global overview) and in subdirectories (local conventions). Must be concise and broadly applicable to avoid performance penalties.

Hooks : Scripts that evolve configuration. A stop hook can reflect on a session and suggest updates to CLAUDE.md; a start hook can dynamically load context per module, removing the need for manual configuration.

Skills : On‑demand loading of domain knowledge without inflating each session. Example: a security‑review skill loads only when evaluating vulnerabilities; a documentation skill activates when code changes trigger doc updates. Skills can be scoped to specific paths, e.g., a deployment skill that runs only in the payment directory.

Plugins : Package and distribute proven configurations. In large codebases, valuable setups become “tribal knowledge”; plugins bundle skills, hooks, and MCP configuration into installable components for new engineers.

LSP integration : Enables symbol‑based search instead of raw string matching. Grep on a common function name may return thousands of hits, whereas LSP returns references to the same symbol, filtering results before file reads. One enterprise pre‑deployed LSP organization‑wide to ensure reliable C/C++ navigation at scale.

MCP servers : Bridge Claude to external tools such as internal documentation, ticketing systems, and analytics platforms, extending the AI’s reach into the organization’s internal ecosystem.

Subagents : Separate exploration from editing. A read‑only sub‑agent first surveys a subsystem and writes findings to a file; the main agent then edits with full context, avoiding context mixing when an instance both explores and modifies.

Validated configuration patterns

Pattern 1 – Make the codebase “navigable”. Effective deployments include a streamlined, layered CLAUDE.md (root contains pointers and key pain points), initializing CLAUDE.md in subdirectories rather than only at the repo root (Claude automatically traverses upward), running tests and linting scoped to subdirectories (full‑repo runs exceed context limits), using .ignore to exclude generated files and build artifacts, and, when the directory structure is unclear, creating a “code map”.

Pattern 2 – Configuration must evolve with the model. Instructions written for older models can become constraints for newer ones. For example, a rule forcing Claude to split each refactor into single‑file changes helped older models stay focused but blocks newer models that excel at cross‑file coordinated edits. The recommendation is to review the configuration every 3–6 months and immediately after major model releases.

Pattern 3 – Assign dedicated owners. Fastest adoption cases shared a common trait: before opening access broadly, a dedicated person or small team prepared the underlying infrastructure. One company pre‑built a full set of plugins and MCP; another formed a team to manage the AI programming tool. In both scenarios, developers’ first experience was “usable” rather than “painful”.

Implications for engineering teams

Enterprise‑grade AI programming tools succeed based on the maturity of their harness and the organization’s willingness to invest, not on model benchmark scores.

Continuous maintenance of the harness—similar to a CI/CD pipeline—is required because configuration rules written for older model versions can become burdensome as models evolve.

Original blog post: https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start