Anthropic 工程团队总结的规模化部署经验：Claude Code 为什么选择主动搜索而非 RAG 索引，为什么 Harness 比模型本身更重要，以及 CLAUDE.md、Hooks、Skills、LSP、MCP、Subagents 七层如何协同工作。
演绎自 《How Claude Code works in large codebases: Best practices and where to start》，原作者：Anthropic
这篇文章是 Anthropic 工程团队发布的系列文章「Claude Code at Scale」的第一篇，记录了他们在数百万行单仓库、跨几十个微服务的分布式架构、历时数十年的遗留系统中部署 Claude Code 的实践经验。
原文面向的是企业用户，但其中的判断对任何规模的代码库都有参考价值——哪怕你只是在维护一个个人项目。
本文是对原文的演绎，不是逐段翻译。做法是保留原文的核心论断和结构，用自己的语言重新表达，并在与本站直接相关的地方插入批注。对于原文中较为平铺的内容，会适当收拢或重新组织，力求读来更紧凑。
Claude Code 导航代码库的方式，和一位软件工程师的工作方式相同：遍历文件系统，读文件，用 grep 精确定位，跨文件追踪引用。它在开发者本地运行，不需要构建、维护或上传索引。
这一点值得停下来想一下。
大多数 AI 编程工具依赖 RAG（Chen 注：RAG（Retrieval-Augmented Generation）的常见实现是把整个代码库向量化，查询时检索相关片段再喂给模型。问题在于向量化管道会有延迟——在活跃的工程团队里，索引永远都在追赶最新代码。）：先把整个代码库向量化，查询时检索相关片段。这在小规模、变化慢的代码库里还好，但到了真实的工程环境，问题就暴露了：工程师合并了 PR，索引还没更新；两周前被重命名的函数，检索仍然返回旧名字；上个迭代删掉的模块，今天查出来还像是存在的。
Claude Code 的「主动搜索」（Agentic Search）绕开了这个问题。没有索引，每个开发者实例直接操作最新代码。代价是：如果 Claude 不知道从哪开始找，效率会很低。
这是一个微妙但重要的权衡。如果让 Claude 在十亿行代码库里搜索一个模糊的模式，它会在耗尽上下文窗口之前一无所获。所以，代码库的「可导航性」——它能多快告诉 Claude「去这里找」——直接决定了 Claude 的有效性。
这是原文最核心的论断，也最容易被忽视。
团队在评估 AI 编程工具时，通常盯着模型的 benchmark：在 SWE-bench 上是多少分，能不能一次性完成某个测试任务。但在真实部署里，围绕模型构建的生态系统——Harness——比模型本身更能决定最终效果。
Harness 由五个扩展点组成，加上 LSP 集成和 Subagents 两个能力，共同决定了 Claude 能不能在你的代码库里真正工作。
CLAUDE.md（Chen 注：CLAUDE.md 是 Claude Code 每次启动时自动读取的上下文文件。根目录的 CLAUDE.md 提供全局视角，子目录的 CLAUDE.md 提供局部约定。两者叠加加载，越深的目录越晚加载、优先级越高。） 是起点，不是终点。它告诉 Claude「这个代码库是怎么工作的」，让 Claude 在开始任何任务之前都有足够的上下文。
关键在于保持精简和分层。根目录的 CLAUDE.md 只放关键约定和跳转指针，具体细节交给子目录各自的 CLAUDE.md 文件。把所有信息都堆在根目录，反而会把噪音带进每一个任务。
本站的配置（Chen 注：本站的 CLAUDE.md 只有一行：`@AGENTS.md`。AGENTS.md 里的规则是「这不是你认识的 Next.js，有 breaking changes，写代码前先读 文档」。这是一个极简但有效的设计：CLAUDE.md 负责引用，AGENTS.md 负责内容，分工清晰，更新互不干扰。）印证了这一点：CLAUDE.md 做的唯一一件事，就是把 Claude 指向真正有信息的地方。
大多数人把 Hooks 理解为「防止 Claude 犯错的检查脚本」。Anthropic 团队的观察是，它更有价值的用途是持续改进。
stop hook：在会话结束时自动反思本次任务，提议更新 CLAUDE.md——趁上下文还新鲜，而不是等几天后才想起来start hook：会话开始时按开发者当前的工作目录动态加载上下文，让每个工程师自动得到和其所在模块匹配的配置Lint 和格式化这类确定性检查，通过 Hooks 强制执行，比依赖 Claude 记住指令更可靠。（Chen 注：确定性规则用 Hooks，不确定性判断交给模型——这条原则在很多 AI 工程实践里都成立。让 LLM 记住「每次都要跑 ESLint」是在浪费上下文；让 hook 直接跑，既节省 token 也更稳。）
在有几十种任务类型的大型代码库里，不可能把所有专业知识都塞进 CLAUDE.md。Skills 解决的是这个问题：把特定领域的工作流和知识打包，只在任务需要时加载。
安全审计的 skill 只在做漏洞排查时出现。文档更新的 skill 只在代码发生变化、需要同步文档时出现。Skills 还可以绑定到特定路径——支付服务的部署 skill 只在支付目录下自动激活，不会污染其他模块的会话。
本站的 /annotate skill（Chen 注：本站有一个 `/annotate` skill，专门在 MDX 文件里添加 `<Revision>` 批注。它包含批注组件的三种变体说明和操作步骤，只在需要写批注时调用——正是「按需加载的专业知识」的具体体现。） 是一个典型案例：把「如何给 MDX 文件添加批注组件」这件事封装起来，不需要每次在 CLAUDE.md 里重复说明。
一个好的 Harness 配置最大的浪费，是把它锁在少数人手里。Plugin 把 skills、hooks、MCP 配置打包成可安装的单元，新工程师入职第一天安装，立刻拥有和资深成员相同的能力和上下文。
Anthropic 见过的一个案例：某大型零售商把内部分析平台连接到 Claude Code 做成 plugin，在全面推广前先分发给业务分析师团队，让他们不用离开工作流就能拉取数据。
LSP（Chen 注：Language Server Protocol。IDE 里的「跳转定义」「查找所有引用」，背后就是 LSP。Claude Code 可以接入已有的 LSP 服务器，让 Claude 按符号而非字符串搜索代码。） 解决的是导航精度问题。如果 Claude 靠 grep 搜索一个常见函数名，在大型代码库里会返回几千条结果，然后花大量上下文一个个打开文件判断哪个才是目标。LSP 直接返回指向同一个符号的引用，过滤在读任何文件之前就完成了。
对 C、C++、Java 这类静态类型语言，LSP 集成是效果提升最显著的单项投资。Anthropic 提到一个企业案例：在 C/C++ 代码库全面推广 Claude Code 之前，先做了全组织级的 LSP 集成，正是为了让导航在规模下可靠。
MCP servers 负责把 Claude 和内部系统连起来：文档系统、工单平台、监控数据、内部 API。最成熟的团队会构建结构化搜索的 MCP server，让 Claude 可以直接调用而不是用 grep 盲搜。
Subagents（Chen 注：Subagent 是独立的 Claude 实例，有自己的上下文窗口。它完成任务、返回结果，主会话只看到结果而不需要承担探索过程的上下文消耗。） 是 Harness 建好之后的最后一层。一种常见模式：先用只读 subagent 绘制某个子系统的全局图，把结果写到文件；主 agent 读取这份地图再做编辑。探索和修改分开，防止探索过程把主会话的上下文窗口消耗殆尽。
Harness 搭好之后，Anthropic 观察到三种在大型代码库中反复出现的配置模式。
这是基础工作，也是收益最高的投资：
CLAUDE.md 精简分层。 根目录文件只放关键指针，细节下沉到子目录。堆在根目录的信息越多，每次会话被稀释得越厉害。
从子目录初始化，而非从根目录。 在单仓库里，把 Claude 限定在任务真正相关的那部分代码，而不是让它面对整个仓库。Claude 会自动向上遍历目录树加载所有 CLAUDE.md，不会丢失根目录的上下文。
每个子目录独立的测试和 lint 命令。 全量跑测试套件会超时，还会把不相关的输出堆满上下文。子目录级别的 CLAUDE.md 里指定局部命令，在服务化的代码库里效果尤其显著。
用 .ignore 文件排除生成物、构建产物、第三方代码。 把 permissions.deny 规则提交到 .claude/settings.json，版本化管理，团队所有人自动获得同样的过滤，不需要每人单独配置。
构建代码库地图。 对于目录结构不够自说明的代码库，在根目录放一个 Markdown 文件，列出每个顶层目录一句话说明里面是什么——给 Claude 一个目录，让它在打开任何文件之前先能定位。
模型在更新，为旧模型写的规则可能在新模型上适得其反。一条曾经有效的指令「每次重构只修改一个文件」，在更新的模型里可能阻碍它做完全合理的跨文件协调修改。
Anthropic 建议：每三到六个月做一次配置审查。在重大模型发布后、效果感觉停滞时，提前做。（Chen 注：这对本站同样适用。AGENTS.md 里关于 Next.js 的警告，是当时版本迭代时写下的——随着 Claude 训练数据更新，这条规则的必要性需要定期重新评估。）
技术配置之外，Anthropic 观察到推广最顺利的组织有一个共同特征：在广泛铺开之前，有人提前把基础设施建好。
有的公司是两三个工程师在推广前搭好了一套 plugins 和 MCP；有的公司专门设了一个团队负责 AI 编程工具的基础设施建设。新工程师第一次接触 Claude Code 就是生产力的状态，而不是「先配置半天」的挫败感——这直接决定了后续的自发传播速度。
Anthropic 提到了一个新兴角色：Agent Manager。一个 PM/工程师混合的职能，负责管理 Claude Code 生态：配置、权限策略、plugin 市集、CLAUDE.md 规范的维护。对于没有专职团队的组织，最低限度是一个 DRI（直接责任人）：有权做配置决策，也有责任让配置保持更新。
自下而上的采用能产生热情，但没有人归拢，会碎片化成各自为政的局面。有效的知识传播需要有人做标准制定和布道的工作。
原文面向的「大型代码库」包含很宽的范围：百万行单仓库、几十年积累的遗留系统、跨几十个 repo 的微服务群。但文中的配置模式，本质上是在解决一个共同问题：如何让 Claude 知道该去哪里看、该怎么做。
这个问题和代码库大小无关，只和「代码库是否被配置得可被导航」有关。一个五十个文件的个人项目，如果 CLAUDE.md 写得好、测试命令配好了、不相关的生成物排除了，Claude 的工作效果不会比一个乱成一团的百万行项目差。
Harness 的核心思路可以归结为一句话：把「如何在这个项目里工作」的知识，从人脑转移到可以被 Claude 读取的系统里。这件事做好了，模型的能力才能真正释放出来。