Anthropic 博客又双叒叕更新了：Claude Code 大型代码库最佳实践

公众号名称：AGI Hunt

作者名称：Anthropic

发布时间：2026-05-15 15:00

Claude 频繁更新的另一边，公司技术博客也开始密集输出了……（推测是新入职的前 CTO 们转型 IC 后开始发力了）

这一次，Anthropic 发的是一篇 Claude Code 的企业级使用指南，讲的是它在大型代码库里怎么用才好使。

博客首页

这里说的「大型代码库」，包括百万行级的 monorepo、跑了十几年的遗留系统、分散在几十个仓库的微服务架构。

甚至包括 C、C++、Java、PHP 这些的，大家通常不太会联想到 AI 编程工具的语言。

Anthropic 说，Claude Code 在这些语言上的表现，比大多数团队预期的要好不少，尤其是最近几代模型上来之后。

其中最核心的一个观点是：

Claude Code 的能力上限，取决于你怎么配它，模型本身有多强反倒是其次的。

不靠索引

Claude Code 是怎么在大型代码库里找到自己需要的东西的呢？

答案并不花哨，而且非常的简单而朴素：遍历文件系统、读文件、grep 搜索、追踪引用。跟一个真人工程师拿到一个新项目时做的事情，其实真的差不多。

它跑在开发者本地，不需要预先构建索引，也不需要把代码库上传到服务器。

而早期的 AI 编程工具走的是另一条路：RAG，先把整个代码库做 embedding，查询时检索相关代码块。这在小项目上没问题，但到了大型工程团队，就会有个致命缺陷：

索引更新的速度，永远跟不上几千个工程师提交代码的速度。

等你查的时候，拿到的可能是两周前被重命名的函数、上个 sprint 已经删掉的模块。而且没有任何提示告诉你：「这已经过期了」。

RAG 过期索引 vs Agent 实时搜索

Claude Code 的 agent 式搜索避开了这个坑。没有 embedding 管道，没有集中式索引，每个开发者的实例直接对着最新的代码工作。

当然也有代价，Claude 需要足够的起始上下文才能知道从哪里开始找。如果你让它在十亿行代码里盲搜……那 context window 还没开始干活就满了。

所以，花时间把代码库对 Claude 配置好，会有相当可观的收益**。**

配置比模型重要

这大概是整篇指南里，最为反直觉的一个观点了。

大多数团队评估 Claude Code 时，盯着的是 benchmark、测试表现。但 Anthropic 说，在实际生产中，围绕模型构建的工具生态，对最终表现的影响，会比模型本身还大。

这就好比赛马，马当然重要，但鞍具、马蹄铁、骑手的配合加在一起，对比赛结果的影响未必比马小。

Anthropic 把这套东西称为 harness，由七个扩展点组成，按构建顺序排列：

扩展层全景

从底到顶依次是：CLAUDE.md 文件、Hooks、Skills、Plugins、LSP、MCP 服务器、子 agent。

每一层都建立在前一层的基础上，而且顺序非常讲究。

打底两层

CLAUDE.md 文件是第一层，也是最基础的一层。

这是 Claude 每次会话自动加载的上下文文件。根目录放全局信息，比如「我们是什么项目、用什么框架、有哪些关键约定」。子目录放局部约定。Claude 在文件系统中移动时会自动向上遍历，逐层叠加加载。

因为每个会话都会加载 CLAUDE.md，所以内容要克制。塞太多进去反而会拖累性能。

一个常见的错误是把可复用的专业知识也塞到 CLAUDE.md 里。这些东西其实应该放到 Skills 中，按需加载就好。

CLAUDE.md 分层 + Hooks 自我进化

Hooks 是第二层。

大多数团队把 Hooks 当防护栏用，让 Claude「别做某事」。但 Anthropic 说，Hooks 更有价值的用法其实是让系统自我进化。

比如一个 stop hook，在会话结束时反思发生了什么，趁 context 还热乎，提议更新 CLAUDE.md。

一个 start hook 则可以根据开发者当前所在的模块，动态加载对应的团队配置。每个人进入自己负责的区域，自动获得正确的上下文。

对于 lint、格式化这类确定性检查，Hooks 跑脚本就行了，比让 Claude「记住一条规则」靠谱得多。

知识分发

Skills 是按需加载的专业知识包。

大型代码库有几十种不同类型的任务。把所有专业知识都塞进每个会话，既不现实也不高效。Skills 的做法是「渐进式披露」：安全审查时加载安全 Skill，文档更新时加载文档 Skill。

Skills 还可以绑定到特定目录。支付服务的部署 Skill 绑到支付目录下，在 monorepo 其他地方干活时就不会被自动加载。

Skills 按需加载 + Plugin 新人大礼包

Plugins 则解决了一个老问题：好的配置容易变成部落知识。

张三花了两周调出一套完美的 Claude 配置，但李四入职时完全不知道这些。Plugin 把 Skills、Hooks、MCP 配置打成一个包，新人第一天装上就拥有和老手一样的环境。

Plugin 更新可以通过统一的 marketplace 分发到整个组织。（这里我还是得吐槽一下：Skill 没有较好的更新机制，谁来搞一个吧，不搞我搞了……）

Anthropic 提到了一个真实的案例：

一家大型零售企业造了一个 Skill，让 Claude 直接连接他们的内部数据分析平台，从而业务分析师不用切换工具就能拉取性能数据。在大规模推广之前，他们就可以把这个打成了 Plugin 分发了出去。

精准导航

LSP（语言服务器协议）给了 Claude 和开发者在 IDE 里一样的导航能力。

你的 IDE 里大概率已经有 LSP 在跑了，提供「跳转到定义」「查找所有引用」之类的功能。把这些暴露给 Claude，它就能按符号精确导航，区分不同语言里同名函数的差别。

grep 大海捞针 vs LSP 精准定位

没有 LSP 的话，Claude 只能靠文本匹配。在大型代码库里 grep 一个常见函数名，返回几千个结果，Claude 要逐个打开文件去判断，context 就这么烧完了。

有一家企业软件公司，在全组织部署 Claude Code 之前，先在公司范围铺了 LSP 集成，专门是为了让 C 和 C++ 的代码导航更可靠。对于多语言代码库，这算是回报最高的投入之一。

不过需要注意的是：LSP 不是开箱即用的……你得自己装对应语言的 code intelligence 插件和语言服务器。

外部连接

MCP 服务器是 Claude 连接内部工具、数据源和 API 的方式。

段位最高的团队会构建 MCP 服务器，把结构化搜索暴露为 Claude 可以直接调用的工具。也有团队用 MCP 接上了内部文档系统、工单系统或数据分析平台。

不过 Anthropic 的建议是：别在基础还没搭好的时候就急着上 MCP。 先把 CLAUDE.md、Hooks、Skills 这些基本功做扎实再说。

子 Agent 侦察兵 + 施工队

子 agent 是独立的 Claude 实例，有自己的 context window。

接收一个任务，做完之后只把最终结果返回给主 agent。有些团队会先用一个只读的子 agent 把某个子系统摸清楚，把发现写成文件，然后主 agent 带着完整的上下文去做编辑。

（这不是在说我吗……）

核心价值是：把探索和编辑分开做。

在同一个会话里又探索又编辑，context 很容易就撑爆了。

代码可读性

七层扩展讲完了，接下来是怎么在实际的大型代码库里做配置。

Anthropic 总结了三个在成功部署中反复出现的模式。第一个：

让代码库对 Claude 可读。

Claude 在大型代码库里能帮多少忙，取决于它能不能找到正确的上下文。加载太多会拖累性能，加载太少 Claude 就两眼一抹黑了。

几个实践经验：

CLAUDE.md 文件要精简且分层。根目录只放指针和关键注意事项，细节下沉到子目录。

在子目录初始化 Claude，别从仓库根目录开始。

这在 monorepo 里有点反直觉，但 Claude 会自动向上遍历加载所有 CLAUDE.md 文件，根目录的上下文不会丢。好处是工作范围被精确限定在了相关的代码区域。

测试和 lint 命令也应该按子目录配置。Claude 改了一个服务就跑整个测试套件？那就等着超时吧。每个子目录的 CLAUDE.md 应该写清楚该跑哪些命令。

用 .claudeignore 排除生成文件、构建产物和第三方代码。把 permissions.deny 规则提交到 .claude/settings.json，整个团队就能自动共享这些排除规则。

对于做代码生成器开发的同学，可以在本地设置里覆盖项目级别的排除规则，不会影响其他人。

给代码库画张地图。

如果目录结构本身不够自解释，那就在根目录放一个 markdown 文件，列出每个顶层文件夹的一句话说明。几百个文件夹的代码库用分层方式：根文件描述最高层结构，子目录 CLAUDE.md 补充下一级细节。

简单场景下，直接在对话中 @-mention 具体文件或目录也行。

Anthropic 也坦承一个边界情况：几十万个文件夹、上百万个文件的代码库，或者跑在非 Git 版本控制上的遗留系统，即使分层 CLAUDE.md 也可能搞不定。这个留到后续系列文章解决。

配置要迭代

第二个模式：随模型进化，主动维护你的配置。

为当前模型写的指令，在下一代模型上可能适得其反。

旧配置拖累新模型

一个例子是，一条 CLAUDE.md 规则要求 Claude 每次重构只改一个文件。在老模型上确实有效，能帮它保持专注。但新模型已经完全能做跨文件的协调编辑了，这条规则反而变成了枷锁。

同样的道理，为弥补模型弱点而写的 Skills 和 Hooks，模型一升级就可能变成多余的负担。

Anthropic 还举了个例子：有团队写了个 Hook，在每次文件写入时自动执行 p4 edit（Perforce 版本控制命令）。后来 Claude Code 原生支持了 Perforce 模式，这个 Hook 就没用了。

建议每 3-6 个月做一次完整的配置审查。每次大模型发布后也值得检查一轮。

如果你觉得 Claude Code 的表现到了某个瓶颈怎么也上不去……问题可能不在模型，而在你的配置没跟上。

毕竟模型都已经往前跑了，你的 CLAUDE.md 可能还停在三个月前。

得有人管

第三个模式：指定专人负责 Claude Code 的管理和推广。

技术配置做得再好，也撑不起全组织的采用。

Anthropic 观察到一个共同点：推广最快的组织，在大面积开放之前，都是先有一小队人把基础设施搭好了。

有人管 vs 野蛮生长

有的公司是两三个工程师在 rollout 前就造好了一整套 Plugins 和 MCP。有的甚至组了专门管理 AI 编程工具的团队，一切就绪才开放访问。

效果是：开发者第一次接触 Claude Code 就能跑通。

第一印象如果是「这东西不好使」，后面要翻盘就太难了。

目前承担这个职能的通常在「开发者体验」或「开发者效率」部门下面。一个正在浮现的新角色叫 Agent Manager：半 PM 半工程师，专门负责管理 Claude Code 生态。

规模更小的组织至少需要一个 DRI（直接责任人）：一个人负责配置、权限策略、Plugin 管理、CLAUDE.md 规范，并且有拍板权。

自底向上的采用能激发热情，但缺了组织层面的收敛，好用的实践就会变成部落知识，采用率到某个点就上不去了。

治理先行

大组织，尤其是受监管行业的公司，治理问题会更早出现。

谁控制哪些 Skills 和 Plugins 可用？怎么防止几千个工程师各自造轮子？AI 生成的代码怎么走和人类代码相同的审查流程？

Anthropic 的建议是从小开始：一组预定义的已批准 Skills、必须的代码审查流程、有限的初始访问权限。随着信心的增长再逐步放开。

最顺畅的部署，来自那些早期就成立了跨职能工作组的组织：工程、信息安全、治理的代表坐到一起，共同定义需求，一起画路线图。

三步部署

Anthropic 把企业级部署分为三个阶段：

部署三阶段

基础设施阶段：小团队先搭好工具链、Plugins、MCP，把地基打好。

试点阶段：有限的初始访问，配上已经定义好的审批流程。

规模阶段：在已建立的治理体系和约定基础上，再大面积推广。

适用边界

最后一个问题：什么样的代码库能用这套方案呢？

Claude Code 设计的前提是常规的软件工程环境：工程师是主要贡献者、仓库用 Git、目录结构标准。大多数大型代码库都符合。

但也有一些非常规场景需要额外的配置工作：带大量二进制资产的游戏引擎、非 Git 版本控制的环境、非工程师往代码库里贡献内容的情况。

这些场景下，Anthropic 的 Applied AI 团队可以直接和工程团队合作，把通用模式翻译成具体组织的定制方案。

快速启动清单

◇ ◆ ◇

整篇指南读下来，Anthropic 想传达的核心逻辑是：模型能力是地板，配置质量才是天花板。

七层扩展，三步部署，先搞基础再上规模，有人负责，定期翻新。

这倒也算不上太过新鲜的道理，可能许多各位也已经在这么做了。但 A 厂这也算是第一个把企业级部署的经验写得这么系统，并分享出来的。

这个系列后面还会持续更新，Anthropic 说的是，更极端场景（超大规模文件系统、非 Git 版本控制）的实践指南正在路上。

本号也会继续追踪，分享出来，敬请期待。

我是 John，感谢阅读。进 Claude Code 交流群可加我（公众号后台有联系方式）后备注 cc。

◇ ◆ ◇

指南链接：

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

内容效果不满意？点此反馈