公司大型代码库里用 Claude Code，头几天顺手，跨服务一改就难受。下面是读 Anthropic 博客文章 How Claude Code works in large codebases 的收获。
一、导航：不靠索引，靠「现查现用」
大代码库的第一个硬约束：没有任何窗口装得下整个仓库。Opus 即便开到 1M context，面对持续增长的 monorepo 加依赖树，依然只能看局部。
不少工具（如 Cursor、Copilot 的 semantic search）会先对代码建 embedding 索引，再按语义召回；大库里索引可能滞后，且「相似」不等于「就是那个符号」。
Claude Code 不走这条路，而是用 agentic search：在本机 ls、读文件、grep、沿引用现查，始终对着当前工作区。
Anthropic 把这套做法叫 agentic search，核心表述是：Claude Code 导航代码库的方式 「像软件工程师那样去」——遍历文件系统、读文件、用 grep 找需要的内容、沿引用跨文件追踪；在开发者本机运行，不需要构建、维护或上传 codebase 索引。
官方把两类路径的差异归纳如下:
RAG / 语义索引：典型失效场景
- 索引跟不上提交：embedding pipeline can't keep up with active engineering teams（活跃团队持续提交时，索引难以同步）。
- 查询读到的是「旧的内容」：开发者发起查询时，索引往往仍是 weeks, days, or even hours before 的代码库快照。
- 召回内容已失真：例如两周前已重命名的函数、上个 sprint 已删除的模块仍被返回。
- 过期无感知：上述过期信息被当作有效上下文喂给模型，with no indication that either is out of date。
Agentic search：官方强调的规避点
- 无中心化索引：不必构建、维护或上传 codebase index。
- 始终对着 live codebase：Each developer's instance works from the live codebase——每次搜索都基于本机当前文件。
| 官方对比维度 | RAG / 语义索引 | Agentic search |
|---|---|---|
| 索引 | 需构建、维护，难跟上提交节奏 | 无需 codebase index；对应当前工作区 |
| 召回风险 | 过期函数/已删模块，且无过期提示 | 现查现用，避免上述失效模式 |
| 前置条件 | 索引建完才好用 | 足够的 starting context（CLAUDE.md、子目录、LSP 等） |
| 适用边界 | 大库 + 模糊全局搜索易撞 context 上限 | 有范围的探索与修改更稳 |
因此 context 爆掉时，官方提示先查的不是「模型够不够大」，而是 起点 context 与仓库可导航性——后文 harness 一节就是在回答这件事。
二、Harness：模型是烈马，harness 是马具
博客里有一句话：The harness matters as much as the model（harness 和模型一样重要）。
换个说法：模型是烈马——能力强、跑得快；harness 是马具（鞍、辔、缰）——决定这匹马在大库这条路上能不能被驾驭、往哪跑、会不会跑偏。
很多人评估 Claude Code 时只看 benchmark、模型版本、套餐档位；真正进生产后，马鞍辔头怎么配——记忆怎么注入、什么时候自动跑 lint、团队 SOP 怎么分发——往往比换一匹更烈的马更影响体感。
上一节讲的 starting context，落到工程里就是这套 harness：先得 CLAUDE.md 立住项目约定，再挂 Hooks 做确定性动作与自我修正，再用 Skills 按需加载专长，最后用 Plugins / MCP 把个人配置变成团队能力；LSP、Subagents 则补导航与拆任务。下图、下表按此列出各层职责。
| 组件 | 加载方式 | 该干什么 | 常见误用 |
|---|---|---|---|
| CLAUDE.md | 每次会话自动读 | 项目约定、关键坑、目录指针 | 把本该做成 skill 的长流程全塞进来 |
| Hooks | 事件触发 | 确定性检查、会话结束反思、动态加载上下文 | 用 prompt 重复提醒「记得 format」 |
| Skills | 任务相关时才加载 | 专项 SOP（迁移、发布、安全审查） | 与 CLAUDE.md 职责混淆 |
| Plugins | 安装后团队共享 | 打包 skill + hook + MCP 配置 | 好配置只留在高手本机 |
| LSP | 配置后常驻 | 按符号跳转、找引用 | 以为装了插件就自动有语言服务 |
| MCP | 配置后常驻 | 接 Slack、工单、内网文档 | 基础没搭好就先接一堆 server |
| Subagents | 调用时派生 | 探索与编辑分窗，只回传摘要 | 同一 session 里又读又改又大改 |
简言之，harness 不单是「把团队经验写成默认值」——官方把它定义为围在模型外的扩展生态：约定入口、确定性自动化、按需专长、工具链接入，以及大库里的符号导航与任务拆分；在生产里，这套外装对体感的影响，往往不亚于换模型。
三、让仓库「可被读懂」：三个反复出现的模式
博客里有一句定调的话：Claude 在处理大型代码库时的能力， 受限于它能否找到正确的上下文（背景信息）。——上下文给太多，每次会话都被噪声淹没；给太少，agentic search 只能盲搜。下面三类模式，就是在这两者之间找平衡。
模式一：让代码库可导航
Making the codebase navigable at scale：让大规模（或大型）代码库变得易于导航/查阅。
对应 harness 里的 CLAUDE.md、LSP、ignore，直接缓解「搜错地方、context 被无关输出冲垮」。
-
CLAUDE.md 瘦而分层
根目录只放指针与致命坑，模块约定进子目录；其余写进根文件会变成噪声，挤掉真正有用的规则。
-
在子目录启动
cd services/payments && claude，不要总在 repo 根；向上走树仍会加载根级 CLAUDE.md，但默认视野落在当前服务。 -
子目录写清测试 / lint
改哪个服务就跑哪条命令，避免全仓 suite 把 context 冲垮；编译型 monorepo 依赖深时要按构建图单独定。
-
ignore +
permissions.deny进 git生成物、构建产物、第三方代码一律排除，全队同一套降噪。
-
代码库地图
目录名说不清故事时，根目录用 markdown 给每个顶层文件夹一句话；顶层上百个则分层，细节放进子目录 CLAUDE.md。
-
上 LSP
常见符号
grep可能上千命中；LSP 在读文件前按符号过滤。C/C++ 等栈有客户先 org-wide 铺 LSP，再 rollout Claude Code。
官方也提到了：数十万文件夹、非 Git 等极端场景，分层 CLAUDE.md 也会失效，系列后续文章会单独讲。
模式二：把配置当活文件维护
Actively maintaining CLAUDE.md as models evolve：随着模型的不断演进，积极维护 CLAUDE.md 文件。
对应 harness 里的 Hooks、Skills。
官方指出的问题：随着模型能力演进，为当前这一代写的指令，换到下一代后可能起反作用——曾经帮 Claude 度过难点的 CLAUDE.md，在新模型上线后可能不再必要，甚至主动限制它。
怎么治——下面三条是同一套动作的不同环节，不是并列的三种可选方案：
-
定期审查 — 何时查：
每 3–6 个月做一次完整审查；或 major 模型发布后体感 plateau 时，先审 CLAUDE.md 与 skill，再考虑换模型。
-
狠删文档 — 查完怎么改：
Ruthlessly edit your CLAUDE.md，对每一行问「删掉后 Claude 还会不会做对」——会，就删。
-
让 harness 自更新 — 怎么持续：
用 stop hook 在会话结束时反思并提议更新 CLAUDE.md，减少只靠人工堆规则。
模式三：组织层有人对 harness 负责
Assigning ownership for Claude Code management and adoption：明确 Claude Code 的管理与落地（采用）的责任人。
对应 harness 里的 Plugins、MCP、marketplace 与治理。
官方指出的问题：单靠技术配置推不动推广——模式一、二在个人仓库里能见效，但若没有人把 harness 汇编、分发、保鲜，好配置会停在高手本机，新人仍是「阉割版」体验。自下而上容易碎片化（人人各写一套 skill），知识停在部落里，推广会触顶；若开发者第一次用起来就挫败，后面很难翻盘。大企业还要尽早面对治理：谁控制哪些 skill/plugin 可上架、如何避免千人重复造轮子、AI 生成代码是否走同样 code review。
怎么治——下面三条同样是同一套推广链的不同环节：
-
先铺基建再放量 — 铺开前：
大面积开放前，用小团队把 plugin、MCP、目录约定接好，保证新人第一次就顺。
-
指定责任人 — 日常谁维护：
设 DRI（或 Agent Manager），对配置、marketplace、CLAUDE.md 规范有拍板权并负责保鲜。
-
收拢实践与治理 — 怎么扩、怎么管：
汇编推广共用 skill/plugin；大企业尽早跨职能定治理，先批准清单 + code review + 小范围试点，再放大。
因此，三个模式是一条链：仓库可读 → 配置随模型更新 → 组织有人维护并分发——缺任何一环，前两节配好的 agentic search 与 harness 都难在全公司站稳。
四、经常容易犯的错误
「换 Opus 就能扛住大库」
窗口变大，只延缓「全库塞不下」；导航与 harness 没跟上，照样在错误文件里烧 token。
「CLAUDE.md 写得越全越好」
它每次会话都加载，过长会变成对所有任务的噪声；专项流程应下沉到 skill，用渐进式披露按需加载。
「MCP 接得越多越好」
MCP 在栈里偏后；前面 CLAUDE.md、hook、skill、plugin 没稳，接进来的内网数据只会加重混乱。官方对 retail 客户的例子是：先有一个连内部分析平台的 skill，验证价值后再 plugin 全公司分发——顺序是 skill → plugin → 规模化，不是反过来。
「大改动靠一个超长 prompt 一次做完」
跨几十个文件的迁移/重构，更可靠的是 plan 与实现分会话、探索用 subagent 只回传 findings、批量同质改动用
/batch并行 worktree。本质是把「读库」和「改库」从同一个 context 里拆开，跟人查资料、写代码分两阶段一样。
「Claude Code 万能」
它默认的世界观是：Git、工程师为主贡献者、常规目录结构。游戏引擎海量二进制资产、非常规 VCS、非工程师主导改库，需要额外定制；不是不能做，但别指望开箱即用同一套 harness。
五、若你负责在团队落地，会怎么排优先级
- 子目录工作 + 根 CLAUDE.md 瘦身（<200 行量级）+ 子目录 CLAUDE.md —— 成本低，立刻改善「搜错地方」和「规则淹没」。
- 语言栈对应的 LSP plugin + language server —— 多语言/符号重的库 ROI 最高。
- ignore / deny 规则进仓库 —— 全团队统一降噪。
- 高频流程做成 skill，再 plugin 进 marketplace —— 把个人本机配置变成组织资产。
- hook 做确定性门禁 + stop hook 反哺 CLAUDE.md —— 减少「靠模型记得跑 lint」。
- MCP 接内网系统 —— 在前五步稳了之后，接 Slack/Jira/内网 wiki 等。
- 指定 harness DRI + 季度审查节奏 —— 防止配置随模型进化腐烂。
模型选型当然要做，但在这套顺序里，它更像换马；前面几步是在配马具。
六、收尾
大库里用 Claude Code，关键从来不是「读完整个 repo」——谁也读不完。有用的是：每次对着你本机那份代码现查，再靠 CLAUDE.md、LSP、skill 这些把入口和边界说清楚。
体验变差，常见原因也不是模型突然不行，而是规则写太长、总在根目录开、测试命令跑全仓、好配置只留在某个人电脑上。换 Opus、开 Max，解决不了这些。
别一上来全公司推广，也别在根目录堆一千行 CLAUDE.md 当万能药。
参考
- Anthropic：How Claude Code works in large codebases
