Claude Code 在大型代码库里怎么干活：最佳实践和起步路径

原文链接：https://claude.com/blog/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 的 AI 编码工具的做法是把整个代码库做嵌入，查询时检索相关片段。在大规模场景下，这类系统会出问题，因为嵌入流水线跟不上工程团队的节奏。等开发者查询索引时，它反映的还是几周前、几天前甚至几小时前的代码库状态。检索结果会返回一个团队两周前已经重命名的函数，或者引用上一个 sprint 里已经删掉的模块，而且没有任何提示告诉你这些已经过期了。

Agent 式搜索（agentic search）避开了这些失败模式。没有嵌入流水线，也没有需要维护的中心化索引，上千名工程师提交新代码时也不存在同步问题。每个开发者的实例都直接基于实时代码库工作。

但这种方式有个权衡：它最理想的前提是 Claude 有足够的起始上下文，知道该去哪里找。这意味着 Claude 导航质量的好坏，取决于代码库被设置得有多好，也就是有没有用 CLAUDE.md 文件和 Skills 来分层叠加上下文。如果你让它在一个十亿行的代码库里找出某个模糊模式的所有实例，工作还没开始就会撞上上下文窗口上限。在代码库设置上投入的团队，效果会更好。

模型之外，harness 同样重要

关于 Claude Code 一个最常见的误解是：它的能力完全由所用模型决定。团队盯着模型的 benchmark 和它在测试任务上的表现。但实际中，围绕模型构建的生态（即 harness）比模型本身更能决定 Claude Code 的表现。

harness 由五个扩展点构成，分别是 CLAUDE.md 文件、hooks、Skills、plugins、MCP 服务器，各自承担不同功能。团队构建它们的顺序很重要，因为每一层都建立在前一层之上。另外还有 LSP 集成和 subagent 这两项能力补全了整套设置。下面解释这些组件和能力各自的作用：

CLAUDE.md 文件排在最前。这是 Claude 在每次会话开始时自动读取的上下文文件：根目录的文件给全局视图，子目录的文件给局部约定。它们给 Claude 提供做好任何事都需要的代码库知识。因为它们无论什么任务都会在每次会话加载，把它们聚焦在广泛适用的内容上，能避免拖累性能。

Hooks 让设置能自我改进。大多数团队把 hooks 想成阻止 Claude 做错事的脚本，但它们更有价值的作用是持续改进。一个 stop hook 可以在上下文还新鲜时回顾会话里发生了什么，并提议对 CLAUDE.md 的更新；一个 start hook 可以动态加载团队特定的上下文，让每个开发者无需手动配置就能拿到适合自己模块的设置。对于 lint 和格式化这类自动化检查，hooks 以确定性的方式执行规则，结果比依赖 Claude 记住某条指令更一致。

Skills 让合适的专业能力按需可用，又不会撑爆每次会话。 在有几十种任务类型的大型代码库里，不是所有专业能力都需要出现在每次会话中。Skills 通过渐进式披露解决这个问题，把那些本会争夺上下文空间的专门工作流和领域知识转移出去，只在任务需要时才加载。比如，一个安全审查 Skill 在 Claude 评估代码漏洞时加载，一个文档处理 Skill 在代码改动需要更新文档时加载。

Skills 还可以绑定到特定路径，只在代码库的相关部分激活。一个负责支付服务的团队可以把他们的部署 Skill 绑定到那个目录，这样当有人在 monorepo 的其他地方工作时它永远不会自动加载。

Plugins 把有效的东西分发出去。 大型代码库的一个挑战是，好的 设置可能停留在口口相传。一个 plugin 把 Skills、hooks 和 MCP 配置打包成一个可安装的包，所以当新工程师在第一天安装这个 plugin 时，就立刻拥有和已经用过一段时间的人相同的上下文和能力。plugin 更新可以通过托管市场在组织内分发。

比如，我们合作的一家大型零售企业构建了一个 Skill，把 Claude 接到他们内部的分析平台上，业务分析师不用离开工作流就能拉取业绩数据。他们在向业务部门全面推广之前，就先把它作为 plugin 分发下去。

语言服务器协议（LSP）集成让 Claude 拥有和开发者在 IDE 里一样的导航能力。 大多数大型代码库的 IDE 里都已经在跑一个 LSP，驱动着「跳转到定义」和「查找所有引用」。把这些暴露给 Claude，就给了它符号级别的精度：它可以沿着一次函数调用追到定义、跨文件追踪引用、还能区分不同语言里同名函数。没有它，Claude 只能在文本上做模式匹配，可能落到错误的符号上。我们合作过的一家企业软件公司在 Claude Code 推广之前就在全公司部署了 LSP 集成，专门为了让 C 和 C++ 在大规模下的导航可靠。对多语言代码库来说，这是回报最高的投入之一。

MCP 服务器把一切延伸出去。 MCP 服务器是 Claude 连接内部工具、数据源和它本来够不到的 API 的方式。最成熟的团队构建了 MCP 服务器，把结构化搜索暴露成一个 Claude 可以直接调用的工具。还有的把 Claude 接到内部文档、工单系统或分析平台。

Subagents 把探索和编辑分开。 subagent 是一个有自己独立上下文窗口的 Claude 实例，它接下一个任务、做完工作、只把最终结果返回给父 Agent。一旦 harness 搭好，有些团队会拉起一个只读 subagent 去摸清某个子系统并把发现写到文件里，再让主 Agent 在掌握全貌后做编辑。

Claude Code 的扩展层一览。

下表总结每个组件做什么、何时加载，以及我们看到的每个组件最常见的误区：

*LSP 通过 plugin 层访问。Subagents 是一种委派能力，而不是一个被配置的扩展点。

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

怎么给大型代码库配置 Claude Code，很大程度上取决于代码库本身的结构。尽管如此，在我们观察到的部署里有三类模式反复出现。

让代码库在大规模下可导航

Claude 在大型代码库里能帮上多少忙，受限于它找到正确上下文的能力。把太多上下文塞进每次会话会拖累性能，上下文太少又让 Claude 盲目导航。最有效的部署会先期投入，让代码库对 Claude 可读。有几个模式反复出现：

• 保持 CLAUDE.md 文件精简且分层。 Claude 在代码库里移动时会叠加式地加载它们：根目录文件给全局视图，子目录文件给局部约定。根目录文件应该只放指针和关键坑点，其他东西都会慢慢变成噪音。
• 在子目录里初始化，而不是在仓库根目录。 Claude 在被限定到任务真正相关的代码库部分时表现最好。在 monorepo 里这有点反直觉，因为工具通常假设根目录访问，但 Claude 会自动沿目录树向上走，加载它一路上找到的每个 CLAUDE.md 文件，所以根目录级的上下文永远不会丢。
• 按子目录限定测试和 lint 命令。 Claude 只改了一个服务却跑完整测试套件，会导致超时还把上下文浪费在无关输出上。子目录级的 CLAUDE.md 文件应该指定适用于代码库那部分的命令。这对每个目录有自己测试和构建命令的服务型代码库很有效。在跨目录依赖很深的编译型语言 monorepo 里，按子目录限定更难做到，可能需要项目特定的构建配置。
• 用 .ignore 文件排除生成文件、构建产物和第三方代码。 在 .claude/settings.json 里提交 permissions.deny 规则意味着这些排除是版本控制的，团队里每个开发者都拿到同样的降噪效果而无需自己配置。在某些代码库里，生成文件本身就是开发工作的对象。做代码生成器的开发者可以在自己的本地设置里覆盖项目级排除，而不影响团队其他人。
• 当目录结构本身不够用时，构建代码库地图。 对于代码没有收纳在常规目录结构里的组织，在仓库根目录放一个轻量 markdown 文件，列出每个顶层文件夹并用一句话说明里面是什么，就给了 Claude 一份目录表，它可以在打开文件前先扫一遍。对于有几百个顶层文件夹的代码库，这最好做成分层：根目录文件只描述最高层结构，子目录 CLAUDE.md 文件提供下一层细节，随着 Claude 在目录树里移动按需加载。对简单情况，@-mention Claude 应该参考的具体文件或目录也能起到同样作用。
• 跑 LSP 服务器，让 Claude 按符号而不是按字符串搜索。 在大型代码库里 grep 一个常见函数名会返回成千上万条匹配，Claude 要打开文件逐个判断哪个重要，烧掉大量上下文。LSP 只返回指向同一符号的引用，过滤在 Claude 读任何东西之前就完成了。设置它需要为你的语言安装一个代码智能 plugin 和对应的语言服务器二进制文件；Claude Code 文档覆盖了可用 plugin 和排错方法。

一个提醒：有些边缘情况下连分层 CLAUDE.md 的方法都会失效，比如有几十万文件夹、几百万文件的代码库，或者用非 Git 版本控制的遗留系统。我们会在本系列后续文章里讲这些挑战。关于遗留系统，可以看 AI 是如何打破 COBOL 现代化的成本壁垒的。

随模型智能演进而持续维护 CLAUDE.md 文件

随着模型演进，为当前模型写的指令可能会跟未来的模型对着干。曾经引导 Claude 走过它本不擅长模式的 CLAUDE.md 文件，在下一个模型发布时可能变得多余，甚至成为束缚。比如，一条告诉 Claude 把每次重构都拆成单文件改动的 CLAUDE.md 规则，可能帮过早期模型保持正轨，却会阻止新模型做它已经能胜任的跨文件协同编辑。

那些为弥补模型特定局限而构建的 Skills 和 hooks，无论局限在模型推理还是 Claude Code 自身工具里，一旦这些局限不复存在就会变成开销。比如，一个拦截文件写入以在 Perforce 代码库里强制 p4 edit 的 hook，在 Claude Code 原生支持 Perforce 模式后就变得多余了。

团队应该预期每三到六个月做一次有意义的配置审查，而且在主要模型发布后感觉性能停滞时也值得做一次。

为 Claude Code 的管理和采用明确归属

光靠技术配置推动不了采用。做对的组织也在组织层面投入。

推广最快的情况是，在广泛开放访问之前就有了专门的基础设施投入。一个小团队，有时甚至只有一个人，先把工具接好，让 Claude 在开发者第一次接触时就已经贴合他们的工作流。在一家公司，几个工程师构建了一整套 plugin 和 MCP，第一天就可用。在另一家，一整个专注于管理 AI 编码工具的团队在推广开始前就把基础设施铺好了。在这两种情况下，开发者的第一次体验是高效的而不是令人沮丧的，采用就从这里扩散开。

今天做这些工作的团队通常挂在开发者体验或开发者生产力下面，这个职能一般负责新人入职和开发工具建设。在几个组织里出现的一个新角色是 Agent manager：一个兼顾 PM 和工程的混合职能，专门管理 Claude Code 生态。对于没有专职团队的组织，最小可行版本是一个 DRI（直接负责人）：一个人拥有 Claude Code 配置的所有权，有权对设置、权限策略、plugin 市场和 CLAUDE.md 约定拍板，并负责让它们保持最新。

自下而上的采用会制造热情，但没有人集中沉淀有效做法就会碎片化。你需要一个个人或团队来组装并推广正确的 Claude Code 约定（比如标准化的 CLAUDE.md 层级，或一套精选的 Skills 和 plugins）。没有这层工作，知识会停留在部落化，采用会停滞。

在大型组织里，尤其是受监管行业，治理问题会很早冒出来：谁控制哪些 Skills 和 plugins 可用、怎么防止上千名工程师各自重复造同一个轮子、怎么确保 AI 生成的代码和人生成的代码走同样的审查流程？要尽早应对，我们建议从一个明确的已批准 Skills 集合、必需的代码审查流程和有限的初始访问开始，随着信心建立再扩大。

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

把这些模式用到你的组织

Claude Code 是围绕常规软件工程环境设计的：工程师是代码库的主要贡献者，仓库用 Git，代码遵循标准目录结构。大多数大型代码库符合这个模子，但非传统设置需要额外的配置工作，比如带有大量二进制资源的游戏引擎、用非常规版本控制的环境，或者由非工程师贡献代码的代码库。我们的指导假设的是常规设置，我们描述的模式在很多客户那里都行之有效。任何剩余的复杂性都需要针对你的代码库、工具和组织做判断。Anthropic 的 Applied AI 团队正是在这里直接和工程团队合作，把这些模式翻译成你组织具体的需求。

从 Claude Code for Enterprise 开始。

致谢： 特别感谢 Anthropic Applied AI 团队的 Alon Krifcher、Charmaine Lee、Chris Concannon、Harsh Patel、Henrique Savelli、Jason Schwartz、Jonah Dueck 和 Kirby Kohlmorgen 分享他们大规模部署 Claude Code 的经验，也感谢 Zoox 的 Amit Navindgi 对本文的反馈。