Anthropic 在 Claude Code at Scale 系列首篇把客户大规模部署的真实经验摊开:RAG 是反模式,5 个扩展点 + 2 个增援组件构成 harness,而一个 million-line monorepo 的胜负,80% 在配置里,20% 在那个被任命的 DRI 身上。
2026 年 5 月 14 日,Anthropic 在 claude.com/blog 发表 Claude Code at Scale 系列首篇。论断刺耳:在百万行代码库里,胜负不在模型 benchmark,而在围绕模型搭建的 harness。CLAUDE.md / hooks / skills / plugins / MCP servers 5 个扩展点 + LSP / subagents 2 个增援组件 + 1 个 DRI,决定一个 million-line monorepo 上的 AI 编程是放大生产力还是放大混乱。
大多数 AI 编程工具默认把整个代码库 embed 进向量数据库,然后在查询时检索 chunks。这在小项目可行,在百万行 monorepo 上就崩溃 —— embedding pipeline 跟不上数千名工程师每天的提交速度。
Claude Code 选择另一条路。它像人类工程师一样工作:遍历文件系统、读文件、用 grep 精确定位、跟随跨文件引用。本地运行在开发者机器上,没有需要维护的索引,没有需要上传到服务器的代码库快照,完全在 live codebase 上工作。这条路在 Anthropic 内部有个名字,叫 agentic search。
Anthropic 给 RAG-based 工具下的判词很直接:"By the time a developer queries the index, it reflects the codebase as it previously existed weeks, days, or even hours before. Retrieval then returns a function the team renamed two weeks ago, or references a module that was deleted in the last sprint, with no indication that either is out of date."—— 检索结果是几周前的代码库快照,renamed 的函数照旧返回,deleted 的模块照旧引用,没有任何过期警告。
这条路有 tradeoff:Claude 需要足够的起始 context 才能知道去哪儿找。问"在十亿行代码库里所有 X pattern 的实例",上下文窗口先撑爆。胜负被推到了"代码库是否被设置好"这件事上 —— 投入设置的团队拿到更好的结果,没投入的拿到 Claude 像无头苍蝇一样 grep。
这是一个架构选择,不是工程优化。RAG 把代码库当 数据库,Claude Code 把代码库当 文件系统。工程师不会查向量数据库找代码,Claude 也不应该。Anthropic 的论断:在 active 工程团队 + 大代码库的双重条件下,任何"集中式索引"都会输给"分布式 live 文件系统"。
Anthropic 把这个观察直接点名为"most common misconception"—— 关于 Claude Code 最常见的误解,是以为它的能力等同于背后那个模型。团队聚焦 benchmark,聚焦测试任务上的表现,觉得这就是天花板。
论断刚好相反:"In practice, the ecosystem built around the model—the harness—determines how Claude Code performs more than the model alone." 围绕模型搭建的生态 —— harness —— 比模型本身更决定结果。
harness 由 5 个核心扩展点(CLAUDE.md / hooks / skills / plugins / MCP servers)+ 2 个增援组件(LSP / subagents)组成。Anthropic 强调:"The order in which teams build them matters, as each layer builds on what came before." 搭建顺序不能乱,每一层都建立在前一层之上。
| 组件 | 是什么 | 何时加载 | 常见误用 |
|---|---|---|---|
| CLAUDE.md | 每会话自动读的 context 文件 | 每会话 | 把可复用的专业知识塞进来 —— 应该用 skill |
| Hooks | 关键时刻触发的脚本 | 事件触发 | 把应该自动化的事写成 prompt 反复嘱咐 |
| Skills | 特定任务的打包指令 | 按需匹配 | 把所有内容堆进 CLAUDE.md |
| Plugins | 打包好的 skills / hooks / MCP | 配置后常驻 | 让好配置只在小圈子流传(tribal) |
| LSP | 语言服务器实时智能 | 配置后常驻 | 以为它会自动启用 —— 必须显式集成 |
| MCP Servers | 连接外部工具 / 数据 / API | 配置后常驻 | 基础没就位就先建 MCP |
| Subagents | 独立 context 的 Claude 实例 | 调用时 | 把探索和编辑放同一个 session |
"Teams focus on a model's benchmarks.
The harness is what actually decides whether Claude Code works at scale."
Anthropic 给的核心约束:"Claude's ability to help in a large codebase is bounded by its ability to find the right context." 上下文窗口塞太多,表现退化;塞太少,模型在百万文件里盲航。Claude 表现的天花板,被它"找对 context"的能力封顶。
一线团队反复出现的设置 pattern,Anthropic 总结成五条 —— 按杠杆从大到小排:
大多数 monorepo 工具假设你在 repo root 操作。Claude Code 的建议恰恰相反 —— 在你真正要改的子目录里 init。Anthropic 把这条单独拎出来,因为它最违背直觉:"In monorepos, this can feel counterintuitive because tooling often assumes root access."
关键机制:Claude 会自动沿目录树往上走,把路径上的每一份 CLAUDE.md 都加载进来。root-level 的全局 context 不会丢,子目录的本地约定也获得加载 —— 但 Claude 的 working scope 收缩到了它真正要改的部分。
配套的纪律:把 test 和 lint 命令 scope 到子目录。当 Claude 只改了一个 service,跑全套测试会超时,还会把不相关的输出灌满 context。子目录级 CLAUDE.md 应该写明这个子目录用什么命令。在 service-oriented codebase 上这工作得很好;深度跨目录依赖的编译语言 monorepo,这件事会难一些。
"grep 一个常见函数名在大代码库里返回数千匹配,Claude 烧 context 一个个打开文件去判断哪个是真正要找的。"这是 Anthropic 给的具体痛点。LSP 解决方案:先做符号 resolution,再返回精确匹配,filtering 在 Claude 读任何文件之前就发生。
具体客户案例:Anthropic 提到一家企业软件公司,在 Claude Code 组织级 rollout 之前,专门先部署了 LSP 集成,目的是让 C 和 C++ 代码库的导航在大规模下可靠。多语言代码库,LSP 是最高杠杆的投入之一。
.claude/settings.json 里的 permissions.deny 规则应该 commit 进 repo。这样团队每个人都获得相同的"噪音过滤",不用各自配置。例外:开发代码生成器本身的工程师 —— 他们可以在 local settings 里 override 项目级排除,不影响团队其他人。
对于代码没按常规目录结构组织的组织,一份轻量级 markdown 文件放在 repo root,列出每个 top-level folder + 一句话描述,给 Claude 一份它可以先扫一眼再决定打开哪些文件的"目录索引"。文件夹数百个的代码库,这个 codebase map 应该分层 —— root 写到 top level,子目录的 CLAUDE.md 提供下一级细节,按需加载。
多数团队把扩展点理解成"通用工具的特定版本" —— CLAUDE.md = readme,hooks = pre-commit,skills = 自定义 prompt 模板。Anthropic 的实操经验把每一层都拉到了不同方向。误解 vs 真实用法,逐条对照:
| 组件 | 团队普遍以为的用法 | Anthropic 实操中真正的杠杆 |
|---|---|---|
| CLAUDE.md | 装项目所有信息的大文档 | 根级只写 pointer + 致命 gotcha,具体约定下沉子目录 |
| Hooks | 防止 Claude 写错代码的检查脚本 | 让配置自我改进 — stop hook 总结 session,提议 CLAUDE.md 更新 |
| Skills | 团队 prompt 模板的封装 | 按路径绑定 — payments 团队的 deploy skill 只在 payments 目录加载 |
| Plugins | skill 的更大版本 | 解决"好配置部落化" — 新人 day 1 同步全套生态 |
| LSP | "我们已经在 IDE 里有了,不用再配置" | Claude 不会自动用,必须显式集成 + 安装 language server |
| MCP | 给 Claude 接 OpenAPI 那种 | 最 sophisticated 团队用 MCP 暴露"结构化搜索"成 Claude 可调用工具 |
| Subagents | 并行任务调度器 | read-only subagent 先 map 子系统、写文件,主 agent 拿完整图景再编辑 |
大多数团队把 hooks 当 pre-commit 用 —— 跑 linter、跑 formatter、防止 Claude 提交破坏构建的代码。Anthropic 强调:"Most teams think of hooks as scripts that prevent Claude from doing something wrong, but their more valuable use is continuous improvement." 真正的杠杆是让配置自我改进。
"A hook that intercepted file writes to enforce p4 edit in a Perforce codebase became redundant once Claude Code added native Perforce mode." — Anthropic · 关于 hooks 会随模型 / 工具迭代失效
在大代码库里,task type 几十种,每种都把专业知识塞进 CLAUDE.md 会让 context 严重过载。skill 的核心机制是 progressive disclosure —— 只在 task 匹配时才把专业知识加载进来。绑定路径让这件事自动化:payments 团队的 deploy skill 绑到 payments 目录,Claude 进入这个目录,skill 才被加载。其他人在 monorepo 别处工作,完全感知不到。
Anthropic 提到的客户案例:一家大型零售公司给业务分析师做了一个 skill,连接 Claude 到内部分析平台,让业务能不离开 workflow 就拉到性能数据。这个 skill 没有写成全公司可用 —— 而是先打包成 plugin,在向业务全面 rollout 之前先内部分发。
多数团队把 MCP 当 OpenAPI gateway 用 —— Claude 通过 MCP 调内部服务、查 ticket、读文档。Anthropic 提到 最 sophisticated 的团队反过来做这件事:用 MCP 把代码库的"结构化搜索"(按符号 / 按引用 / 按调用图)暴露成 Claude 可以直接 call 的工具。配合 LSP + agentic search,Claude 的"找对位置"能力被推到了人类工程师之上。
主 agent 一边探索代码库 + 一边写改动,会出现两个问题:① context 被探索过程灌满,编辑时已经没有空间装代码细节;② 探索阶段的 noise(grep 输出、读文件、wrong turns)污染编辑阶段的判断。解法是用一个独立 context 的 subagent 先 map 子系统、把发现写到一个 markdown 文件、再让主 agent 在完整图景下编辑。
真正决定 Claude Code 在大型组织里能否落地的,不是 plugin marketplace 有多丰富,而是组织层有没有人在统筹。Anthropic 给出的核心观察:"The rollouts that spread fastest had a dedicated infrastructure investment before broad access." —— 上线之前就把基础设施搭好,而不是在采用过程中应急救火。
三种组织安排,Anthropic 按效果排序:
只投技术配置,没有 DRI,没有 rollout 策略
给 Claude Code 配置一个 DRI(Directly Responsible Individual)
上线前配好工具栈 + 工程 / InfoSec / Governance 工作组
这是 Anthropic 明确点名的纪律 —— 每 3 到 6 个月做一次 meaningful configuration review,major model release 之后必做一次。原因是模型在进步,旧的 CLAUDE.md 会从助力变束缚。
Anthropic 给的两个具体例子:
为旧模型的 limitation 写的强制规则,在新模型上变成限制
为弥补 Claude Code 本身限制写的 hook,新版本工具原生支持后该删
把 configuration review 写进 cadence,跟代码库本身一起演进
大型组织,尤其是受监管行业,治理问题来得很早 —— 谁批准 skill?如何防止数千工程师重复造轮子?AI 生成代码如何走 review?Anthropic 提到最顺的部署是把工程、InfoSec、Governance 拉到同一张桌子,先定 rollout roadmap,再开放 access。"Starting with a defined set of approved skills, required code review processes, limited initial access, and expanding as confidence builds."
Anthropic 这篇文章本质上是把"AI 编程工具的胜负"重新框定 —— 不在"哪个模型 SWE-bench 跑得高",而在"你的 harness 把代码库设置得多 navigable"。
5 个扩展点 + 2 个增援组件 + 1 个 DRI + 每 3-6 个月 review 一次。这套打法的核心反直觉是:模型这一年比上一年强 X% 可能没有意义,但你的 CLAUDE.md 这一年比去年精简 50% 一定有意义。模型是 Anthropic 在迭代的资产,harness 是你的组织在迭代的资产。前者会自动升级,后者不会。
Q1 答案:RAG 假设 embedding pipeline 能跟上提交速度,大代码库 + active 团队下做不到。Claude Code 用 agentic search 绕开 —— grep + 跟随引用,在 live 代码库上工作,没有索引滞后。
Q2 答案:CLAUDE.md 第一(每会话基础),然后 hooks(让 CLAUDE.md 自我改进),然后 skills(按需 expertise)。MCP / plugins 在基础没就位前不要做 —— Anthropic 明确点名这是常见误用。
Q3 答案:Claude 自动沿目录树往上走加载所有 CLAUDE.md,root context 不会丢。子目录 init 让 working scope 收到真正要改的部分,test/lint 命令也对得上。在 monorepo 这是必选,不是 nice-to-have。
Q4 答案:真正杠杆是让配置自我演进 —— stop hook 反思 session 提议 CLAUDE.md 更新,start hook 按开发者/模块动态加载 context。lint/format 自动化只是 hook 价值的 20%。
Q5 答案:skill 是单个专业能力(progressive disclosure 按需加载);plugin 是把 skills + hooks + MCP 打包成可分发包,解决"好配置部落化"。Plugin 让团队 working setup 跨组织流动,marketplace 让 DRI 治理可执行。
Q6 答案:大概率部分失效。专为旧模型 limitation 写的规则会限制新模型(例:强制单文件 refactor)。每 3-6 个月或 major release 后做 review,删 over-constrained 规则、删 redundant hook,Anthropic 把这条写进了官方指南。
你不需要等公司层面的 rollout。从最小可行集开始,四件事按顺序:
① 在你 owning 的 service 子目录建 CLAUDE.md(只写本地约定 + 关键 gotcha,根级文档放 pointer)
② cd 到子目录后再 claude init,不在 repo root 启动
③ 在 .claude/settings.json 排除生成文件,commit 进 repo,团队同步获益
④ 部署 LSP(如果是 C / C++ / Java / TypeScript 等 typed 语言,这是最高杠杆)
关键纪律:先把自己手上的子目录跑顺,再去推团队。子目录的成功是 plugin / DRI 的存在理由。
你的杠杆是把"好配置"打包成可分发资产。三件事:
① 把根 CLAUDE.md 精简成"指针 + critical gotcha",所有具体约定下沉到子目录
② 把团队反复出现的 task type 收成 skill(按子目录绑定 path,而不是全局加载)
③ 把 skills + hooks + MCP 打包成 plugin,分发给团队 / 写进 onboarding
关键纪律:标准化的 CLAUDE.md 层级 + curated skill set,比给团队每人一份完美 prompt 重要十倍。"好配置部落化"是大代码库 AI 编程的最大隐性损耗。
你需要的不是更多 plugin,是 DRI + cross-functional working group。四件事按顺序:
① 任命一个 agent manager(PM / Eng 混合角色),授权 settings / permissions / marketplace 决策权
② 上线前组好工程 + InfoSec + Governance 工作组,先定 roadmap 再开放 access
③ Day 1 就部署好 plugins + MCP + LSP,新人入职就有完整生态
④ 写入 review 节奏:每 3-6 个月 / major model release 后必做
关键纪律:rollout 之前的 dedicated infrastructure 投入,比 rollout 期间应急救火便宜十倍。Anthropic 提到的"扩散最快的部署"全部满足这个条件。
| # | 信号 | 触发判断 / 动作 |
|---|---|---|
| 1 | CLAUDE.md 根文件 > 200 行 | context 过载 → 下沉到子目录,根级只留 pointer + gotcha |
| 2 | session 末尾 context window > 80% | scope 太宽 → 用 subagent 分离探索/编辑 |
| 3 | Claude 反复读相同的文件 | 缺 codebase map 或 .claudeignore 没排除 → 补充 |
| 4 | grep 返回 1000+ 匹配 | 没装 LSP → 部署 language server,改按 symbol 搜索 |
| 5 | test 跑全套 + 输出 > 1000 行 | test 命令没 scope 到子目录 → 在子目录 CLAUDE.md 写明命令 |
| 6 | 新人 day 1 自己装 skills / MCP | plugin marketplace 没就位 → 打包配置成 plugin 分发 |
| 7 | CLAUDE.md 里"避免 X、不要 Y"规则越积越多 | 需做配置 review → 可能在束缚新模型,删 over-constrained |
| 8 | 团队内同一个能力被多人独立实现 | 好配置在部落化 → 缺 DRI / plugin 通道 |
| 9 | Code review 没把 AI-generated diff 单独 flag | governance 没跟上 → 跨职能工作组介入 |
| 10 | 没人定期跑配置审计 | 每 3-6 个月 review 缺位 → 写进 cadence,major release 后必做 |
"模型在变,harness 在变,但'谁负责'这件事必须有答案。
That answer is what scales — not the model."
· Anthropic Blog · How Claude Code works in large codebases: Best practices and where to start · 2026.05.14 · claude.com/blog
· Anthropic Docs · Best Practices for Claude Code · code.claude.com/docs
· Anthropic Blog · Claude Code at Scale 系列(Legal Industry / Financial Services / Sales Workflows) · 2026.05 · claude.com/blog
· Zoox · Amit Navindgi 提供的客户反馈(致谢内引用)
· Anthropic Applied AI Team · Alon Krifcher / Charmaine Lee / Chris Concannon / Harsh Patel / Henrique Savelli / Jason Schwartz / Jonah Dueck / Kirby Kohlmorgen