百万行 monorepo 里的 Claude Code：Anthropic 官方拆解的 7 个扩展点与 3 大部署模式

原文：How Claude Code works in large codebases: Best practices and where to start · Anthropic · 2026-05-14

一句话导读：模型只是底座；真正决定 Claude Code 在大代码库里能跑多远的是它的 harness——CLAUDE.md、Hooks、Skills、Plugins、LSP、MCP、Subagents 这一整套扩展层。这篇按"是什么 → 为什么这么设计 → 怎么落地 → 别踩的坑"重新组织 Anthropic 官方文章，并补上对"DRI / Agent Manager 这一新岗位"和"3–6 个月配置审查节奏"两点反常识判断的解读。

引言：百万行 monorepo 里，那只索引追不上的兔子

如果你所在的工程组织已经迈过了 “demo 演示"阶段，开始把 AI 编码工具放进几百万行的 monorepo、跨数十个仓库的微服务、还有几十年没人敢动的 legacy 系统，会很快撞上同一个问题：

我接入的那个"代码助手”，每次给我的答案都像是上周的代码。

熟悉这种痛感的人都知道下一句是什么——RAG 索引追不上活跃团队的 commit 速度。Anthropic 在原文里直接点破了这个失败模式：“embedding pipelines can’t keep up with active engineering teams”，索引一旦滞后，工具就会"返回团队两周前刚改名的函数，引用上个 sprint 已经删掉的模块，并且不会告诉你这条结果其实已经过期"。

这就是为什么 Claude Code 走了一条完全相反的路——不建索引，每次都让模型像工程师一样在本地仓库里 grep / read / 跟引用。这条路看起来朴素到反直觉，却恰恰是它能撑起百万行 monorepo 的原因。

读完这篇你应该能回答三个问题：

1. **为什么 Claude Code 不用 RAG？**这条路径的优势和代价分别是什么？
2. **Harness 的七个扩展点怎么配合？**每一个该装多少，过载了会怎样？
3. **大组织怎么落地？**从个人工具到团队标准，中间需要哪些角色和节奏？

下面按这三层往下走。

一、Claude Code 怎么在大代码库里"导航"——Agentic Search vs RAG

它到底做了什么

Claude Code 在你机器上启动之后，处理一个任务时做的事情其实和一名靠谱工程师一模一样：

• traverses the file system：在文件树里走一遍
• reads files：打开它觉得相关的文件
• uses grep to find exactly what it needs：用 grep 精确定位
• follows references across the codebase：顺着引用跳到下一个相关位置

这套行为模式 Anthropic 把它叫做 agentic search——“agentic"的意思是：检索由 agent 当场发起，而不是事先建好的索引。

它的两个关键属性是：

• 本地运行：“operates locally on the developer’s machine”——你机器上的 Claude Code 直接读你机器上的代码
• 不需要索引：“doesn’t require a codebase index to be built, maintained, or uploaded to a server”——既不需要构建，也不需要上传到服务器维护

为什么这么设计：RAG 在快速迭代团队里的结构性失效

把 RAG 工具搬进活跃工程团队，问题不在精度，而在时效。原文给了非常直白的描述：

An indexed search returns a function the team renamed two weeks ago, or references a module that was deleted in the last sprint, with no indication that either is out of date.

中心化索引是一张昨天的快照，而工程团队今天还在改代码。两者之间天然有时间差，且这种过时不会主动告诉你——这是最致命的一点。

Agentic search 的代价也清楚地写在那里：它高度依赖你给它的初始 context 是不是足够窄、足够准。Anthropic 给了一句很值得抄下来的警告：

If you ask it to find all instances of a vague pattern across a billion-line codebase, you’ll hit context-window limits before the work begins.

也就是说，面对十亿行级别 + 模糊描述，agentic search 会先撞上 context 上限，再开始干活。所以代价就是把一部分认知工作从"建索引"前移到了"喂 context”——这正是 CLAUDE.md 和 skills 的角色。

怎么落地

记住一条心法：给 Claude Code 一个尽量小的"工作子树"。这件事原文用了一个反直觉的词：在 monorepo 里不要在仓库根目录初始化 Claude Code，要在子目录初始化。具体见后面"模式 1"。

别踩的坑

• 把"过时的命中"当成"工具不准"——不是它不准，是 RAG 索引天然滞后。
• 给 Claude Code 一个无范围的任务（“找出整个仓库所有用到 logger 的地方”），还希望它给你完整答案——这种任务必须先做范围收窄。

二、Harness 比模型更重要：七个扩展点的全景

关键判断：Claude Code 的能力不只由模型决定，真正的上限是包在模型外面的 harness——CLAUDE.md、Hooks、Skills、Plugins、LSP、MCP、Subagents 共同构成的扩展层。

很多团队只盯着模型 benchmark 选工具，这是一个结构性误解。原文用了非常直接的表述：“the ecosystem built around the model—the harness—determines how Claude Code performs more than the model alone”。

下面这张图把七个扩展点按"加载时机"和"职责定位"一次性铺平。理解每个扩展点最重要的一刀，是问自己：它在什么时刻进入 Claude 的视野？

1. CLAUDE.md：每次必加载的"项目记忆"

• 是什么：放在仓库里的上下文文件，每个 session 自动读入。
• 怎么落地：根目录文件写大局观（架构指针 + critical gotchas），子目录文件写局部约定。Claude 在工作时会自动一路向上遍历目录树，把沿途的所有 CLAUDE.md 都拼进 context。
• 别踩的坑：把它当百科塞——“keeping them focused on what applies broadly will prevent them from becoming a drag on performance”。一句话：CLAUDE.md 是项目专属，不是可复用专长。可复用的东西应该是 skill。

2. Hooks：让配置自我改进的钩子

• 是什么：在关键事件触发的脚本（start / stop / pre-tool / post-tool 等）。
• 反直觉点：很多人一提 hooks 想到的是"防止 Claude 干蠢事的拦截器"。原文给出了一个更高价值的用法——continuous improvement：
  • stop hook：在 session 结束时让 Claude 自己回顾过程，当 context 还热的时候直接给 CLAUDE.md 提改进建议。
  • start hook：根据当前模块自动加载团队特定上下文，让"每个开发者都拿到对的初始配置"这件事不用人手动点。
• 怎么落地：把 lint / format 等可机器确定的检查统统交给 hook，不要交给 Claude 去记——确定性脚本比"提示词里写的提醒"更稳。

3. Skills：渐进式专长

• 是什么：打包好的"特定任务专长"，按需加载而非每次都进 context（progressive disclosure）。
• 怎么落地：原文两个例子说得很清楚——安全审查 skill 在评估漏洞时被加载，文档处理 skill 在代码改动需要同步更新文档时被加载。可以把 skill 绑定到 path：负责支付服务的团队可以把部署 skill 绑定在那个目录下，别的目录不会触发它。
• 别踩的坑：把"可复用专长"硬塞进 CLAUDE.md。CLAUDE.md 是项目级、每次必加载；skill 是横向复用、按需触发。两者职责不能混。

4. Plugins：让"部落知识"变成组织标准

• 是什么：把 skills + hooks + MCP 配置打包成的可分发单元，通过 managed marketplaces 推送更新。
• 典型案例：原文里那家大型零售公司的做法值得抄——他们的工程团队先做了一个连接内部 analytics 平台的 skill，先打成 plugin 在小范围跑通，确认体验稳定后再向业务全面推广。这是把"个人级好实践"升级为"组织级能力"的标准做法。
• 别踩的坑：让一两个工程师做出的好配置一直停留在他们自己机器上——原文称之为 “good setups can stay tribal”。

5. LSP（Language Server Protocol）：把 grep 升级成"按符号搜"

• 是什么：让 Claude 能调用 IDE 级的"跳转到定义"和"查找所有引用"。
• 为什么关键：在大代码库里，grep 一个常见函数名可能命中几千个匹配，Claude 会逐个打开文件去判断哪个才是它要的——context 就这样烧光了。LSP 反过来，只返回真正指向同一个符号的引用，过滤发生在 Claude 读文件之前。
• 典型案例：一家企业软件公司在 Claude Code 全员铺开之前，先组织级部署了 LSP，专门为了 C/C++ 在大规模下的导航可靠性。在多语言代码库里这是 “one of the highest-value investments”。
• 别踩的坑：默认 LSP 自动启用——它不会。需要装 code intelligence plugin + 对应语言的 language server binary。

6. MCP servers：把外部世界接进来

• 是什么：让 Claude 能调用外部工具、数据源、API 的标准协议层。
• 进阶用法：原文里那句很好——“The most sophisticated teams built MCP servers exposing structured search as a tool Claude can call directly”。比起把检索丢给 grep，结构化检索 MCP 让 Claude 有更好的"问问题的姿势"。
• 别踩的坑：“before the basics are working” 就先冲 MCP。MCP 是放大器，不是补救手段——基础（CLAUDE.md / hooks / LSP）没稳之前先做 MCP，等于在沙地上叠塔。

7. Subagents：把"探索"和"编辑"切开

• 是什么：一个独立的 Claude 实例，有自己独立的 context window，接到子任务后干完只把最终结果回传给父 agent。
• 为什么关键：在同一个 session 里又探索又改代码，会让 context 被"扫码 + 思考 + 改动"三件事同时占用，效率和稳定性都受影响。原文给的范式是：先派一个只读 subagent 扫子系统并把发现写到文件里，再让主 agent 读完那份文件统一改。
• 别踩的坑：把它当线程池滥用——这是委派能力，不是"可配置的扩展点"，只在确实需要拆分上下文时用。

关键判断：七个扩展点的真正区别是加载时机——CLAUDE.md 是"每次必加载"，skills 是"按需触发"，subagents 是"显式调用"。把任何一个用错了它的加载时机，都会得到反向效果。

三、三大配置模式：从代码可导航到组织可落地

模式 1 · 让代码库在规模下仍然可导航

这一层处理的是最朴素的痛点：代码库太大，Claude 看一眼就被信息淹没。

原文怎么说：

Too much context loaded into every session degrades performance, while too little context leaves Claude to navigate blind.

为什么有效：Agentic search 的代价是依赖初始 context。这层做的所有事情都在围绕同一件事——为模型收窄视野。

落地清单：

• CLAUDE.md 分层：根目录写大局观（pointers + critical gotchas），子目录写局部约定，其它一切就是噪音。
• 在子目录初始化 Claude Code：“Claude works best when it’s scoped to the part of the codebase that’s actually relevant to the task”。在 monorepo 里这一步反直觉——很多工具假设要在仓库根上跑——但 Claude 会自动向上遍历，沿途加载所有 CLAUDE.md，根级上下文不会丢。
• test/lint 命令按子目录绑定：服务化代码库里这件事容易；编译型语言、跨目录强依赖的 monorepo 会更难，需要项目级的构建配置。
• .ignore 文件 + permissions.deny：在 .claude/settings.json 里把生成代码、构建产物、第三方代码统统排除——这份配置版本化，所有人共享同一份降噪规则。例外情况（如开发 code generator 的人需要看那些目录）走 local settings 覆盖。
• codebase map：当目录结构本身说不清架构时，在仓库根写一份轻量 markdown 列出顶层目录与一行说明。有几百个顶层目录的代码库走分层方式：根目录文件只写最高一层，下一级写在子目录的 CLAUDE.md 里。
• 跑 LSP 让 grep 升级成按符号搜：见前一节。

模式 2 · 跟随模型迭代主动维护 CLAUDE.md

这一层处理的是时间维度的损耗：曾经有用的指令，会在新模型下变成束缚。

原文给了两个非常具体的反例：

• 旧 CLAUDE.md 里"每次重构只改一个文件“的指令——这条曾经帮老模型保持专注，但会阻止新模型做协调式跨文件编辑，而新模型本来很擅长这件事。
• Perforce 仓库里那个拦截写操作以强制 p4 edit 的 hook——它在某次 Claude Code 加上 native Perforce mode 之后就完全冗余了，但许多团队仍然留着它。

关键判断：Anthropic 给的节奏是 “a meaningful configuration review every three to six months”——3 到 6 个月做一次有意义的配置审查，并在每个模型大版本发布之后再补一次。这是反直觉的：模型在变强，旧配置在贬值，不主动减负就是在主动降级。

很多团队会把 CLAUDE.md 当一份"只增不删"的项目说明书，这是规模化阶段最常见的隐形负债。配置审查不是 nice-to-have，是定期还债。

模式 3 · 给 Claude Code 指定专人/团队负责

这一层处理的是组织传播问题：技术配置再好，没有人统筹也会碎片化。

原文的两个组织样本很值得看：

1. 一家公司：两位工程师在工具上线前先搭了一套 plugins + MCPs，首日即可用。
2. 另一家公司：一支专注管理 AI 编码工具的团队，在工具铺开之前基础设施就已经就位。

归属一般在 developer experience / developer productivity 团队下面。原文还点出了一个正在出现的新岗位——Agent Manager：

A hybrid PM/engineer function dedicated to managing the Claude Code ecosystem.

这个 PM/工程混合岗的职责是管 Claude Code 这个生态本身，不是用它写代码——这是 AI 工具规模化以后第一个原生衍生岗位，值得各家工程效能团队提前看一眼。

最小可行版本叫 DRI（Directly Responsible Individual）：一个人直接拥有 Claude Code 配置、settings、permissions policy、plugin marketplace、CLAUDE.md 规范的决策权。

关键判断：自下而上的采纳能制造热情，但没有中心化所有权就会碎片化。在受监管行业（金融、医疗、政府）必须更早做治理：在工具进入工程组织之前就把工程 / 信息安全 / 治理三方拉进跨职能工作组，一起定义"哪些 skills/plugins 可用、AI 生成代码走什么 review 流程”。先小范围放开，再逐步扩展。

四、十五条反模式，逐句点破

下面这份清单从原文里逐条提取，按"踩中代价"从高到低排，方便对照自查。

1. 把 RAG 索引返回的过时函数当成"工具不准"——不是工具不准，是索引天然落后。
2. 只盯模型 benchmark 选工具，忽视 harness——harness 的影响超过模型本身。
3. 把可复用专长塞进 CLAUDE.md——它该是一个 skill。
4. 用提示词去做本该自动化的事——该是 hook。
5. 把所有内容堆进 CLAUDE.md，让它变成项目百科——会拖累每个 session 的性能。
6. 让好的配置一直停在"两个工程师机器上"——它该被打成 plugin 分发。
7. 默认 LSP 自动启用——它不会，需要显式装。
8. 基础（CLAUDE.md / hooks / LSP）还没稳就先冲 MCP——MCP 是放大器，不是补救。
9. 在同一个 session 里又探索又编辑——该用 subagent 拆分。
10. 在 monorepo 根目录初始化 Claude Code——该在子目录初始化。
11. 对单个服务的改动跑全套测试——会超时并烧 context。
12. 让旧 CLAUDE.md 的过时规则限制新模型（如"每次只改一个文件"）。
13. 保留已被原生支持取代的 hooks（如 Perforce 已支持 native mode 后还留着 p4 edit 拦截）。
14. 完全自下而上推广，没有中心化所有权——会迅速碎片化。
15. 在受监管环境跳过早期治理与跨职能工作组——后期补做代价倍增。

五、起步路线图：10 步从"个人能用"到"组织能规模化"

把上面所有的内容浓缩成一张落地图，以及一段清单。前 5 步是"为模型清场"，6–7 步是"复用沉淀"，8–10 步是"组织复制"——绝大部分团队走着走着掉链子，都是因为跳过了清场阶段直接做集成。

如果你的团队规模不大，可以把 8–9 合并、10 步浓缩为一个 DRI 角色；但顺序不能跳——尤其是 1–5 步，是给后面所有事情打底。

六、Claude Code 不是为所有代码库设计的

原文最后留了一个很坦诚的适用边界，值得在落地决策前认真看一眼：

Claude Code 的内置假设是：

• 工程师是代码库的主要贡献者
• 仓库用 Git
• 代码遵循标准目录结构

下面这些场景需要额外配置或并不在当前最佳实践覆盖范围：

• 含有大量二进制资产的游戏引擎仓库
• 用非传统版本控制系统（Perforce 之类，虽然已加 native 模式但仍有约束；或更小众的）
• 非工程师也在贡献代码的代码库
• 几十万级别文件夹、上百万级别文件的超巨代码库

不是说这些场景不能用，是默认配置不能直接套。Anthropic 自己也明确说，会在系列后续文章里专门讲。

七、三句话带走的判断

如果你只能记三句话，建议是这三句：

1. 决定 Claude Code 在大代码库里能跑多远的，不是模型，是 harness——CLAUDE.md / Hooks / Skills / Plugins / LSP / MCP / Subagents 这一整层；评估工具时把眼光从"模型分数"挪到"扩展层"上。
2. 大代码库里最重要的动作不是"加 context"，而是"为模型收窄视野"——子目录初始化、分层 CLAUDE.md、.ignore、LSP 按符号搜，所有这些都在给同一件事服务。
3. AI 编码工具的规模化是一个组织问题——一个 DRI 或一个 Agent Manager 的有无，比技术配置更能决定 1000 个工程师 6 个月之后的状态。3–6 个月一次的配置审查不是 nice-to-have，是给配置定期还债。

原文链接：How Claude Code works in large codebases: Best practices and where to start · Anthropic · 2026-05-14

本文图片均为重新设计的 SVG 信息图，遵循本站博客配图 SVG 设计规范。

× 爱折腾的工程师

真诚赞赏，手留余香

2元 5元 10元 50元 100元 任意金额

2元

使用微信扫描二维码完成支付

• ← Previous Post
• Next Post →