Claude Code 如何在大型代码库中工作：最佳实践与起步指南｜Anthropic

本文编译自 Anthropic 官方博客《How Claude Code works in large codebases: Best practices and where to start》，在保留原文信息量和技术细节的前提下做了中文语序和排版优化。

Claude Code 已经在以下这些环境里跑在生产中：

• 数百万行代码的 monorepo
• 跨越数十年的 遗留系统
• 横跨数十个仓库的 分布式架构
• 拥有数千名开发者的 大型组织

这些环境带来了小型、简单代码库不会遇到的挑战——比如每个子目录都有不同的构建命令，或者遗留代码散落在没有共同根目录的多个文件夹里。

本文将梳理我们在大规模部署 Claude Code 的过程中观察到的、能带来成功落地的模式。

我们所说的「大型代码库」涵盖范围很广：

• 上百万行代码的 monorepo；
• 历经数十年沉淀的遗留系统；
• 分布在多个独立仓库中的几十个微服务；
• 或上述形式的任意组合。

这也包括那些通常不会和 AI 编码工具联系在一起的语言——C、C++、C#、Java、PHP。事实上，Claude Code 在这些语言上的表现往往比团队预期得更好，尤其是在近期几次模型发布之后。

虽然每个大型代码库的部署都会受到其版本控制方式、团队结构和历史约定的影响，但本文中的模式具有跨场景的通用性，对于正在评估是否引入 Claude Code 的团队来说，是一个不错的起点。

一、Claude Code 是如何在大型代码库中导航的

Claude Code 浏览代码库的方式，和一位工程师非常相似：

• 遍历文件系统
• 读取文件
• 用 grep 精准定位
• 跨文件追踪引用

它在开发者本地机器上运行，不需要构建、维护或上传任何代码库索引到服务器。

为什么不是 RAG？

基于 RAG 的 AI 编码工具，是把整个代码库 embedding，然后在查询时检索相关片段。在大规模场景中，这类系统经常会失败，原因在于：

Embedding 流水线跟不上活跃工程团队的迭代速度。

等开发者去查询索引时，索引反映的可能是几周、几天甚至几小时之前的代码库状态。检索可能会返回：

• 一个两周前已经被重命名的函数；
• 或者引用一个上个 Sprint 就已经被删除的模块；

而且没有任何提示告诉你这些已经过期。

智能体式搜索（Agentic Search）的优势与权衡

Agentic search 避开了这些失败模式：

• 不需要维护 embedding 流水线；
• 不需要随着上千名工程师不断提交新代码而维护一个中心化索引；
• 每个开发者的实例都基于实时的代码库工作。

但这种方式也有一个权衡：

它在 Claude 已经拥有足够起始上下文、知道该往哪里看的时候表现最好。

这意味着 Claude 的导航质量，取决于代码库本身的组织程度，以及通过 CLAUDE.md 文件和 Skills 一层层叠加的上下文。

如果你让它去一个十亿行规模的代码库中查找某种模糊的模式，那还没开始干活，上下文窗口就已经被打爆了。投入资源做好代码库的「可读化」设置的团队，结果会明显更好。

二、Harness 的重要性，丝毫不亚于模型本身

关于 Claude Code，最常见的一个误解是：

它的能力完全由所使用的模型决定。

很多团队会盯着模型的 benchmark 和它在测试任务上的表现。

但实际上，围绕模型构建的整套生态——也就是 harness（脚手架）——对 Claude Code 表现的影响，往往比模型本身更大。

Harness 由 五个扩展点 组成：

1. CLAUDE.md 文件
2. Hooks
3. Skills
4. Plugins
5. MCP Servers

它们各自承担不同的职责，构建顺序很重要——每一层都依赖前一层。

再加上两个额外能力：

• LSP 集成
• Subagents（子智能体）

下面分别说明：

1. CLAUDE.md 文件——最先要做的事

CLAUDE.md 是 Claude 在每次会话开始时自动读取的上下文文件：

• 根目录的 CLAUDE.md：提供整体视角；
• 子目录的 CLAUDE.md：提供局部约定。

它们为 Claude 提供完成工作所需的代码库知识。

由于它们会在每次会话中加载（无论当前任务是什么），所以应保持聚焦于「广泛适用」的内容，否则会拖累性能。

2. Hooks——让整套配置自我进化

Hooks 是在关键时刻自动运行的脚本。

大多数团队把 Hooks 理解为「防止 Claude 做错事的脚本」，但它更有价值的用法是持续改进：

• Stop hook：会话结束时反思本次发生了什么，趁记忆新鲜时提出 CLAUDE.md 更新建议；
• Start hook：动态加载团队特定的上下文，让每个开发者无需手动配置就能自动获得适合自己模块的设置；
• Linting / Formatting：用 hook 确定性地强制执行，远比让 Claude 「记得」某条指令更稳定。

3. Skills——按需出现的专家能力

Skills 让正确的专业能力按需可用，而不会让每一次会话都背负所有知识。

在一个任务类型繁多的大型代码库中，并不是所有专业能力都需要出现在每次会话中。Skills 通过 渐进式披露（progressive disclosure） 来解决这个问题：

• 把那些原本会争抢上下文空间的专业工作流和领域知识外置；
• 只在任务需要时才加载。

例如：

• 评估代码安全漏洞时，加载 安全审查 Skill；
• 代码变更需要更新文档时，加载 文档处理 Skill。

Skills 还可以绑定到特定路径，仅在代码库的相关部分激活：

拥有支付服务的团队可以把部署 Skill 绑定到那个目录，monorepo 中其他地方的工作就不会自动加载它。

4. Plugins——把「好东西」分发出去

大型代码库的一个挑战是：好的配置容易停留在小圈子里。

Plugins 把 Skills、Hooks、MCP 配置 打包成一个可安装的整体：

• 新工程师在第一天安装这个 plugin，就能立刻获得和资深用户一样的上下文与能力；
• 通过 managed marketplaces，Plugin 更新可以在组织范围内统一分发。

比如，我们合作的一家大型零售企业构建了一个 Skill，把 Claude 接入他们内部的分析平台，让业务分析师不离开工作流就能拉取业绩数据。在面向全体业务团队推广之前，他们以 plugin 的形式把它分发出去。

5. LSP（Language Server Protocol）集成——给 Claude 装上 IDE 的导航能力

大多数大型代码库的 IDE 里都已经跑着 LSP，背后驱动着 「跳转到定义」「查找所有引用」 这些功能。

把 LSP 暴露给 Claude，可以让它获得 符号级别的精度：

• 跟随一个函数调用跳到它的定义；
• 跨文件追踪引用；
• 区分不同语言中同名函数。

如果没有 LSP，Claude 只能在文本上做模式匹配，可能落到错误的符号上。

我们合作的一家企业软件公司，在 Claude Code 全员推广之前就提前部署了 LSP 集成，目的是让 C 和 C++ 的导航在大规模下保持可靠。

对多语言代码库来说，这是 投入产出比最高的一项投资之一。

6. MCP Servers——把外部世界接进来

MCP Servers 是 Claude 连接到内部工具、数据源和 API 的方式。

最成熟的团队会：

• 构建 MCP server，把结构化搜索暴露为 Claude 可直接调用的工具；
• 把 Claude 连接到内部文档、工单系统或分析平台。

7. Subagents——把「探索」和「编辑」分开

Subagent 是一个拥有自己独立上下文窗口的、隔离的 Claude 实例：

• 接受一个任务
• 完成工作
• 只把最终结果返回给父智能体

当 harness 搭好之后，一些团队会：

起一个 只读的 subagent 来梳理某个子系统并把发现写到文件里，然后让主智能体在拥有全局图景的前提下进行编辑。

各组件一览表

三、来自成功部署的三种配置模式

如何为大型代码库配置 Claude Code，很大程度上取决于代码库本身的结构。但我们观察到的部署中，有 三种模式 一致地出现。

模式 1：让代码库在规模下「可被导航」

Claude 在大型代码库中能否提供有效帮助，取决于它能否找到正确的上下文：

• 每次会话加载太多上下文，会拖垮性能；
• 加载太少，则等于让 Claude 盲走。

效果最好的部署，会在前期投入精力，让代码库对 Claude 来说是「可读」的。常见做法包括：

• 保持 CLAUDE.md 精简且分层：Claude 会在代码库中移动时逐层叠加地加载它们。根目录给大图景，子目录给局部约定。根文件应该只放指针和关键陷阱，其他内容会演变成噪音。
• 在子目录里初始化，而不是在仓库根目录：Claude 在被限定到任务真正相关的部分时表现最好。在 monorepo 中这听起来反直觉（因为工具链通常假设你站在根目录），但 Claude 会自动向上遍历目录树，加载沿途每一个 CLAUDE.md，所以根级上下文永远不会丢失。
• 测试和 lint 命令按子目录限定作用域：Claude 只改了某一个服务，却跑整套测试套件，结果就是超时 + 浪费上下文。CLAUDE.md 应在子目录级别指明属于这部分代码库的命令。
  • 这对面向服务的代码库很自然，因为每个目录都有自己的测试和构建命令；
  • 在跨目录依赖很深的编译型 monorepo 中较难实现，可能需要项目特定的构建配置。
• 用 .ignore 文件排除生成文件、构建产物和第三方代码：把 permissions.deny 规则提交到 .claude/settings.json 里，可以让排除规则受版本管理控制，每个开发者都获得相同的「降噪」，无需各自配置。
  • 在某些场景中，生成的文件本身就是开发对象。负责代码生成器的开发者可以在本地设置里覆盖项目级排除规则，而不影响团队其他成员。
• 当目录结构本身不能完成工作时，自己画一张「代码库地图」：对于代码没有按常规目录结构整理的组织，可以在仓库根目录放一个轻量级 markdown 文件，列出每个顶级文件夹和一句话描述。这给 Claude 一份目录索引，让它在打开文件之前先扫一眼。
  • 对于有数百个顶级文件夹的代码库，这种做法最好分层：根文件只描述最高级结构，子目录 CLAUDE.md 提供下一层级细节，按需加载。
  • 对简单情况，直接用 @ 提到 Claude 应该参考的具体文件或目录，也能起到同样作用。
• 运行 LSP 服务器，让 Claude 按符号搜索，而不是按字符串搜索：在大型代码库里 grep 一个常见函数名会返回几千个匹配，Claude 会消耗大量上下文来打开文件分辨哪些是真正想要的。LSP 只会返回指向同一符号的引用，过滤工作在 Claude 真正读取文件之前就完成了。
  • 配置方法：为你的语言安装一个 code intelligence plugin，以及对应的 language server 二进制文件。Claude Code 文档涵盖了可用的 plugin 和排错方式。

模式 2：随着模型能力进化，持续维护 CLAUDE.md

随着模型能力变化，为当前模型写的指令可能会拖累未来的模型。

• 一些原本帮助 Claude 跨越某些模式障碍的 CLAUDE.md 文件，可能在下一代模型发布后变得多余甚至是反向约束。

例如：

一条 CLAUDE.md 规则要求 Claude 把每次重构都拆成「单文件变更」，这在早期模型上有助于保持专注；但放在更新的模型上，会阻止它做本应轻松完成的跨文件协调编辑。

同样：

• 为了弥补特定模型限制（无论是推理上的还是 Claude Code 工具上的）而构建的 Skill 和 Hook，一旦限制不复存在，就成了多余负担。
• 比如：曾经有个 hook 拦截文件写入以强制执行 Perforce 代码库中的 p4 edit——在 Claude Code 加入原生 Perforce 模式后就变得多余。

建议：

• 每 3～6 个月 做一次有意义的配置评审；
• 在重大模型发布后，如果感觉性能进入瓶颈期，也值得做一次。

模式 3：为 Claude Code 的管理和推广指定责任人

仅靠技术配置，无法驱动真正的采用。部署成功的组织都在「组织层」上做了投入。

部署最快铺开的组织有一个共同特征：

在大规模开放访问之前，先有一个专门的基础设施投入。

通常是一个小团队，有时甚至只有一个人，把工具链布置好，让 Claude 第一次出现在开发者面前时就已经契合他们的工作流。

• 一家公司在开放访问前，由几位工程师构建了一整套 plugin 和 MCP，让开发者上线第一天就能用；
• 另一家公司则有一个专门管理 AI 编码工具的团队，提前完成基础设施搭建。

两种情形下，开发者的第一次体验都是有产出的，而不是挫败的——采用就这样自然扩散。

承担这项工作的团队，通常归属于哪里？

• 一般在 Developer Experience 或 Developer Productivity 团队，这通常也是负责新工程师入职和开发者工具建设的部门；
• 一个新兴角色正在多个组织中出现：Agent Manager——一种 PM/工程师混合职能，专门负责管理 Claude Code 生态。

对于没有专门团队的组织，最小可行版本 是：

一位 DRI（Directly Responsible Individual），负责 Claude Code 配置，拥有以下决策权：

- 设置项

- 权限策略

- Plugin marketplace

- CLAUDE.md 约定

同时负责让这些保持更新。

自下而上的采纳能激发热情，但没有人去做集中沉淀的话很容易碎片化。需要有个人或团队去：

• 组装并推广合适的 Claude Code 约定（例如标准化的 CLAUDE.md 层级，或一组精选的 Skills 和 Plugins）；
• 否则知识只会停留在小圈子，采纳会陷入停滞。

在大型组织——尤其是受监管行业——治理问题会很早出现：

• 谁来决定哪些 Skills 和 Plugins 可用？
• 如何防止几千名工程师各自重复造同一个轮子？
• 如何确保 AI 生成的代码经过与人类代码相同的审查流程？

为此，我们建议一开始就：

• 定义一组经过批准的 Skills；
• 强制必要的代码评审流程；
• 限定初始访问范围，随着信心建立逐步扩大。

我们观察到，最顺畅的部署来自那些很早就组建跨职能工作组的组织：把工程、信息安全、治理代表聚到一起，共同定义需求和制定推广路线图。

四、把这些模式应用到你的组织

Claude Code 是面向主流软件工程环境设计的：

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

大多数大型代码库都符合这个模式，但非常规设置会需要额外配置工作，例如：

• 含有大量二进制资源的游戏引擎；
• 使用非常规版本控制的环境；
• 由非工程师参与贡献代码的代码库。

本文的建议假设了一个常规设置，并且这些模式已经在多个客户身上验证过。剩下的复杂性，需要结合你自己的代码库、工具链和组织来判断。这正是 Anthropic 的 Applied AI 团队 与工程团队直接合作的地方——把这些模式转化为你们组织的具体方案。

了解更多：Claude Code for Enterprise。