Claude Code 正在生产环境中运行，覆盖数百万行代码的单体仓库、数十年的遗留系统、跨越数十个仓库的分布式架构，以及拥有数千名开发者的组织。这些环境带来了小型简单代码库不会遇到的挑战——无论是每个子目录中不同的构建命令，还是分布在没有共享根目录的文件夹中的遗留代码。

Anthropic 观察到最成功的 Claude Code 部署共享一组可识别的模式，涵盖配置、工具和组织结构。本文是 "规模化 Claude Code" 系列的一部分，涵盖了企业规模化使用 Claude Code 的最佳实践。

Agentic Search 避免传统 RAG 的失败模式

传统的 AI 编程工具依赖基于 RAG 的检索，通过嵌入整个代码库并在查询时检索相关块。但在大型规模下，这些系统可能失败，因为嵌入管道无法跟上活跃的工程团队。当开发者查询索引时，它反映的是几天、几周甚至几小时前存在的代码库。检索然后返回团队两周前重命名的函数，或者引用上一个 sprint 中删除的模块，而没有任何指示两者已过时。

Agentic search 避免了这些失败模式。没有嵌入管道或需要维护的集中索引，因为数千名工程师提交新代码时，每个开发者的实例都从实时代码库工作。但这种方法有权衡：它最适合 Claude 有足够的起始上下文知道在哪里查找。这意味着 Claude 的导航质量取决于代码库的设置方式——用 CLAUDE.md 文件和技能分层上下文。如果你要求它在十亿行代码库中找到所有模糊模式的实例，你会在工作开始前就达到上下文窗口限制。投资于代码库设置的团队会看到更好的结果。

扩展层决定性能而非模型本身

关于 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 就位，一些团队启动只读子代理来映射子系统并将发现写入文件，然后让主代理根据完整情况编辑。

三大配置模式

如何为大型代码库配置 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 读取任何内容之前发生。

主动维护 CLAUDE.md 文件

随着模型的发展，为当前模型编写的指令可能会与未来的模型产生负面影响。指导 Claude 度过曾经挣扎模式的 CLAUDE.md 文件可能在下一个模型发布时变得不必要或主动限制。例如，一个告诉 Claude 将每个重构分解为单文件更改的 CLAUDE.md 规则可能帮助更早的模型保持正轨，但会阻止更新模型进行其处理良好的协调跨文件编辑。

为补偿特定模型限制而构建的 skills 和 hooks，无论是模型的推理还是 Claude Code 自己的工具，一旦这些限制不再存在就会成为开销。一旦 Claude Code 添加了原生 Perforce 模式，一个拦截文件写入以在 Perforce 代码库中强制执行 p4 编辑的 hook 就变得冗余了。

团队应该期望每三到六个月进行一次有意义的配置审查，但在重大模型发布后性能感觉停滞时也值得进行一次。

分配 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、必需的代码审查流程和有限的初始访问开始，随着信心的建立而扩展。

来源：Anthropic (https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start)