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

最成功的 Claude Code 部署，在配置、工具和组织结构上都有一组清晰可辨的共同模式。本文是 大规模 Claude Code 新系列的一部分，该系列会介绍工程组织在企业级规模上使用 Claude Code 的最佳实践。

Claude Code 正在多种生产环境中运行：数百万行代码的 monorepo、延续数十年的遗留系统、跨数十个仓库的分布式架构，以及拥有数千名开发者的组织。这些环境会带来更小、更简单的代码库所没有的挑战，比如每个子目录的构建命令都不同，或者遗留代码分散在没有共享根目录的多个文件夹中。

本文介绍我们观察到的、能在大规模采用 Claude Code 时带来成功的模式。我们所说的“大型代码库”覆盖范围很广：数百万行代码的 monorepo、构建了数十年的遗留系统、分布在多个独立仓库中的数十个微服务，或这些情况的任意组合。它也包括运行在一些团队并不总是会联想到 AI 编码工具的语言上的代码库，例如 C、C++、C#、Java、PHP。（Claude Code 在这些场景中的表现通常比多数团队预期得更好，尤其是在最近的模型版本发布之后。）尽管每个大型代码库部署都会受到具体版本控制方式、团队结构和长期积累的约定影响，但本文中的模式能够跨环境泛化，也是团队考虑采用 Claude Code 时的良好起点。

Claude Code 如何导航大型代码库

Claude Code 导航代码库的方式和软件工程师类似：它会遍历文件系统、读取文件、使用 grep 精确查找需要的内容，并沿着引用关系在代码库中追踪。它在开发者本地机器上运行，不需要构建、维护代码库索引，也不需要把索引上传到服务器。

基于 RAG 的 AI 编码工具会嵌入整个代码库，并在查询时检索相关片段。在大规模环境下，这类系统可能会失败，因为嵌入流水线跟不上活跃工程团队的变化速度。等开发者查询索引时，索引反映的可能是几周、几天，甚至几小时前的旧代码库。检索结果可能返回团队两周前已经重命名的函数，或引用上个 sprint 已经删除的模块，却不会提示这些内容已经过时。

Agentic search 避免了这些失败模式。它不需要嵌入流水线，也不需要随着数千名工程师提交新代码而维护集中式索引。每个开发者实例都基于实时的代码库工作。

但这种方法也有取舍：它在 Claude 拥有足够起始上下文、知道该去哪里查找时效果最好。这意味着 Claude 的导航质量，会受到代码库设置质量的影响，例如是否通过 CLAUDE.md 文件和技能分层提供上下文。如果你让它在一个十亿行代码库中查找某种描述模糊的模式，还没真正开始工作，就会触及上下文窗口限制。愿意投入代码库设置的团队，会得到更好的结果。

Harness 和模型同样重要

关于 Claude Code 最常见的误解之一，是认为它的能力完全由所使用的模型决定。团队往往关注模型基准测试，以及它在测试任务上的表现。实践中，围绕模型构建的生态，也就是 harness，对 Claude Code 表现的影响往往比模型本身更大。

Harness 由五个扩展点构成：CLAUDE.md 文件、hooks、skills、plugins 和 MCP servers。每个扩展点承担不同功能。团队构建它们的顺序很重要，因为每一层都会建立在前一层之上。另外两个能力，LSP integrations 和 subagents，则补齐了整体设置。下面我们解释这些组件和能力分别做什么：

CLAUDE.md 文件应该首先建立。这些是 Claude 在每个会话开始时自动读取的上下文文件：根目录文件提供全局图景，子目录文件提供局部约定。它们为 Claude 提供做好任何事情所需的代码库知识。因为无论任务是什么，它们都会在每个会话中加载，所以保持内容聚焦在广泛适用的信息上，能避免它们拖慢性能。

Hooks 让设置能够自我改进。多数团队会把 hooks 理解为阻止 Claude 做错事的脚本，但更有价值的用法是持续改进。Stop hook 可以在会话结束时回顾发生了什么，并趁上下文仍然新鲜时提出 CLAUDE.md 更新建议。Start hook 可以动态加载团队特定上下文，让每位开发者无需手动配置，就能为自己的模块获得正确设置。对于 lint 和 format 这类自动化检查，hooks 能以确定性的方式执行规则，比依赖 Claude 记住某条指令更一致。

Skills 让正确的专业能力按需可用，而不会膨胀每个会话。 在一个拥有数十种任务类型的大型代码库中，并非所有专业知识都需要出现在每个会话里。Skills 通过 progressive disclosure 解决这个问题，把原本会争夺上下文空间的专门工作流和领域知识卸载出去，只在任务需要时加载。例如，当 Claude 评估代码漏洞时加载安全审查 skill；当代码变更后需要更新文档时加载文档处理 skill。

Skills 也可以限定到特定路径，因此只会在代码库的相关部分激活。拥有 payments service 的团队可以把自己的部署 skill 绑定到该目录，这样当有人在 monorepo 的其他位置工作时，它就不会自动加载。

Plugins 把有效做法分发出去。大型代码库的一个挑战是，好的设置可能停留在“部落知识”里。Plugin 会把 skills、hooks 和 MCP configurations 打包成一个可安装包，这样新工程师在第一天安装 plugin 后，就能立刻获得那些已经在使用 Claude 的同事所拥有的相同上下文和能力。Plugin 更新可以通过 managed marketplaces 在组织内分发。

例如，我们合作过的一家大型零售组织构建了一个 skill，用于把 Claude 连接到他们的内部分析平台，让业务分析师无需离开工作流就能拉取绩效数据。他们在面向业务部门广泛推出之前，将它作为 plugin 分发。

Language server protocol (LSP) integrations 让 Claude 拥有开发者在 IDE 中拥有的同等导航能力。 多数大型代码库的 IDE 中已经运行着 LSP，用来支持“跳转到定义”和“查找所有引用”。把这层能力暴露给 Claude，可以带来符号级精度：它可以沿着函数调用跳到定义，跨文件追踪引用，并区分不同语言中同名但不同的函数。没有 LSP 时，Claude 会基于文本做模式匹配，可能落到错误的符号上。我们合作过的一家企业软件公司在 Claude Code 推广之前，就在组织范围内部署了 LSP integrations，专门让 C 和 C++ 导航在大规模下变得可靠。对于多语言代码库，这是最有价值的投资之一。

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

Subagents 把探索和编辑拆开。Subagent 是一个隔离的 Claude 实例，拥有自己的上下文窗口；它接收任务、完成工作，并只把最终结果返回给 parent。Harness 就位后，一些团队会启动一个只读 subagent 来梳理子系统并把发现写入文件，然后让 main agent 在掌握全局图景后进行编辑。

Claude Code 扩展层概览。

下表总结了每个组件的作用、加载时机，以及我们在每个组件上最常见到的错误：

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

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

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

Claude 能在大型代码库中提供多少帮助，受限于它找到正确上下文的能力。每个会话加载太多上下文会降低性能，而上下文太少又会让 Claude 盲目导航。最有效的部署会前置投入，让代码库对 Claude 来说变得可读。以下几种模式反复出现：

保持 CLAUDE.md 文件精简且分层。 Claude 会在代码库中移动时以叠加方式加载它们：根目录文件负责全局图景，子目录文件负责本地约定。根目录文件应该只包含指针和关键坑点；其他内容都会逐渐变成噪音。
在子目录初始化，而不是在 repo root 初始化。 当 Claude 被限定在与任务真正相关的代码库部分时，效果最好。在 monorepo 中，这可能有点反直觉，因为工具链通常假设有 root access，但 Claude 会自动沿目录树向上查找并加载它找到的每个 CLAUDE.md 文件，所以根级上下文不会丢失。
按子目录限定测试和 lint 命令。 如果 Claude 只修改了一个服务，却运行完整测试套件，会导致超时，并把无关输出浪费到上下文里。子目录级 CLAUDE.md 文件应该指定适用于代码库该部分的命令。对于每个目录拥有独立测试和构建命令的服务化代码库，这种方式效果很好。在拥有深层跨目录依赖的编译型语言 monorepo 中，按子目录限定更难做到，可能需要项目特定的构建配置。
使用 .ignore 文件排除生成文件、构建产物和第三方代码。 在 .claude/settings.json 中提交 permissions.deny 规则，意味着排除项会纳入版本控制，因此团队中的每位开发者都能获得相同的降噪效果，而无需自己配置。在一些代码库中，生成文件本身就是开发工作的对象。处理代码生成器的开发者可以在本地设置中覆盖项目级排除项，而不会影响团队其他人。
当目录结构无法承担导航职责时，构建代码库地图。 对于代码没有集中在传统目录结构中的组织，可以在 repo root 放一个轻量 markdown 文件，列出每个顶层文件夹，并用一句话说明其中内容，让 Claude 在打开文件前先扫描目录表。对于拥有数百个顶层文件夹的代码库，最好采用分层方式：根文件只描述最高层结构，子目录 CLAUDE.md 文件按需提供下一层细节，随着 Claude 在目录树中移动而加载。对于更简单的情况，@-mention Claude 应该参考的具体文件或目录，也能实现相同目的。
运行 LSP servers，让 Claude 按符号搜索，而不是按字符串搜索。 在大型代码库中 grep 一个常见函数名会返回数千个匹配项，Claude 会消耗上下文去打开文件并判断哪些重要。LSP 只会返回指向同一符号的引用，因此过滤会在 Claude 读取任何内容之前发生。设置它需要安装适用于你的语言的 code intelligence plugin，以及相应的 language server binary；Claude Code 文档覆盖了可用 plugins 和故障排查。

一个注意事项：有些边缘情况中，即使层级化 CLAUDE.md 方法也会失效，例如拥有数十万个文件夹和数百万个文件的代码库，或使用非 git 版本控制的遗留系统。我们会在本系列后续文章中讨论它们的挑战。

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

随着模型演进，针对当前模型编写的指令可能会反过来阻碍未来模型。那些曾经帮助 Claude 处理其薄弱模式的 CLAUDE.md 文件，在新模型发布后可能变得不再必要，甚至成为主动约束。例如，一条要求 Claude 把每次重构拆成单文件变更的 CLAUDE.md 规则，可能帮助过早期模型保持方向，但会阻止更新的模型完成它已经能够很好处理的协调式跨文件编辑。

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

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

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

单靠技术配置无法推动采用。真正做对的组织，也投资了组织层面的工作。

传播最快的 rollout，都会在广泛开放访问之前投入专门基础设施。一个小团队，有时甚至只有一个人，会先把工具链接起来，让开发者第一次接触 Claude 时，它就已经适配开发工作流。在一家公司，几位工程师构建了一套 plugins 和 MCPs，并在第一天就可用。在另一家公司，一个专门管理 AI 编码工具的完整团队，在 rollout 开始前就把基础设施准备好了。两种情况下，开发者的第一次体验都是高效的，而不是令人沮丧的，采用也由此扩散。

如今承担这类工作的团队，往往位于 developer experience 或 developer productivity 之下，这通常也是负责新工程师 onboarding 和构建开发者工具的职能部门。在几个组织中正在出现一种新角色：agent manager。这是一个混合 PM/engineer 职能，专门管理 Claude Code 生态系统。对于没有专门团队的组织，最低可行版本是一个 DRI：由一个人负责 Claude Code 配置，拥有对 settings、permissions policy、plugin marketplace 和 CLAUDE.md 约定做决策的权力，并负责保持它们更新。

自下而上的采用会产生热情，但如果没有人集中整理有效做法，就会碎片化。你需要有个人或团队来组装并推广正确的 Claude Code 约定，例如标准化的 CLAUDE.md 层级，或一组精选 skills 和 plugins。没有这项工作，知识会停留在部落知识中，采用会进入平台期。

在大型组织中，尤其是受监管行业，治理问题会很早出现，例如：谁控制哪些 skills 和 plugins 可用？如何防止数千名工程师独立重复构建同一件东西？如何确保 AI 生成代码经过和人类生成代码相同的审查流程？为了及早处理这些问题，我们建议从一组定义明确的 approved skills、必需的代码审查流程和有限的初始访问开始，并随着信心建立逐步扩大。

我们观察到，部署最顺畅的组织会尽早建立跨职能工作组，把工程、信息安全和治理代表聚集在一起，共同定义要求并构建 rollout roadmap。

将这些模式应用到你的组织

Claude Code 围绕常规软件工程环境设计，在这种环境中，工程师是代码库的主要贡献者，repo 使用 Git，代码遵循标准目录结构。多数大型代码库符合这一模式，但非传统设置需要额外配置工作，例如拥有大型二进制资产的游戏引擎、使用非常规版本控制的环境，或非工程师也会贡献代码的代码库。我们的建议假设的是常规设置，而我们描述的这些模式已经在许多客户中奏效。任何剩余复杂性，都需要结合你的代码库、工具链和组织进行具体判断。这正是 Anthropic Applied AI 团队会直接与工程团队合作，将这些模式转化为你组织具体要求的地方。