Claude Code 如何在大型代码库中工作：最佳实践以及从哪里开始

本文翻译自 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（Retrieval-Augmented Generation，检索增强生成）的 AI 编程工具通常会为整个代码库生成嵌入，并在查询时检索相关片段。在大规模环境下，这类系统可能失效，因为嵌入流水线跟不上活跃工程团队的提交速度。等开发者查询索引时，索引反映的可能是数周、数天，甚至数小时前的代码库状态。检索结果可能返回一个团队两周前已经重命名的函数，或者引用上个迭代已经删除的模块，而且没有任何迹象表明这些结果已经过时。

智能体式搜索（agentic search）可以避开这些失效模式。它不需要随着成千上万名工程师不断提交新代码而维护嵌入流水线或集中式索引。每个开发者的实例都直接基于实时的本地代码库工作。

但这种方法也有取舍：只有当 Claude 拥有足够的起始上下文、知道该从哪里开始查找时，它的效果才最好。这意味着 Claude 的导航质量取决于代码库本身的准备程度，包括如何用 CLAUDE.md 文件和技能（skills）分层提供上下文。如果你要求它在十亿行代码库中查找某个模糊模式的所有实例，它可能在真正开始工作之前就碰到上下文窗口限制。愿意投入代码库准备工作的团队，会得到更好的结果。

运行框架与模型同样重要

关于 Claude Code，最常见的误解之一是认为它的能力完全由所使用的模型决定。团队往往关注模型基准测试，以及模型在测试任务上的表现。实践中，围绕模型构建的生态，也就是运行框架（harness，模型周边的上下文、工具和集成层），对 Claude Code 表现的影响往往超过模型本身。

这个运行框架由五类扩展点构成：CLAUDE.md 文件、hooks（钩子）、skills（技能）、plugins（插件）和 MCP servers（MCP 服务器）。它们各自承担不同功能。团队构建它们的顺序也很重要，因为每一层都会建立在前一层之上。另外还有两项能力补齐整体配置：LSP 集成和子智能体（subagents）。下面我们说明这些组件和能力分别做什么。

CLAUDE.md 文件应该最先建立。这些是 Claude 在每个会话开始时自动读取的上下文文件：根目录文件提供整体图景，子目录文件提供局部约定。它们为 Claude 提供完成任何任务所需的代码库知识。由于这些文件会在每个会话中加载，无论任务是什么，因此应只保留广泛适用的内容，避免它们拖慢性能。

Hooks 让配置具备自我改进能力。多数团队会把 hooks 理解为防止 Claude 做错事的脚本，但它们更有价值的用途是持续改进。stop hook 可以在一次会话结束时，趁上下文仍然新鲜，回顾发生了什么并提出 CLAUDE.md 更新建议。start hook 可以动态加载团队特定上下文，让每个开发者都能自动获得适合自己模块的配置，而不需要手动设置。对于 lint 和格式化等自动检查，hooks 能以确定性方式执行规则，比依赖 Claude 记住某条指令更稳定。

Skills 让正确的专业能力按需可用，而不会膨胀每个会话的上下文。在拥有数十种任务类型的大型代码库中，并非所有专业知识都需要出现在每个会话里。Skills 通过渐进披露解决这个问题，把特定工作流和领域知识从默认上下文中卸载出去，只在任务需要时加载。比如，安全审查技能会在 Claude 评估代码漏洞时加载，而文档处理技能会在代码变更后需要更新文档时加载。

Skills 还可以限定到特定路径，因此只会在代码库的相关部分激活。拥有支付服务的团队可以把部署技能绑定到对应目录，这样当其他人在 monorepo 的其他区域工作时，该技能就不会自动加载。

Plugins 用来分发已经验证有效的配置。大型代码库的一个挑战是，好的配置容易停留在小圈子经验中。插件可以把 skills、hooks 和 MCP 配置打包成一个可安装包。这样新工程师第一天安装插件时，就能立即获得已经在使用 Claude 的同事所拥有的上下文和能力。插件更新也可以通过托管市场在组织内分发。

例如，我们合作过的一家大型零售组织构建了一个技能，把 Claude 连接到他们的内部分析平台，使业务分析师可以在不离开工作流的情况下拉取绩效数据。他们在面向业务团队大规模推广前，先把这个能力作为插件分发。

语言服务器协议（Language Server Protocol，LSP）集成为 Claude 提供与开发者 IDE 相同的导航能力。多数大型代码库的 IDE 已经运行了 LSP，用于支持“跳转到定义”和“查找所有引用”。把这项能力暴露给 Claude，可以让它具备符号级精度：它可以沿着函数调用跳到定义，跨文件追踪引用，并区分不同语言中同名但不同含义的函数。没有 LSP 时，Claude 只能基于文本模式匹配，可能落到错误的符号上。我们合作过的一家企业软件公司，在 Claude Code 推广前就在全组织部署了 LSP 集成，专门用来保证 C 和 C++ 在规模化代码库中的导航可靠性。对于多语言代码库来说，这是最有价值的投入之一。

MCP 服务器扩展了所有能力。MCP 服务器是 Claude 连接内部工具、数据源和 API 的方式，这些资源原本是 Claude 无法访问的。最成熟的团队会构建 MCP 服务器，把结构化搜索作为 Claude 可以直接调用的工具暴露出来。其他团队则把 Claude 连接到内部文档、工单系统或分析平台。

Subagents 用来把探索和编辑拆开。子智能体是一个隔离的 Claude 实例，拥有自己的上下文窗口。它接收任务、完成工作，然后只把最终结果返回给父智能体。一旦运行框架就位，有些团队会启动一个只读子智能体来梳理某个子系统，并把发现写入文件，然后让主智能体在掌握完整图景后进行编辑。

Claude Code 的扩展层概览。下表总结了每个组件的作用、加载时机，以及我们最常见的误用：

*LSP 通过插件层访问。Subagents 是一种委派能力，而不是配置型扩展点。

成功部署中的三种配置模式

如何为大型代码库配置 Claude Code，在很大程度上取决于代码库结构。不过，在我们观察到的部署中，有三种模式反复出现。

让代码库在规模化环境中可导航

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 读取任何内容之前。设置这项能力需要为对应语言安装代码智能插件以及相应的语言服务器二进制文件；Claude Code 文档说明了可用插件和排错方法。

一个注意事项：在某些边界场景中，即使是分层 CLAUDE.md 方法也会失效。例如，代码库有数十万个文件夹和数百万个文件，或者遗留系统使用非 Git 版本控制。我们会在本系列后续文章中讨论这些挑战。

随着模型智能演进，主动维护 CLAUDE.md 文件

随着模型演进，为当前模型编写的指令可能会在未来模型上适得其反。过去帮助 Claude 处理困难模式的 CLAUDE.md 文件，在新模型发布后可能变得不必要，甚至限制模型能力。例如，一条 CLAUDE.md 规则要求 Claude 把每次重构拆成单文件变更，这可能曾经帮助早期模型保持方向，但会阻止更新模型执行它已经能够很好处理的跨文件协同编辑。

为弥补特定模型限制而构建的 skills 和 hooks，无论这些限制来自模型推理能力还是 Claude Code 自身工具能力，一旦限制不复存在，就会变成额外开销。例如，在 Perforce 代码库中拦截文件写入以强制执行 p4 edit 的 hook，在 Claude Code 加入原生 Perforce 模式后就变得多余。

团队应预期每三到六个月进行一次有意义的配置评审；此外，在重大模型发布之后，如果感觉性能进入平台期，也值得做一次评审。

为 Claude Code 管理和采用指定负责人

仅有技术配置并不能推动采用。做得好的组织也会投入组织层面的工作。

推广最快的团队，在开放大规模访问之前就已经有专门的基础设施投入。一个小团队，有时甚至只有一个人，会先把工具接好，让开发者第一次接触 Claude 时，它已经适配了他们的工作流。在一家公司，几名工程师构建了一套插件和 MCP，在第一天就可用。在另一家公司，一个完整团队专门负责管理 AI 编程工具，在推广开始前就把基础设施准备好。两种情况下，开发者的第一次体验都是高效的，而不是令人沮丧的；采用也因此扩散开来。

今天做这类工作的团队，通常隶属于开发者体验或开发者生产力职能。这通常也是负责新工程师入职和构建开发者工具的团队。在一些组织中，一个新兴角色是 agent manager（智能体管理者）：一种混合 PM / 工程师职能，专门管理 Claude Code 生态。对于没有专职团队的组织，最低可行版本是指定一名 DRI（Directly Responsible Individual，直接负责人）：这个人拥有 Claude Code 配置的所有权，有权决定设置、权限策略、插件市场和 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 为本文提供反馈。