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

来源 (中文翻译版): https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start 抓取时间: 2026-07-21 16:21:33

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

最成功的 Claude Code 部署在配置、工具和组织结构方面共享一套可识别的模式。本文是** 大规模 Claude Code** 系列文章的一部分，该系列涵盖工程组织在企业规模下使用 Claude Code 构建的最佳实践。

• 类别 企业 AI
• 产品 Claude Code
• 日期 2026 年 5 月 14 日
• 阅读时间 5 分钟
• 分享 复制链接 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 中删除的模块，而没有任何迹象表明两者都已过时。 智能体搜索避免了这些失败模式。当数千名工程师提交新代码时，没有嵌入管道或集中式索引需要维护。每个开发人员的实例都从实时代码库工作。 但是这种方法有一个权衡：当 Claude 有足够的启动上下文来知道在哪里寻找时，它的效果最好。这意味着 Claude 导航的质量取决于代码库的设置情况，通过 CLAUDE.md 文件和技能分层上下文。如果你要求它在十亿行代码库中找到一个模糊模式的所有实例，你会在工作开始前就遇到上下文窗口限制。投资于代码库设置的团队会看到更好的结果。

执行层与模型同样重要

关于 Claude Code 最常见的误解之一是，其能力完全由使用的模型定义。团队专注于模型的基准测试以及它在测试任务上的表现。实际上，围绕模型构建的生态系统——执行层——比单独的模型更能决定 Claude Code 的表现。 执行层由五个扩展点构建——CLAUDE.md 文件、hooks、技能、插件和 MCP 服务器——每个都服务于不同的功能。团队构建它们的顺序很重要，因为每一层都建立在之前的基础上。两个额外的能力，LSP 集成和子智能体，完善了设置。下面，我们解释这些组件和能力各自的作用： CLAUDE.md文件是第一位的。这些是 Claude 在每个会话开始时自动读取的上下文文件：根文件用于全局概览，子目录文件用于本地约定。它们为 Claude 提供了做好任何事情所需的代码库知识。因为它们在每个会话中加载，无论任务如何，保持它们专注于广泛适用的内容将防止它们成为性能负担。 Hooks使设置能够自我改进。大多数团队认为 hooks 是防止 Claude 做错事的脚本，但它们更有价值的用途是持续改进。stop hook 可以反思会话期间发生的事情，并在上下文新鲜时提出 CLAUDE.md 更新。start hook 可以动态加载团队特定的上下文，以便每个开发人员都能获得适合他们模块的正确设置，而无需手动配置。对于 linting 和格式化等自动化检查，hooks 以确定性方式执行规则，并产生比依赖 Claude 记住指令更一致的结果。 技能保持正确的专业知识按需可用，而不会膨胀每个会话。在具有数十种任务类型的大型代码库中，并非所有专业知识都需要存在于每个会话中。技能通过渐进式披露解决了这个问题，卸载专门的工作流和领域知识，否则这些知识会竞争上下文空间，并且只在任务需要时加载它们。例如，当 Claude 评估代码漏洞时，安全审查技能会加载，而文档处理技能在进行代码更改需要更新文档时加载。 技能也可以限定在特定路径，因此它们只在代码库的相关部分激活。拥有支付服务的团队可以将他们的部署技能绑定到该目录，这样当有人在 monorepo 的其他地方工作时，它永远不会自动加载。 插件分发有效的设置。大型代码库的一个挑战是，_好的_设置可能一直停留在部落知识中。插件将技能、hooks 和 MCP 配置捆绑到一个可安装的包中，所以当新工程师在第一天安装该插件时，他们将立即拥有与已经使用 Claude 的人相同的上下文和能力。插件更新可以通过托管市场在整个组织中分发。 例如，我们合作的一家大型零售组织构建了一个技能，将 Claude 连接到他们的内部分析平台，以便业务分析师可以在不离开工作流的情况下提取性能数据。在向业务广泛推出之前，他们将其作为插件分发。 语言服务器协议（LSP）集成为 Claude 提供与开发人员在 IDE 中相同的导航。大多数大型代码库的 IDE 都已经运行了 LSP，支持"转到定义"和"查找所有引用"。将此提供给 Claude 使其具有符号级精度：它可以跟踪函数调用到其定义，跨文件跟踪引用，并区分不同语言中同名的函数。没有它，Claude 会对文本进行模式匹配，可能会落在错误的符号上。我们合作的一家企业软件公司在推出 Claude Code 之前在整个组织内部署了 LSP 集成，专门为了使 C 和 C++ 导航在大规模上可靠。对于多语言代码库，这是最高价值的投资之一。 MCP 服务器扩展了一切。MCP 服务器是 Claude 连接到它无法以其他方式访问的内部工具、数据源和 API 的方式。最成熟的团队构建了 MCP 服务器，将结构化搜索作为 Claude 可以直接调用的工具。其他人将 Claude 连接到内部文档、票务系统或分析平台。 子智能体将探索与编辑分开。子智能体是一个隔离的 Claude 实例，具有自己的上下文窗口，接受任务，完成工作，并仅将最终结果返回给父智能体。一旦执行层就位，一些团队启动一个只读子智能体来映射子系统并将发现结果写入文件，然后让主智能体在完整的情况下进行编辑。 Claude Code 的扩展层概览。 下表总结了每个组件的作用、加载时间以及我们看到的每个组件最常见的错误：

成功部署的三种配置模式

如何为大型代码库配置 Claude Code 在很大程度上取决于该代码库的结构。然而，在我们观察到的部署中，三种模式始终出现。

使代码库在大规模上可导航

Claude 在大型代码库中提供帮助的能力受限于其找到正确上下文的能力。每个会话加载太多上下文会降低性能，而上下文太少会让 Claude 盲目导航。最有效的部署预先投资于使代码库对 Claude 清晰可读。几种模式始终出现：

• 保持 CLAUDE.md 文件精简和分层。Claude 在代码库中移动时以累加方式加载它们：根文件用于全局概览，子目录文件用于本地约定。根文件应该只包含指针和关键陷阱；其他一切都会变成噪音。
• 在子目录中初始化，而不是在 repo 根目录。当 Claude 的范围限定为与任务实际相关的代码库部分时，它的工作效果最好。在 monorepo 中，这可能感觉违反直觉，因为工具通常假定根目录访问，但 Claude 会自动沿着目录树向上走，并加载它沿途找到的每个 CLAUDE.md 文件，所以根级上下文永远不会丢失。
• 按子目录限定测试和 lint 命令的范围。当 Claude 更改了一个服务时运行完整套件会导致超时，并在不相关的输出上浪费上下文。子目录级别的 CLAUDE.md 文件应该指定适用于代码库该部分的命令。这对于每个目录都有自己的测试和构建命令的面向服务的代码库非常有效。在具有深度跨目录依赖的编译语言 monorepo 中，按子目录限定范围更难实现，可能需要特定项目的构建配置。
• 使用.gitignore文件排除生成的文件、构建工件和第三方代码。在 .claude/settings.json 中提交 permissions.deny 规则意味着排除是版本控制的，所以团队中的每个开发人员都获得相同的降噪，而无需自己配置。在某些代码库中，生成的文件本身就是开发工作的主题。从事代码生成器工作的开发人员可以在其本地设置中覆盖项目级别的排除，而不会影响团队的其他成员。
• 当目录结构无法完成工作时构建代码库地图。对于代码未合并到常规目录结构中的组织，在 repo 根目录下的轻量级 markdown 文件列出每个顶级文件夹及其所在内容的单行描述，为 Claude 提供了一个目录，它可以在打开文件之前扫描。对于拥有数百个顶级文件夹的代码库，这最好作为分层方法工作：根文件仅描述最高级别的结构，子目录 CLAUDE.md 文件提供下一级细节，在 Claude 遍历树时按需加载。对于更简单的情况，@-提及 Claude 应该引用的特定文件或目录可以完成相同的工作。
• 运行 LSP 服务器，以便 Claude 按符号而不是字符串搜索。在大型代码库中 grep 常见函数名称会返回数千个匹配项，Claude 会消耗上下文打开文件来弄清楚哪个重要。LSP 仅返回指向同一符号的引用，所以过滤在 Claude 读取任何内容之前发生。设置这需要为你的语言安装一个代码智能插件和相应的语言服务器二进制文件；Claude Code 文档涵盖了可用的插件和故障排除。

注意：在某些边缘情况下，即使是分层的 CLAUDE.md 方法也会失效，例如拥有数十万个文件夹和数百万个文件的代码库，或者使用非 git 版本控制的遗留系统。我们将在本系列的未来部分解决它们的挑战。关于遗留系统，请参阅 AI 如何打破 COBOL 现代化的成本壁垒。

随着模型智能的发展，积极维护 CLAUDE.md 文件

随着模型的发展，为当前模型编写的指令可能会与未来的模型背道而驰。指导 Claude 完成它过去难以处理的模式的 CLAUDE.md 文件可能会变得不必要，或者在下一代模型发布时会变得主动受限。例如，一个 CLAUDE.md 规则告诉 Claude 将每次重构分解为单文件更改，这可能帮助了早期模型保持正轨，但会阻止更新模型进行它能很好处理的协调跨文件编辑。 为补偿特定模型限制而构建的技能和 hooks，无论是在模型的推理还是在 Claude Code 自己的工具中，一旦这些限制不再存在，就会成为开销。例如，一个在 Perforce 代码库中拦截文件写入以强制执行 p4 edit 的 hook，一旦 Claude Code 添加了原生 Perforce 模式，就变得多余了。 团队应该期望每三到六个月进行一次有意义的配置审查，但当性能在主要模型发布后感觉停滞不前时，也值得进行一次审查。

为 Claude Code 管理和采用分配所有权

仅技术配置不会推动采用。做得正确的组织也投资于组织层面。 传播最快的推出在广泛访问之前就有了专门的基础设施投资。一个小团队，有时甚至只有一个人，连接了工具，这样当开发人员第一次接触时，Claude 已经适应了他们的工作流。在一家公司，几名工程师构建了一套插件和 MCP，第一天就可用。在另一家，一个专门管理 AI 编码工具的整个团队在开始推出之前就已经有了基础设施。在这两种情况下，开发人员的第一次体验都是富有成效的，而不是令人沮丧的，采用从那里开始传播。 今天从事这项工作的团队往往隶属于开发者体验或开发者生产力部门，这通常负责新工程师的入职和构建开发者工具。几个组织中出现的一个新兴角色是智能体经理：一个专门管理 Claude Code 生态系统的 PM/工程师混合职能。对于没有专门团队的组织，最低限度的可行版本是 DRI：一个人拥有 Claude Code 配置的所有权，有权决定设置、权限策略、插件市场和 CLAUDE.md 约定，并负责保持它们的更新。 自下而上的采用会产生热情，但如果没有人集中有效的做法，可能会分散。你需要有一个人或团队来组装和推广正确的 Claude Code 约定（例如标准化的 CLAUDE.md 层次结构或精选的技能和插件集）。没有这项工作，知识将停留在部落水平，采用将停滞不前。 在大型组织中，特别是在受监管行业的组织中，治理问题很早就出现了，例如：谁控制可用的技能和插件，如何防止数千名工程师独立重建相同的东西，如何确保 AI 生成的代码与人类生成的代码经过相同的审查过程？为了尽早解决这些问题，我们建议从一套已定义的批准技能、必需的代码审查流程和有限的初始访问开始，并随着信心的建立而扩展。 我们观察到，在那些早期建立跨职能工作组的组织中，部署最顺利，通过汇集工程、信息安全和治理代表共同定义需求并制定推出路线图。

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

Claude Code 是围绕常规软件工程环境设计的，其中工程师是主要的代码库贡献者，repo 使用 Git，代码遵循标准目录结构。大多数大型代码库都适合这种模式，但非传统设置，如具有大型二进制资产的游戏引擎、具有非常规版本控制的环境，或非工程师贡献代码库的环境，需要额外的配置工作。我们的指导假设常规设置，并且我们描述的模式在我们的许多客户中都有效。任何剩余的复杂性都需要针对你的代码库、工具和组织的判断力。这就是 Anthropic 的应用 AI 团队直接与工程团队合作，将这些模式转化为你组织的特定要求的地方。 开始使用 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 对本文提供反馈。 ‍ 未找到项目。 上一篇上一篇 0/5 下一篇下一篇 电子书

常见问题 未找到项目。

相关文章

探索更多产品新闻和团队使用 Claude 构建的最佳实践。 2026 年 7 月 20 日

在前沿工作：乐天如何使用 Claude Fable 5 在一夜之间构建智能体

企业 AI 在前沿工作：乐天如何使用 Claude Fable 5 在一夜之间构建智能体在前沿工作：乐天如何使用 Claude Fable 5 在一夜之间构建智能体 在前沿工作：乐天如何使用 Claude Fable 5 在一夜之间构建智能体在前沿工作：乐天如何使用 Claude Fable 5 在一夜之间构建智能体 2026 年 7 月 17 日

在前沿工作：Cursor 如何知道 Claude Fable 5 已准备好解决最难的 1% 问题

企业 AI 在前沿工作：Cursor 如何知道 Claude Fable 5 已准备好解决最难的 1% 问题在前沿工作：Cursor 如何知道 Claude Fable 5 已准备好解决最难的 1% 问题 在前沿工作：Cursor 如何知道 Claude Fable 5 已准备好解决最难的 1% 问题在前沿工作：Cursor 如何知道 Claude Fable 5 已准备好解决最难的 1% 问题 2026 年 7 月 17 日

零风险不是目标：CISO 智能体 AI 指南

企业 AI 零风险不是目标：CISO 智能体 AI 指南零风险不是目标：CISO 智能体 AI 指南 零风险不是目标：CISO 智能体 AI 指南零风险不是目标：CISO 智能体 AI 指南 2026 年 7 月 16 日

Anthropic 如何使用 Claude Code 运行大规模代码迁移

Claude Code Anthropic 如何使用 Claude Code 运行大规模代码迁移Anthropic 如何使用 Claude Code 运行大规模代码迁移 Anthropic 如何使用 Claude Code 运行大规模代码迁移Anthropic 如何使用 Claude Code 运行大规模代码迁移

用 Claude 改变你的组织运作方式

查看定价 查看定价查看定价 联系销售 联系销售联系销售 获取开发者通讯 产品更新、操作方法、社区聚焦等。每月发送到你的收件箱。 订阅订阅 如果你想收到我们的月度开发者通讯，请提供你的电子邮件地址。你可以随时取消订阅。 谢谢！你已订阅。 抱歉，你的提交有问题，请稍后再试。