Anthropic 百万行代码库的官方最佳实践

随着AI 编程智能体的越来越深入到日常工作，相信你也遇到了大型项目和和小型代码库完全不同的场景。

正好最近也是在做大型项目的重构开发，刷到这篇来自 Anthropic 官方的文章。

系统梳理了 Claude Code 在大规模代码库中的运作机制、Harness 架构的七个扩展点，以及在项目中成功使用的三种配置模式。

本文介绍的模式具有普遍适用性，可以为考虑采用 AI 智能体编程的团队提供一个业内领先公司的工程实践。

如何浏览大型项目的代码

首先需要解决的问题就是如何浏览代码库。

Claude Code 会像开发工程师一样，遍历目录、读取代码文件、用 grep 精确查找所需内容、在代码库中追踪引用关系。

记得早期大家都是依赖 RAG 检索：对整个代码库做嵌入索引，查询时检索相关片段。

但是在大规模场景下，索引的速度跟不上提交速度。

等到查询时，它反映的已经是几天、几周甚至几小时前的代码了。

返回的结果可能是两周前已重命名的函数，或者是上个版本中已删除的模块，而且没有任何过时提示。

所以 Claude Code 的解决方案是采用 智能（Agentic）搜索。

不需要RAG模式的嵌入（embedding），没有集中式索引，无论多少工程师同时提交新代码，每个人的实例都直接基于实时代码库工作。

相应的代价就是：Claude 需要足够的起始上下文，才能知道去哪找。

这就意味着 Claude 导航质量取决于代码库的配置程度，核心就是 CLAUDE.md 文件和 Skills 的分层上下文设计。

如果在十亿行代码库里模糊搜索，就会遇到上下文窗口的限制，而导致大模型什么都干不了。

Harness框架与模型同等重要

一个常见的误解是：Claude Code 的能力完全取决于所用模型，因为 Opus 4.7 是目前最好的大模型。

实际上，围绕模型构建的 Harness 生态（即框架），对实际表现的影响超过模型本身。

Anthropic 把 Harness 拆成七个组件，从基础到高级，层层递进。

第一层：CLAUDE.md 文件

CLAUDE.md 是 Claude 每个会话自动读取的上下文文件。

根目录文件把握全局，子目录文件描述本地惯例。

因为每个会话都会加载，内容必须聚焦在广泛适用的信息上，否则会拖累性能。

→ CLAUDE.md 文档：https://code.claude.com/docs/zh-CN/memory

第二层：Hooks 让配置自我改进

大多数团队把 Hooks 看作防止 Claude 犯错的脚本。

但更有价值的用法是持续改进。

Stop Hook 可以在上下文还新鲜时，反思刚才的会话，提出 CLAUDE.md 更新建议。

Start Hook 可以动态加载团队专属上下文，每个开发者打开对应模块时自动获得正确配置。

对于 linting、格式化等自动化检查，Hooks 比让 Claude 记住指令更可靠、更一致。

→ Hooks 指南：https://code.claude.com/docs/zh-CN/hooks-guide

在这篇文章中：万字深研 ｜Harness 工程实践：指令遵从率 20%，Hook 执行率 100%，

研发团队就充分使用了Claude Code 的Hook 机制，设计了8 门状态机（8-Gate State Machine），横跨七个阶段，16个生命周期，来保证智能体在大型开发项目中的指令遵循率。

第三层：Skills 按需加载专业知识

大型代码库有几十种任务类型，不可能每种专业知识都在每个会话中常驻。

Skills 通过渐进式披露解决这个问题：把专业工作流和领域知识卸载，只在任务需要时加载。

比如安全审查 Skill 在 Claude 评估代码漏洞时才加载，文档处理 Skill 在代码变更需要更新文档时才加载。

Skills 还可以限定在特定路径。

支付服务团队把部署 Skill 绑定到自己的目录，别人在仓库其他位置工作时它绝不会自动加载。

→ Skills 文档：https://code.claude.com/docs/zh-CN/skills

第四层：使用插件分发成熟解决方案

大型代码库的通病是好的配置容易停留在内部团队层面。

插件机制把 Skills、Hooks 和 MCP 配置打包成一个可安装包，新工程师安装后第一天就能获得和资深工程师完全相同的上下文和能力。

插件的更新可以通过插件托管市场统一分发。

Anthropic 举了一个例子：某大型零售组织构建了一个 Skill，把 Claude 连接到内部分析平台，业务分析师不用离开工作流就能拉取绩效数据。

他们在全公司推广前，先把这个 Skill 打包成插件分发。

→ Plugins 文档：https://code.claude.com/docs/zh-CN/plugins

第五层：语言服务器协议（LSP） 集成，按函数/变量名查找

大型代码库的 IDE 通常已经在运行语言服务器协议（LSP），提供"跳转到定义"和"查找所有引用"。

把这一能力暴露给 Claude，它就获得了符号级精确导航：跟随函数调用找到定义、跨文件追踪引用、区分不同语言中的同名函数。

没有 LSP，Claude 只做文本模式匹配，很容易命中错误的符号。

一家大型企业软件公司在全组织推广 Claude Code 之前，先部署了 LSP 集成，目的就是让 C 和 C++ 代码的导航在大规模下保持可靠。

对于多语言代码库，这是投资回报率最高的配置之一。

→ 代码智能 Plugin：https://code.claude.com/docs/zh-CN/discover-plugins#code-intelligence

我之前的文章有介绍，开源的项目实现了类似的功能：GitNexus 把代码库变成知识图谱｜审核 AI 产出更清晰，改 Bug 更精准。

可以将整个代码库索引成一个知识图谱，追踪每一个依赖、调用链、功能集群和执行流程，然后通过 MCP 协议暴露给 AI 代理。

第六层：MCP 服务器，连接一切

MCP 服务器让 Claude 连接它原本无法触及的内部工具、数据源和 API。

成熟的团队把结构化搜索暴露为 Claude 可以直接调用的工具。

其他团队则连接内部文档、工单系统或分析平台。

这一层功能和操作，相信大家多少都用过。

比如通过MCP连接腾讯文档：从生成到分享：我把 OpenClaw + 腾讯文档技能跑通了。

又比如 WorkBuddy 默认提供的连接器管理，以及可自定义的连接器。

第七层：子智能体（Subagents），探索与编辑分离

Subagent 是拥有独立上下文窗口的隔离 Claude 实例。

它接收任务、完成工作、只把最终结果返回给父 Agent。

一些团队的做法是：先启动一个只读 Subagent 梳理子系统并把发现写入文件，然后主 Agent 在掌握全局后执行编辑。

→ Subagents 文档：https://code.claude.com/docs/zh-CN/sub-agents

为了更直观地对比，官方给了一张表：

三种配置模式

1. 让代码库可导航

Claude 的能力上限，取决于它能否找到正确上下文。

加载太多会拖性能，加载太少会让它盲目探索。

下面六条是成功部署中较好的做法：

CLAUDE.md 精简且分层。

Claude 遍历目录树时叠加加载，根文件只管全局指针和关键注意事项，其他内容都会变成噪声。

在子目录中初始化，不在仓库根目录。

作用域限定在任务实际相关的部分时效果最好。

Claude 会自动向上遍历并加载沿途的每个 CLAUDE.md，所以根级别上下文不会丢。

按子目录限定测试和 lint 命令。

只改了一个服务就跑全量测试，会超时并浪费上下文。

子目录级的 CLAUDE.md 应指定该部分适用的命令。

用 排除生成文件、构建产物和第三方代码。

在.claude/settings.json中提交permissions.deny规则，排除项受版本控制，团队每个人自动获得相同的噪声过滤。

开发代码生成器的人可以在本地设置中覆盖项目级排除项，不影响其他人。

当目录结构不够清晰时，构建代码库地图。

在仓库根目录放一个轻量 markdown 文件，列出每个顶层文件夹及一行描述。

对于数百个顶层文件夹的代码库，用分层方式：根文件只描述最高层，子目录 CLAUDE.md 提供下一层细节。

使用语言服务协议（LSP），按名称精确定位。

grep 查找命令常见函数名可能返回几千个结果，Claude 会浪费上下文逐个打开判断。

LSP 只返回同一函数名/变量名的引用，过滤在读取之前就完成了。

需要注意的是，分层的 CLAUDE.md 方案在极端情况下也会失效，比如几十万文件夹、几百万文件的代码库，或非 Git 版本控制的遗留系统。

2. 随模型进化维护 CLAUDE.md

为当前模型写的规则，可能在下一个模型上变成束缚。

比如一条告诉 Claude 每次只改一个文件的规则，帮助了早期模型不跑偏，但会阻止新模型做它擅长的跨文件协同编辑。

为弥补特定模型限制而构建的 Skills 和 Hooks，一旦限制不存在了，就成了额外开销。

在 Perforce 代码库中拦截写入执行p4 edit的 Hook，在 Claude Code 增加原生 Perforce 模式后就多余了。

团队应该每三到六个月做一次配置审查，重大模型版本发布后如果感觉性能停滞，也值得做一次。

3. 分配责任人

这一条是非技术的建议，组织结构要适应AI 编程带来的变革。

推广AI 编程最快的团队，都在广泛开放前做了基础设施投入。

一家公司的几位工程师提前构建了全套 Plugin 和 MCP，第一天就可用。

另一家公司有专门管理 AI 编码工具的完整团队，推广前就准备好了基础设施。

这两种情况下，开发者的第一次接触就是高效的，采用自然扩散。

做这种事的人通常归属在开发者体验或开发者生产力部门。

一个正在出现的新角色是智能体经理（Agent Manager）：混合 PM 和工程师职能，专门管理 Claude Code 生态。

如果还没有专门团队，最小可行版本是一个开发负责人：对 Claude Code 配置拥有所有权的人，有权决定设置、权限策略、Plugin 市场和 CLAUDE.md 惯例，并有责任保持它们最新。

对于大型组织，最容易出现以下治理问题：

谁控制哪些 Skills 和 Plugins 可用？怎么防止成千上万的工程师重复造轮子？AI 生成的代码怎么走和人工代码一样的审查流程？

Anthropic 的建议是：从已批准的 Skills、强制代码审查和有限初始访问开始，随着信心增强逐步扩展。

早期就建立跨职能工作组，把工程、信息安全、治理代表拉到一起定义需求、制定路线图。

比如这篇在国内碧桂园研发团队落地的实践经验总结：AI Code 企业落地问题：成本失控与无法持续记忆上下文及解决方案。

在展开 AI Coding 后，实现了改进过程的可观测，然后在此基础上解决了 Token 消耗过大，上下文优化问题。

最后，给出一份 Claude Code 的官方检查清单：

原文：

https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start

推荐：

Lazyweb 免费的 25.7 万截图库｜让 AI 写出好看的前端页面

Multica：让 AI 智能体变为你的员工

给 AI 装上真实浏览器：camofox-browser 实战

基于 DeepSeek 的编程智能体 TUI

ChatGPT 里的"哥布林（goblins）"是怎么来的？

不用一个违禁词 让 Claude 说出炸药配方｜红队攻击实录

大模型黑箱揭秘：GPT、Claude、Gemini、Grok、Hermes 系统提示词全公开

jcode 深度解析：纯 Rust 打造，它凭什么号称「最强 Coding Agent」？

从73.7到89.5，HALO 智能体用"轨迹分析"实现了递归自我进化

小米模型 MiMo V2.5 全系列 Pro · TTS 免费用

让 AI 帮你修 bug，结果它把整个代码重写了一遍

没人整理过的 DeepSeek 进化史：25篇论文里的技术蜕变

给 OpenClaw 接入10000+工具和数据，为你盯盘，给出独家策略

Claude Design 系统提示词被泄露：AI 如何成为你的专业设计师