1. Claude Code 运行现状与挑战Claude Code 正在生产环境中运行覆盖数百万行代码的单体仓库、数十年的遗留系统、跨越数十个仓库的分布式架构以及拥有数千名开发者的组织。这些环境带来了小型简单代码库不会遇到的挑战无论是每个子目录中不同的构建命令还是分布在没有共享根目录的文件夹中的遗留代码。2. Claude Code 部署模式与最佳实践系列Anthropic 观察到最成功的 Claude Code 部署共享一组可识别的模式涵盖配置、工具和组织结构。本文是 规模化 Claude Code 系列的一部分涵盖了企业规模化使用 Claude Code 的最佳实践。3. Agentic Search 避免传统 RAG 的失败模式传统的 AI 编程工具依赖基于 RAG 的检索通过嵌入整个代码库并在查询时检索相关块。但在大型规模下这些系统可能失败因为嵌入管道无法跟上活跃的工程团队。当开发者查询索引时它反映的是几天、几周甚至几小时前存在的代码库。检索然后返回团队两周前重命名的函数或者引用上一个 sprint 中删除的模块而没有任何指示两者已过时。Agentic search 避免了这些失败模式。没有嵌入管道或需要维护的集中索引因为数千名工程师提交新代码时每个开发者的实例都从实时代码库工作。但这种方法有权衡它最适合 Claude 有足够的起始上下文知道在哪里查找。这意味着 Claude 的导航质量取决于代码库的设置方式用 CLAUDE.md 文件和技能分层上下文。如果你要求它在十亿行代码库中找到所有模糊模式的实例你会在工作开始前就达到上下文窗口限制。投资于代码库设置的团队会看到更好的结果。4. 扩展层决定性能而非模型本身关于 Claude Code 最常见的误解之一是其能力完全由使用的模型定义。团队关注模型的基准测试及其在测试任务上的表现。在实践中围绕模型构建的生态系统即 harness比单独的模型更能决定 Claude Code 的性能。Harness 由五个扩展点构建CLAUDE.md 文件、hooks、skills、plugins 和 MCP 服务器每个都有不同的功能。团队构建它们的顺序很重要因为每一层都建立在前一层之上。LSP 集成和子代理这两个额外能力完成了设置。CLAUDE.md 文件首先出现。这些是 Claude 在每个会话开始时自动读取的上下文文件根文件用于全局视图子目录文件用于本地约定。它们给予 Claude 所需的代码库知识来做好任何事情。由于它们在每个会话中加载无论任务如何保持它们专注于广泛适用的内容将防止它们成为性能的拖累。Hooks 使设置自我改进。大多数团队认为 hooks 是阻止 Claude 做某事的脚本但它们更有价值的用途是持续改进。stop hook 可以反思会话期间发生的事情并在上下文新鲜时提出 CLAUDE.md 更新。start hook 可以动态加载特定于团队的上下文这样每个开发者都为其模块获得正确的设置而无需手动配置。对于 linting 和格式化等自动检查hooks 确定性地执行规则比依赖 Claude 记住指令产生更一致的结果。Skills 保持正确的专业知识按需可用而不会膨胀每个会话。在具有数十种任务类型的大型代码库中并非所有专业知识都需要出现在每个会话中。Skills 通过渐进式披露解决这一问题将专业工作流和领域知识卸载否则这些会竞争上下文空间并且仅在任务需要时才加载。例如安全审查 skill 在 Claude 评估代码漏洞时加载而文档处理 skill 在代码更改并需要更新文档时加载。Skills 也可以绑定到特定路径因此它们仅在代码库的相关部分激活。Plugins 分发有效的设置。一个挑战是有效的设置可能保持部落化。一个 plugin 将 skills、hooks 和 MCP 配置捆绑到单个可安装包中因此当新工程师在第一天安装该 plugin 时他们将立即拥有与已经使用 Claude 的人相同的上下文和能力。Plugin 更新可以通过托管市场跨组织分发。LSP 集成赋予 Claude 与开发者在 IDE 中相同的导航能力。大多数大型代码库 IDE 已经运行 LSP为 转到定义 和 查找所有引用 提供支持。向 Claude 展示这一点给了它符号级精度它可以跟踪函数调用到其定义跨文件追踪引用并区分不同语言中同名的函数。没有它Claude 在文本上模式匹配可能落在错误的符号上。一家企业软件公司在 Claude Code 推广之前就在整个组织部署了 LSP 集成专门是为了在规模上使 C 和 C 导航可靠。对于多语言代码库这是最高价值的投资之一。MCP 服务器扩展一切。MCP 服务器是 Claude 连接到无法到达的内部工具、数据源和 API 的方式。最复杂的团队构建 MCP 服务器将结构化搜索作为 Claude 可以直接调用的工具暴露。其他人连接 Claude 到内部文档、票务系统或分析平台。Subagents 将探索与编辑分离。子代理是一个孤立的 Claude 实例有自己的上下文窗口接受任务执行工作只将最终结果返回给父级。一旦 harness 就位一些团队启动只读子代理来映射子系统并将发现写入文件然后让主代理根据完整情况编辑。5. 三大配置模式如何为大型代码库配置 Claude Code 很大程度上取决于该代码库的结构。但三种模式在观察到的部署中始终如一地出现。保持 CLAUDE.md 文件精简和分层。Claude 在代码库中移动时_ADDITIVELY_加载它们根文件用于全局视图子目录文件用于本地约定。根文件应该只是指针和关键的注意事项其他一切都会漂移到噪音中。在子目录中初始化而不是在 repo 根目录。Claude 在与任务实际相关的代码库部分范围内工作时效果最好。在单体仓库中这可能感觉违反直觉因为工具通常假设根访问但 Claude 自动向上遍历目录树并加载沿途找到的每个 CLAUDE.md 文件因此根级上下文永远不会丢失。每个子目录的测试和 lint 命令范围。当 Claude 更改一个服务时运行完整套件会导致超时并在不相关的输出上浪费上下文。子目录级别的 CLAUDE.md 文件应该指定适用于该部分代码库的命令。这对于面向服务的代码库工作得很好其中每个目录都有自己的测试和构建命令。在具有深度跨目录依赖的编译语言单体仓库中每个子目录的范围更难实现可能需要特定于项目的构建配置。使用 .claudeignore 文件排除生成的文件、构建工件和第三方代码。在 .claude/settings.json 中提交 permissions.deny 规则意味着排除是版本控制的因此团队中的每个开发者都获得相同的噪音减少而无需自己配置。在某些代码库中生成的文件本身就是开发工作的主题。从事代码生成器工作的开发者可以在本地设置中覆盖项目级别的排除而不影响团队的其他人。构建代码库地图当目录结构不能完成工作时。对于代码不在传统目录结构中整合的组织在 repo 根目录的轻量级 markdown 文件列出每个顶级文件夹及其内容的单行描述给 Claude 一个可以扫描的目录表然后再打开文件。对于有数百个顶级文件夹的代码库这最适合作为分层方法根文件只描述最高级别的结构子目录 CLAUDE.md 文件提供下一级细节在 Claude 通过树移动时按需加载。对于更简单的情况 - mention 特定文件或目录可以让 Claude 参考相同的工作。运行 LSP 服务器以便 Claude 按符号而非字符串搜索。在大型代码库中 grep 常见函数名会返回数千个匹配项Claude 会燃烧上下文打开文件以找出哪个重要。LSP 只返回指向相同符号的引用因此过滤在 Claude 读取任何内容之前发生。6. 主动维护 CLAUDE.md 文件随着模型的发展为当前模型编写的指令可能会与未来的模型产生负面影响。指导 Claude 度过曾经挣扎模式的 CLAUDE.md 文件可能在下一个模型发布时变得不必要或主动限制。例如一个告诉 Claude 将每个重构分解为单文件更改的 CLAUDE.md 规则可能帮助更早的模型保持正轨但会阻止更新模型进行其处理良好的协调跨文件编辑。为补偿特定模型限制而构建的 skills 和 hooks无论是模型的推理还是 Claude Code 自己的工具一旦这些限制不再存在就会成为开销。一旦 Claude Code 添加了原生 Perforce 模式一个拦截文件写入以在 Perforce 代码库中强制执行 p4 编辑的 hook 就变得冗余了。团队应该期望每三到六个月进行一次有意义的配置审查但在重大模型发布后性能感觉停滞时也值得进行一次。7. 分配 Claude Code 管理和采用的所有权技术配置 alone 不能推动采用。正确的组织也在组织层投入。推广传播最快的公司在广泛访问之前有专门的基础设施投资。一个小团队有时甚至只是一两个人连接工具以便在开发者第一次接触时 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 在大型代码库中的应用：最佳实践与起步指南
发布时间：2026/5/16 16:35:01
1. Claude Code 运行现状与挑战Claude Code 正在生产环境中运行覆盖数百万行代码的单体仓库、数十年的遗留系统、跨越数十个仓库的分布式架构以及拥有数千名开发者的组织。这些环境带来了小型简单代码库不会遇到的挑战无论是每个子目录中不同的构建命令还是分布在没有共享根目录的文件夹中的遗留代码。2. Claude Code 部署模式与最佳实践系列Anthropic 观察到最成功的 Claude Code 部署共享一组可识别的模式涵盖配置、工具和组织结构。本文是 规模化 Claude Code 系列的一部分涵盖了企业规模化使用 Claude Code 的最佳实践。3. Agentic Search 避免传统 RAG 的失败模式传统的 AI 编程工具依赖基于 RAG 的检索通过嵌入整个代码库并在查询时检索相关块。但在大型规模下这些系统可能失败因为嵌入管道无法跟上活跃的工程团队。当开发者查询索引时它反映的是几天、几周甚至几小时前存在的代码库。检索然后返回团队两周前重命名的函数或者引用上一个 sprint 中删除的模块而没有任何指示两者已过时。Agentic search 避免了这些失败模式。没有嵌入管道或需要维护的集中索引因为数千名工程师提交新代码时每个开发者的实例都从实时代码库工作。但这种方法有权衡它最适合 Claude 有足够的起始上下文知道在哪里查找。这意味着 Claude 的导航质量取决于代码库的设置方式用 CLAUDE.md 文件和技能分层上下文。如果你要求它在十亿行代码库中找到所有模糊模式的实例你会在工作开始前就达到上下文窗口限制。投资于代码库设置的团队会看到更好的结果。4. 扩展层决定性能而非模型本身关于 Claude Code 最常见的误解之一是其能力完全由使用的模型定义。团队关注模型的基准测试及其在测试任务上的表现。在实践中围绕模型构建的生态系统即 harness比单独的模型更能决定 Claude Code 的性能。Harness 由五个扩展点构建CLAUDE.md 文件、hooks、skills、plugins 和 MCP 服务器每个都有不同的功能。团队构建它们的顺序很重要因为每一层都建立在前一层之上。LSP 集成和子代理这两个额外能力完成了设置。CLAUDE.md 文件首先出现。这些是 Claude 在每个会话开始时自动读取的上下文文件根文件用于全局视图子目录文件用于本地约定。它们给予 Claude 所需的代码库知识来做好任何事情。由于它们在每个会话中加载无论任务如何保持它们专注于广泛适用的内容将防止它们成为性能的拖累。Hooks 使设置自我改进。大多数团队认为 hooks 是阻止 Claude 做某事的脚本但它们更有价值的用途是持续改进。stop hook 可以反思会话期间发生的事情并在上下文新鲜时提出 CLAUDE.md 更新。start hook 可以动态加载特定于团队的上下文这样每个开发者都为其模块获得正确的设置而无需手动配置。对于 linting 和格式化等自动检查hooks 确定性地执行规则比依赖 Claude 记住指令产生更一致的结果。Skills 保持正确的专业知识按需可用而不会膨胀每个会话。在具有数十种任务类型的大型代码库中并非所有专业知识都需要出现在每个会话中。Skills 通过渐进式披露解决这一问题将专业工作流和领域知识卸载否则这些会竞争上下文空间并且仅在任务需要时才加载。例如安全审查 skill 在 Claude 评估代码漏洞时加载而文档处理 skill 在代码更改并需要更新文档时加载。Skills 也可以绑定到特定路径因此它们仅在代码库的相关部分激活。Plugins 分发有效的设置。一个挑战是有效的设置可能保持部落化。一个 plugin 将 skills、hooks 和 MCP 配置捆绑到单个可安装包中因此当新工程师在第一天安装该 plugin 时他们将立即拥有与已经使用 Claude 的人相同的上下文和能力。Plugin 更新可以通过托管市场跨组织分发。LSP 集成赋予 Claude 与开发者在 IDE 中相同的导航能力。大多数大型代码库 IDE 已经运行 LSP为 转到定义 和 查找所有引用 提供支持。向 Claude 展示这一点给了它符号级精度它可以跟踪函数调用到其定义跨文件追踪引用并区分不同语言中同名的函数。没有它Claude 在文本上模式匹配可能落在错误的符号上。一家企业软件公司在 Claude Code 推广之前就在整个组织部署了 LSP 集成专门是为了在规模上使 C 和 C 导航可靠。对于多语言代码库这是最高价值的投资之一。MCP 服务器扩展一切。MCP 服务器是 Claude 连接到无法到达的内部工具、数据源和 API 的方式。最复杂的团队构建 MCP 服务器将结构化搜索作为 Claude 可以直接调用的工具暴露。其他人连接 Claude 到内部文档、票务系统或分析平台。Subagents 将探索与编辑分离。子代理是一个孤立的 Claude 实例有自己的上下文窗口接受任务执行工作只将最终结果返回给父级。一旦 harness 就位一些团队启动只读子代理来映射子系统并将发现写入文件然后让主代理根据完整情况编辑。5. 三大配置模式如何为大型代码库配置 Claude Code 很大程度上取决于该代码库的结构。但三种模式在观察到的部署中始终如一地出现。保持 CLAUDE.md 文件精简和分层。Claude 在代码库中移动时_ADDITIVELY_加载它们根文件用于全局视图子目录文件用于本地约定。根文件应该只是指针和关键的注意事项其他一切都会漂移到噪音中。在子目录中初始化而不是在 repo 根目录。Claude 在与任务实际相关的代码库部分范围内工作时效果最好。在单体仓库中这可能感觉违反直觉因为工具通常假设根访问但 Claude 自动向上遍历目录树并加载沿途找到的每个 CLAUDE.md 文件因此根级上下文永远不会丢失。每个子目录的测试和 lint 命令范围。当 Claude 更改一个服务时运行完整套件会导致超时并在不相关的输出上浪费上下文。子目录级别的 CLAUDE.md 文件应该指定适用于该部分代码库的命令。这对于面向服务的代码库工作得很好其中每个目录都有自己的测试和构建命令。在具有深度跨目录依赖的编译语言单体仓库中每个子目录的范围更难实现可能需要特定于项目的构建配置。使用 .claudeignore 文件排除生成的文件、构建工件和第三方代码。在 .claude/settings.json 中提交 permissions.deny 规则意味着排除是版本控制的因此团队中的每个开发者都获得相同的噪音减少而无需自己配置。在某些代码库中生成的文件本身就是开发工作的主题。从事代码生成器工作的开发者可以在本地设置中覆盖项目级别的排除而不影响团队的其他人。构建代码库地图当目录结构不能完成工作时。对于代码不在传统目录结构中整合的组织在 repo 根目录的轻量级 markdown 文件列出每个顶级文件夹及其内容的单行描述给 Claude 一个可以扫描的目录表然后再打开文件。对于有数百个顶级文件夹的代码库这最适合作为分层方法根文件只描述最高级别的结构子目录 CLAUDE.md 文件提供下一级细节在 Claude 通过树移动时按需加载。对于更简单的情况 - mention 特定文件或目录可以让 Claude 参考相同的工作。运行 LSP 服务器以便 Claude 按符号而非字符串搜索。在大型代码库中 grep 常见函数名会返回数千个匹配项Claude 会燃烧上下文打开文件以找出哪个重要。LSP 只返回指向相同符号的引用因此过滤在 Claude 读取任何内容之前发生。6. 主动维护 CLAUDE.md 文件随着模型的发展为当前模型编写的指令可能会与未来的模型产生负面影响。指导 Claude 度过曾经挣扎模式的 CLAUDE.md 文件可能在下一个模型发布时变得不必要或主动限制。例如一个告诉 Claude 将每个重构分解为单文件更改的 CLAUDE.md 规则可能帮助更早的模型保持正轨但会阻止更新模型进行其处理良好的协调跨文件编辑。为补偿特定模型限制而构建的 skills 和 hooks无论是模型的推理还是 Claude Code 自己的工具一旦这些限制不再存在就会成为开销。一旦 Claude Code 添加了原生 Perforce 模式一个拦截文件写入以在 Perforce 代码库中强制执行 p4 编辑的 hook 就变得冗余了。团队应该期望每三到六个月进行一次有意义的配置审查但在重大模型发布后性能感觉停滞时也值得进行一次。7. 分配 Claude Code 管理和采用的所有权技术配置 alone 不能推动采用。正确的组织也在组织层投入。推广传播最快的公司在广泛访问之前有专门的基础设施投资。一个小团队有时甚至只是一两个人连接工具以便在开发者第一次接触时 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、必需的代码审查流程和有限的初始访问开始随着信心的建立而扩展。
