Agent X-Ray

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

关键要点

• 智能体式搜索 (agentic search) 优于 RAG：Claude Code 像工程师一样实时遍历文件、grep、追踪引用，不依赖会过期的代码库索引——但前提是有足够的起步上下文知道"该往哪看"。
• 配套体系 (harness) 与模型同等重要：决定 Claude Code 表现的不只是模型，而是围绕模型搭建的五大扩展点——CLAUDE.md、hooks、skills、plugins、MCP servers，外加 LSP 集成与子智能体两项能力。
• CLAUDE.md 要精简分层：根文件只放指针和关键坑点，子目录文件放局部约定；在子目录而非仓库根目录初始化。
• 多语言代码库优先投资 LSP：让 Claude 按符号而非字符串搜索，是性价比最高的投入之一。
• 技术配置之外要指定负责人：成功的推广都在广泛开放前先做基础设施投入，并设立直接责任人 (DRI) 或"智能体管理员"角色统一沉淀有效经验。

原文信息 本文译自 Anthropic 官方博客「Claude Code at scale」系列文章。 英文原文存档：English Original 来源：https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start

Claude Code 已经在生产环境中运行于数百万行的单体仓库 (monorepo)、有数十年历史的遗留系统、横跨数十个仓库的分布式架构，以及拥有数千名开发者的组织中。这些环境带来的挑战是更小、更简单的代码库所没有的——比如每个子目录的构建命令各不相同，又比如遗留代码散落在没有共同根目录的多个文件夹里。

本文介绍我们观察到的、能让 Claude Code 在大规模场景下被成功采用的若干模式。我们用"大型代码库"一词指代相当宽泛的部署形态：数百万行的单体仓库、积累了数十年的遗留系统、分散在不同仓库中的数十个微服务，或上述形态的任意组合。它也包括那些团队通常不会联想到 AI 编程工具的语言所构建的代码库，例如 C、C++、C#、Java、PHP。（在这些场景下，Claude Code 的表现往往超出多数团队的预期，尤其是在近期的模型版本发布之后。）尽管每一次大型代码库部署都会被其特定的版本控制方式、团队结构和长期积累的惯例所塑造，但本文的模式在它们之间是通用的，对于正在考虑采用 Claude Code 的团队来说是一个不错的起点。

Claude Code 如何在大型代码库中导航

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

基于检索增强生成 (RAG) 的 AI 编程工具的工作方式是：对整个代码库做向量嵌入，在查询时检索相关的代码片段。在大规模场景下，这类系统可能失效，因为嵌入流水线跟不上活跃工程团队的节奏。等开发者去查询索引时，索引反映的是代码库在数周、数天甚至数小时之前的状态。检索因此会返回团队两周前就已重命名的函数，或引用上个迭代就已删除的模块，而且没有任何迹象提示这些内容已经过期。

智能体式搜索 (agentic search) 避免了这些失效模式。当数千名工程师不断提交新代码时，它没有需要维护的嵌入流水线，也没有集中式索引。每位开发者的实例都基于实时的代码库工作。

但这种方式有一个权衡：它在 Claude 拥有足够起步上下文、知道该往哪看时效果最好。这意味着 Claude 导航的质量取决于代码库被设置得有多好——通过 CLAUDE.md 文件和 skills 来分层地补充上下文。如果你让它在一个十亿行的代码库里找出某个含糊模式的所有出现位置，工作还没开始就会撞上上下文窗口的上限。在代码库设置上投入的团队会得到更好的结果。

配套体系与模型同等重要

关于 Claude Code 最常见的误解之一，是认为它的能力完全由所用的模型决定。团队往往盯着模型的基准测试分数，以及它在测试任务上的表现。但实际上，围绕模型搭建起来的生态——即配套体系 (harness)——对 Claude Code 表现的决定作用，比模型本身更大。

配套体系由五个扩展点构成——CLAUDE.md 文件、hooks、skills、plugins 和 MCP servers——每一个承担不同的功能。团队搭建它们的顺序很重要，因为每一层都建立在前一层之上。另外两项能力——LSP 集成和子智能体——补全了整套配置。下面我们逐一说明这些组件和能力的作用：

CLAUDE.md 文件最先建立。它们是 Claude 在每次会话开始时自动读取的上下文文件：根文件提供全局视角，子目录文件提供局部约定。它们赋予 Claude 做好任何工作所需的代码库知识。由于无论任务是什么它们都会在每次会话中加载，因此让它们聚焦于"普遍适用"的内容，可以避免它们成为性能上的拖累。

Hooks 让整套配置能够自我改进。大多数团队把 hooks 理解为阻止 Claude 做错事的脚本，但它们更有价值的用途是持续改进。一个 stop hook 可以在一次会话结束时回顾会话过程中发生了什么，并趁着上下文还新鲜时提出对 CLAUDE.md 的更新建议。一个 start hook 可以动态加载团队专属的上下文，让每位开发者无需手动配置就能为自己负责的模块获得正确的设置。对于代码检查 (linting) 和格式化这类自动化检查，hooks 能确定性地强制执行规则，比依赖 Claude 记住某条指令产生的结果更一致。

Skills 让正确的专业能力可按需调用，而不会让每次会话都变得臃肿。 在一个有几十种任务类型的大型代码库里，并非所有专业知识都需要出现在每一次会话中。Skills 通过渐进式披露 (progressive disclosure) 解决这个问题：它把那些原本会争抢上下文空间的专门工作流和领域知识卸载出去，只在任务真正需要时才加载。例如，安全审查 skill 会在 Claude 评估代码漏洞时加载，而文档处理 skill 会在代码发生改动、需要更新文档时加载。

Skills 还可以被限定到特定路径，使其只在代码库的相关部分激活。一个负责支付服务的团队可以把他们的部署 skill 绑定到该目录，这样当有人在单体仓库的其他位置工作时，它就不会被自动加载。

Plugins 负责分发有效的做法。 大型代码库的一个挑战是：好的配置往往停留在小圈子里、口口相传。一个 plugin 把 skills、hooks 和 MCP 配置打包成一个可安装的整体，于是当一名新工程师在入职第一天安装这个 plugin 时，他立刻就拥有了和那些早已在用 Claude 的同事相同的上下文与能力。Plugin 的更新可以通过受管市场 (managed marketplaces) 分发到整个组织。

举个例子，我们合作的一家大型零售企业构建了一个 skill，把 Claude 连接到他们的内部分析平台，让业务分析师无需离开工作流就能拉取业绩数据。他们在向业务部门全面推广之前，先以 plugin 的形式分发了它。

语言服务器协议 (LSP) 集成赋予 Claude 与开发者在 IDE 中相同的导航能力。 大多数大型代码库的 IDE 本就运行着一个 LSP，为"跳转到定义"和"查找所有引用"提供支持。把这个能力暴露给 Claude，能让它获得符号级精度：它可以从一次函数调用追踪到其定义、跨文件追踪引用，并区分不同语言中同名的函数。没有它，Claude 只能基于文本做模式匹配，可能落到错误的符号上。我们合作过的一家企业软件公司在 Claude Code 推广之前就在全组织范围部署了 LSP 集成，专门是为了让 C 和 C++ 的导航在大规模下保持可靠。对于多语言代码库，这是性价比最高的投资之一。

MCP servers 扩展一切。 MCP servers 是 Claude 连接到那些它本来无法触及的内部工具、数据源和 API 的方式。最成熟的团队构建了 MCP servers，把结构化搜索暴露为一个 Claude 可以直接调用的工具。还有一些团队把 Claude 连接到内部文档、工单系统或分析平台。

子智能体 (Subagents) 把探索与编辑分离开。 子智能体是一个隔离的 Claude 实例，拥有自己的上下文窗口，它接收一个任务、完成工作，并只把最终结果返回给父智能体。在配套体系就位之后，一些团队会启动一个只读子智能体去梳理某个子系统并把发现写入文件，然后让主智能体在掌握全貌的情况下进行编辑。

Claude Code 扩展层一览。

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

*LSP 通过 plugin 层来接入。子智能体是一种委派能力，而非一个需要配置的扩展点。

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

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

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

Claude 在大型代码库中能提供多少帮助，受限于它找到正确上下文的能力。每次会话加载过多上下文会拖累性能，而上下文太少则让 Claude 只能盲目导航。最有效的部署会在前期投入，让代码库对 Claude 来说是"可读"的。有几种模式反复出现：

• 保持 CLAUDE.md 文件精简且分层。 Claude 在代码库中移动时会叠加式地加载它们：根文件提供全局视角，子目录文件提供局部约定。根文件应只包含指针和关键坑点；其余内容都会逐渐沦为噪声。
• 在子目录初始化，而不是在仓库根目录。 当 Claude 被限定在与任务实际相关的那部分代码库时，工作效果最好。在单体仓库中这可能有些反直觉，因为工具链常常假定从根目录访问，但 Claude 会自动沿目录树向上走，并加载沿途找到的每一个 CLAUDE.md 文件，所以根级上下文永远不会丢失。
• 按子目录限定测试和检查命令的范围。 当 Claude 只改动了一个服务时却运行整套测试，会导致超时，并把上下文浪费在无关的输出上。子目录级别的 CLAUDE.md 文件应指明适用于该部分代码库的命令。这对于面向服务的代码库效果很好——每个目录有自己的测试和构建命令。在具有深层跨目录依赖的编译型语言单体仓库中，按子目录限定范围更难做到，可能需要项目专属的构建配置。
• 使用 .ignore 文件来排除生成文件、构建产物和第三方代码。 把 permissions.deny 规则提交到 .claude/settings.json 意味着这些排除项被纳入了版本控制，于是团队里每位开发者都能获得相同的降噪效果，而无需各自配置。在某些代码库中，生成文件本身就是开发工作的对象。在代码生成器上工作的开发者可以在本地设置中覆盖项目级的排除项，而不影响团队其他人。
• 当目录结构本身不足以说明问题时，构建代码库地图。 对于代码没有按常规目录结构集中存放的组织，在仓库根目录放一个轻量的 markdown 文件，列出每个顶级文件夹并用一行描述其中存放的内容，就能给 Claude 一份"目录索引"，让它在打开文件之前先扫一遍。对于拥有数百个顶级文件夹的代码库，最好采用分层方式：根文件只描述最高层级的结构，子目录的 CLAUDE.md 文件提供下一层级的细节，在 Claude 沿目录树移动时按需加载。对于更简单的情况，用 @ 提及 Claude 应参考的具体文件或目录也能起到同样的作用。
• 运行 LSP 服务器，让 Claude 按符号而非字符串搜索。 在大型代码库里对一个常见函数名做 grep 会返回数千个匹配结果，Claude 会耗费上下文逐一打开文件来判断哪个才是关键。LSP 只返回指向同一个符号的引用，于是过滤在 Claude 读取任何内容之前就已完成。设置这一点需要为你的语言安装一个代码智能插件 以及对应的语言服务器二进制文件；Claude Code 文档涵盖了可用的插件及故障排查。

一点提醒：存在一些边缘情况，连分层的 CLAUDE.md 方式都会失效，例如拥有数十万个文件夹和数百万个文件的代码库，或运行在非 git 版本控制上的遗留系统。我们会在本系列后续的文章中讨论它们的挑战。

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

随着模型不断演进，为当前模型写下的指令可能会反过来妨碍未来的模型。那些曾经引导 Claude 走过它当时难以应对的模式的 CLAUDE.md 文件，在下一代模型发布时可能变得不再必要，甚至产生实际的束缚。例如，一条告诉 Claude 把每次重构都拆成单文件改动的 CLAUDE.md 规则，对早期模型也许有助于让它不跑偏，却会阻止一个更新的模型去做它本可以胜任的、协调一致的跨文件编辑。

那些为弥补模型特定局限（无论是模型推理上的，还是 Claude Code 自身工具上的）而构建的 skills 和 hooks，一旦这些局限不再存在，就成了额外负担。举例来说，一个拦截文件写入、强制在 Perforce 代码库中执行 p4 edit 的 hook，在 Claude Code 增加了原生 Perforce 模式之后就变得多余了。

团队应当预期每三到六个月做一次有意义的配置复审，而每当在重大模型版本发布后感觉性能进入瓶颈时，也值得做一次。

为 Claude Code 的管理和推广指定负责人

仅靠技术配置并不能推动采用。那些做对了的组织，也在组织层面做了投入。

推广速度最快的部署，都在广泛开放访问之前先做了专门的基础设施投入。一个小团队——有时甚至只有一个人——把工具链接好，让 Claude 在开发者第一次接触时就已经契合他们的工作流。在一家公司，几名工程师构建了一整套 plugins 和 MCP，在第一天就可供使用。在另一家公司，一整个专注于管理 AI 编程工具的团队在推广开始前就把基础设施准备就绪。这两种情况下，开发者的初次体验都是高效的，而非令人沮丧的，采用便由此扩散开来。

如今做这项工作的团队往往隶属于开发者体验或开发者效能部门——这通常正是负责新工程师入职和构建开发者工具的职能部门。在一些组织中出现了一个新兴角色：智能体管理员 (agent manager)，这是一个产品经理与工程师混合的职能，专门负责管理 Claude Code 生态。对于没有专门团队的组织，最小可行的版本是一个直接责任人 (DRI)：一个对 Claude Code 配置拥有所有权的人，有权对设置、权限策略、plugin 市场和 CLAUDE.md 约定做决定，并有责任让它们保持最新。

自下而上的采用能激发热情，但如果没有人来集中沉淀有效做法，就可能走向碎片化。你需要有一个人或一个团队来汇集并推广正确的 Claude Code 约定（比如一套标准化的 CLAUDE.md 层级结构，或一组精选的 skills 和 plugins）。没有这项工作，知识就会停留在小圈子里，采用也会陷入停滞。

在大型组织中，尤其是处于受监管行业的组织，治理问题会很早就浮现，例如：谁来控制哪些 skills 和 plugins 可用、如何避免数千名工程师各自重复造同一个轮子、如何确保 AI 生成的代码和人写的代码经过同样的评审流程？为了尽早应对这些问题，我们建议从一组经过批准的 skills、必需的代码评审流程和有限的初始访问权限起步，再随着信心的建立逐步扩大。

我们观察到，那些尽早建立跨职能工作组的组织——把工程、信息安全和治理方面的代表召集到一起共同定义需求、共同制定推广路线图——其部署最为顺畅。

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

Claude Code 的设计围绕的是常规的软件工程环境：工程师是代码库的主要贡献者、仓库使用 Git、代码遵循标准目录结构。大多数大型代码库都符合这一模型，但非传统的设置——例如带有大量二进制资源的游戏引擎、采用非常规版本控制的环境，或有非工程师向代码库贡献内容——则需要额外的配置工作。我们的指导假定的是常规设置，而我们所描述的模式已在众多客户那里行之有效。剩下的任何复杂性，都需要针对你的代码库、工具链和组织做出具体的判断。这正是 Anthropic 应用 AI 团队 (Applied AI team) 直接与工程团队协作的地方——把这些模式转化为你所在组织的具体需求。

开始使用 面向企业的 Claude Code。

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

---

Related Documents

• 英文原文
• AI 技术博客索引

---