This post is a deep-dive commentary on Anthropic's guide "How Claude Code works in large codebases." The core thesis: Claude Code's success in large codebases is ~70% determined by the harness (the scaffolding built around the model) and only ~30% by the model itself.
Key points
- The harness, not the model, is the bottleneck. Anthropic's Applied AI team found enterprise outcomes depend more on surrounding infrastructure than on model benchmarks—e.g., a retailer built a skill connecting Claude to its analytics platform; an enterprise software company deployed LSP integrations org-wide before rollout.
- Why RAG fails at scale. RAG assumes the codebase is static enough for embedding pipelines to keep up. With active teams, indexes lag by hours to weeks, producing stale function references, deleted-module citations, broken cross-file context, and no freshness signals. This is systematic, not occasional.
- Agentic search is the alternative. Claude Code plans a search strategy, then traverses the filesystem, greps, and follows references in real time—no index to go stale. The catch: it needs enough starting context (a good harness) to know where to look.
- Five-layer harness architecture (build in order, don't stuff everything into CLAUDE.md): 1. CLAUDE.md – layered, auto-loaded context: repo root holds pointers, key pitfalls, and global conventions; subdirectories hold local conventions, test commands, deployment flows. Anthropic even recommends initializing in the relevant subdirectory rather than the repo root—Claude walks up the tree and still loads root-level files. 2. Hooks – deterministic enforcement (lint/format/security) plus a clever use: a stop hook that reflects on each session and proposes CLAUDE.md updates—a form of meta-learning. 3. Skills – on-demand expertise via progressive disclosure, optionally scoped to paths (e.g., a Deployment Skill bound to
- Three successful deployment patterns: 1. Make the codebase navigable: layered CLAUDE.md, subdirectory initialization, per-directory commands,
- Deeper implications. RAG's failure reflects a general law: past a complexity threshold, precomputed indexes always lag real-time state. AI coding competition is shifting from "whose model is stronger" to "whose harness is more mature"—CLAUDE.md files, hooks, and skills are engineering artifacts requiring version control, review, and maintenance. The author even draws an analogy between the harness design and LLM architecture itself (attention ≈ skills loading relevant expertise; positional encoding ≈ CLAUDE.md's spatial orientation).
- Limitations noted: extreme-scale repos, deep multi-language interop (JNI, FFI, WebAssembly), the latency cost of agentic search vs. RAG, and concrete security/audit mechanisms are not quantified.
- Original: https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start
- Chinese translation: https://blog.lightnote.com.cn/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start/
- Claude Code docs: https://code.claude.com/docs
- Skills best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
services/payments/).
4. Plugins – package and distribute what works; solves "tribal knowledge" fragmentation.
5. MCP Servers – connect internal tools and APIs.Complementary: LSP integrations (symbol-level navigation—"one of the highest-value investments" for multi-language C/C++ codebases) and subagents (separating exploration from editing to isolate context windows).
.ignore rules to exclude generated files, a root-level codebase map, LSP symbol search.
2. Actively maintain configuration: rules written for older models can constrain newer ones; review config every 3–6 months and after major model releases.
3. Organizational adoption: dedicated infrastructure teams, an "Agent Manager" role (or at minimum a DRI), cross-functional working groups (engineering + security + governance), and gradual rollout with mandatory code review.