--- title: 'Anthropic 大型代码库 Agent Harness 大师课(Cole 解读)' video_id: efRIrLXoOVA url: https://youtu.be/efRIrLXoOVA title_en: "Anthropic Just Dropped a Masterclass on Building Agent Harnesses (for Large Codebases)" channel: Cole Medin published: 2026-05-21 duration: "28:10" topics: [Agent 工程, Claude Code 定制扩展, MCP 与工具调用, 多 Agent 协作] noted: 2026-07-05 value: A views: '6.2万' --- [![封面](https://i.ytimg.com/vi/efRIrLXoOVA/maxresdefault.jpg)](https://youtu.be/efRIrLXoOVA) > Cole Medin · 28:10 · 发布 2026-05-21 · 6.2万次观看(截至抓取) · [观看原视频](https://youtu.be/efRIrLXoOVA) > 🔥 观众最高回放 [10:25](https://youtu.be/efRIrLXoOVA?t=625) — 讲用 stop/start hook 让 AI 层自我更新规则 ## 主旨 逐段解读 Anthropic 官方文章《How Claude Code works in large codebases》,把它偏 high-level 的观点落成 7 个可操作的 [[Harness]]（作者称 AI 层）构件,并各配一段 demo,专讲如何让编码 agent 在几万到几十万行的真实代码库里有效导航与工作。 ## 核心论点 1. **harness 与模型同等重要**——决定编码 agent 实战效果的不只是底层模型多强,而是围绕它搭的那层 context 与工具。(→ 详解 2) 2. **agent 靠 agentic search 导航,前提是有足够起始 context**——Claude Code 不建索引、不做 RAG,像工程师一样 grep;代价是它得先知道"该往哪看"。(→ 详解 1) 3. **global rules 要 lean 且 layered**——根目录规则全程加载,子目录规则按所在位置叠加;规则越堆越长反而拖垮表现。(→ 详解 3) 4. **让 AI 层自我改进**——stop hook 在会话结束、context 尚新时反思并提议规则更新,防止 CLAUDE.md 随代码库演进而变陈旧。(→ 详解 5) 5. **按路径作用域收窄 skills 与规则**——skills 是 workflow、rules 是 convention,都可 scope 到相关子目录,只在该处触发。(→ 详解 6) 6. **用 LSP 做符号级检索、用 subagent 隔离探索与编辑**——大库里 grep 慢且费 token,而探索类任务丢给独立 context 的 subagent 跑完只回摘要。(→ 详解 7、8) 7. **AI 层需要有人 own**——由小团队在"安静投入期"先搭好组织级标准再逐步推广,避免各自演化出割裂的配置。(→ 详解 9) ## 知识点详解 ### 1. 大库难题与 agentic search [02:10](https://youtu.be/efRIrLXoOVA?t=130) 简单代码库能用的 agent 策略,库一大就"当场翻车"。Anthropic 先给一堆重量级例子(千万行 monorepo、几十年遗留系统、跨数十仓库的分布式架构),意思是别觉得自家库太复杂喂不动。 Claude Code 的导航方式叫 Agentic Search:不做传统 RAG 或语义检索,也没有需要保持同步的代码库索引,而是像工程师那样用 grep 等命令行工具看目录结构、逐步定位要改的地方。 好处是没有索引要维护;代价是它"有足够起始 context 才知道往哪看"。于是后面所有策略的共同母题,就是**如何前置策展好 context**,让 agent 在复杂库里也能找准入口。 ### 2. harness 与模型同等重要,harness = AI 层 [03:04](https://youtu.be/efRIrLXoOVA?t=184) 文章的主命题:很多人过度盯着模型 benchmark,以为 Claude Code、Codex 的力量全来自底层 LLM。模型当然重要,但更重要的是围绕模型搭的生态——[[Harness]]。Cole 把它重命名为更直白的 AI 层。 关键的具象化在这里 [03:47](https://youtu.be/efRIrLXoOVA?t=227):传统代码库有两部分——code 和 tests;AI 层是**第三个组件**,包含 global rules、skills、MCP servers、subagents 等一切给 agent 提供 context 或工具的东西。 文中列出 7 样构件(含较陌生的 LSP、hooks),每一样恰好对应一条策略。全片就是逐个拆这 7 层并配 demo。 ### 3. global rules 要 lean 且 layered [05:08](https://youtu.be/efRIrLXoOVA?t=308) 在整个会话里,别的构件(hooks、skills、LSP)都是零星调用,只有 CLAUDE.md 全称 global rules 是从头到尾主导 agent 行为的地基,所以最值得投入策展。 第一条建议是 **lean**:很多人写上千行的规则文件,有研究证明这反而拖垮表现。只需核心信息——codebase 是什么、tech stack/架构一句带过、通用约定与 gotcha、跑测试和起 dev server 的命令。 第二条是 **layered**:子目录可放各自的 CLAUDE.md。根规则每次会话必加载,一旦进到某子目录编辑,就自动叠加该目录规则——这正是 [[渐进式披露]]:只加载当前工作切片需要的约定。 更进一步 [07:03](https://youtu.be/efRIrLXoOVA?t=423):若你确知只在某子目录干活,可直接 `cd` 进去再开 Claude Code。它会自动沿目录树向上逐级加载每层 CLAUDE.md(根 context 不丢),同时把工作范围收敛在此目录——由你替 agent 完成了导航。 ### 4. 目录结构不够时,建 codebase map [08:08](https://youtu.be/efRIrLXoOVA?t=488) 如果你不知道从哪下手,而目录结构本身又不足以自解释,就在全局规则里加一段 codebase map:列出各子目录并对每个写一句职责说明。 这样 agent 能帮你做"发现"——根据手上的 issue/ticket 判断该聚焦大库的哪个切片。总之定位要么你当场就知道(直接在那初始化),要么让 agent 借这张 map 帮你找。 ### 5. 用 hooks 让 AI 层自我改进 [10:51](https://youtu.be/efRIrLXoOVA?t=651) 多数团队只把 hook 当"拦截器"(如 pre-tool-use 阻止 agent 删文件),但更有价值的用法是**持续改进**,让整个 AI 层自我进化。 **stop hook**(会话结束触发)[11:19](https://youtu.be/efRIrLXoOVA?t=679):趁 context 还新,起一个 headless 会话对照本次改动,检查 CLAUDE.md 是否需要更新,把建议输出成 markdown。这解决了规则随代码演进而变陈旧、CLAUDE.md 与实际脱节的老问题——你事后再决定是否 action。 **start hook**(会话开始触发):按角色或所改代码块动态加载团队 context,比如去 Confluence 拉对应文档,或像 demo 那样注入 git 现状(未暂存改动、近期 commit)给 agent 定向。 ### 6. skills:workflow vs convention,按路径作用域 [16:52](https://youtu.be/efRIrLXoOVA?t=1012) skill 是可复用的流程/提示,大库里有几十上百种任务类型(如"加 API 端点")。它同样靠渐进式披露:先只给 agent 看 name 与 description,agent 判断相关才读完整 skill.md,不给当前任务加载无关 workflow。 多数人不知道的参数:skill 可 **scope 到特定 path**,只在相关子目录激活。等于强制"碰这块代码就带上这套 workflow"。 和子目录 CLAUDE.md 有重叠,Cole 的区分是 [17:35](https://youtu.be/efRIrLXoOVA?t=1055):**global rules 是 convention(必须遵守的规矩),skills 是 workflow(要走的流程)**。但更重要的不是二选一,而是都把约定 scope 到真正相关的代码处,别用无关 context 淹没 agent。 ### 7. LSP + MCP:符号级检索 [18:17](https://youtu.be/efRIrLXoOVA?t=1097) LSP（Language Server Protocol）就是 IDE 里 Ctrl+点击跳转定义、类型提示、查引用那套能力。把它通过一个 MCP server 暴露给 Claude Code,agent 就有了工程师在 IDE 里的导航力,补足或替代原生 grep。 demo 里 Cole 建了随库附带的本地 MCP server,提供三个检索工具。让 agent 找某符号的所有引用、并禁用 grep 逼它走符号级检索,结果精确返回"1 处定义 + 2 处引用"。 到六位数行的巨库,纯 grep 会慢且极费 token;LSP 做的是"查定义/查引用"这类定向检索,针对类、变量等符号,远比字符串匹配高效。 ### 8. subagents:分离探索与编辑 [22:08](https://youtu.be/efRIrLXoOVA?t=1328) 建议朴素但有力:用 subagent 把**探索**从**编辑**里拆出来。派一个探索任务(web 调研架构最佳实践、或勘察该改代码库哪块),subagent 在自己的 context 窗口里跑完,只把摘要回传给主会话去推理与动手。 探索动辄消耗几十万 token。若让主会话亲自做调研或勘察,等真要编辑时 context 早已臃肿。而探索往往只需要那份摘要,所以正适合外包给 subagent——这与对抗 [[Context Rot]] 是同一逻辑。 如今 Claude Code、Codex 都内置了 subagent,不必自定义:一句"开三个 subagent 分别查数据库/后端/前端"即可,它会自动调度并回收摘要。 ### 9. 组织落地:给 AI 层指派 owner [26:31](https://youtu.be/efRIrLXoOVA?t=1591) 文章结尾的组织建议:指派一个人或小团队来 champion AI 层的初始搭建。做法是先有一段"安静投入期",由少数人把 rules、skills、LSP、MCP 这整套 AI 层建好,再逐步推给全员。 价值有二:让大家从一开始就拿到一致、能出好结果的基座,避免首次使用因没有 AI 层而失望;也避免人人各自演化出割裂的 AI 层,而组织要的是统一标准。 ## 可执行步骤 - [ ] 把根 CLAUDE.md 砍到只剩核心:codebase 是什么 + tech stack/架构一句 + 通用约定与 gotcha + 跑测试和起 dev server 的命令;局部约定下沉到对应子目录 CLAUDE.md。 - [ ] 需聚焦某子目录时直接 `cd` 进去再开 Claude Code:它自动向上逐级加载每层 CLAUDE.md,同时把工作范围收敛在此目录。 - [ ] 目录结构不自解释时,在全局规则加一段 codebase map(列子目录 + 一句职责),让 agent 帮你做定位发现。 - [ ] 配一个 stop hook:会话结束跑 headless 会话对照改动检查 CLAUDE.md 是否需更新,产出 markdown 建议供事后 action。 - [ ] 对高复用任务类型(如"加 API 路由")写成 skill,并用 path 参数 scope 到相关子目录只在那激活。 - [ ] 巨库(六位数行)接一个暴露 LSP 的 MCP server,用符号级"查定义/查引用"替代纯 grep。 - [ ] 探索类任务(代码库勘察、web 调研)派给 subagent 跑,让主会话只拿回摘要再动手编辑。 ## 关联 - 深化:[[Harness]] 概念页与 [[2026-06-25-Harness为王的能动工程大师课|Harness为王的能动工程大师课]]。同为 Cole,但那篇讲"harness 占 90%"的总纲,本片聚焦**大型代码库**场景,并把 harness 拆成 Anthropic 官方的 7 个可操作层(layered CLAUDE.md、LSP-over-MCP、stop hook 自改进等),各配 demo。 - 印证:[[Context Rot]]。本片"subagent 独立 context 只回摘要"正是避免主会话上下文膨胀的具体手段,与该概念同源。 - 印证/深化:[[静态上下文与动态上下文]]。global rules 恒定加载 = 静态,skills/LSP/hooks 按需触发 = 动态;本片的 [[渐进式披露]](skill 先读 description 再读全文、子目录 CLAUDE.md 按位置叠加)是动态加载的直接演示。 - 侧重差异:[[2026-06-15-Omnigent编排多个AI编码助手的元Harness|Omnigent 元 Harness]] 讲的是 Meta Harness——编排多个助手;本片的 subagent 只是**单个 harness 内**的分工,未上抬到 meta 层。 ## 一手来源与延伸 - Anthropic 官方文章(本片逐段解读的原文):[How Claude Code works in large codebases: Best practices and where to start](https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start) - Cole 另附一个名为「helpline AI layer」的 Claude 插件(含 stop hook、explorer subagent、带 LSP 的 codebase-search MCP server 与一个作用域 skill 示例),仓库地址在视频简介;.meta.json 无 description、未联网核到稳定链接,故此处不贴。 ## 术语 - harness / AI layer（harness = AI 层:给编码 agent 的 context 与工具集合,codebase 的第三组件) - global rules（全局规则,即 CLAUDE.md) - agentic search（能动检索:无索引、grep 式的代码导航,非 RAG) - progressive disclosure（渐进式披露:按需加载 context) - LSP（Language Server Protocol,语言服务器协议:跳转定义/查引用等符号级能力) - hook（钩子:stop hook 会话结束触发、start hook 会话开始触发) - subagent（子代理:独立 context 窗口执行探索任务并回传摘要) - scoping（作用域限定:把规则/skill 绑到特定子目录) ## 金句 > "The harness matters as much as the model." → 别再只盯模型 benchmark,你真正能动手优化的是围绕模型的那层。 > "Not all expertise needs to be present in every session." → 渐进式披露的一句话本质:按需加载,别把全部规则塞满每次会话。 ## 立场与利益 片中约 12 分钟处有 JetBrains Academy 赞助贴片(可跳过);Cole 推广自建的「helpline AI layer」插件,结尾还兜售自家的企业 AI 层搭建咨询/培训服务——这些是其变现绑定。但核心 7 层框架源自 Anthropic 官方文章、可独立核验,属行业内容而非厂商话术;策略也标榜"不限编码 agent"通用。 ## 价值定位 - 适合谁:已在用 Claude Code(或 Codex 等)、代码库已到几万~几十万行、感到 agent 在大库里"迷路"的工程师。 - 解决什么:把 Anthropic 那篇偏 high-level 的官方指南,落成 7 个带 demo 的可操作层,尤其 layered CLAUDE.md、LSP-over-MCP、stop hook 自改进这几处有具体做法。 - 认知 vs 实操:偏实操(每层配 demo),但 demo 库刻意做得简单,真·超大库需自行放大;组织落地那段则偏认知。 - 与 [[2026-06-25-Harness为王的能动工程大师课|Harness为王的能动工程大师课]] 重叠,但本片独有"大型代码库"场景聚焦 + Anthropic 官方七层拆解(那篇是 harness 占 90% 的总纲)。 ## 自检问题 1. Claude Code 在大代码库里如何"找路"?它对起始 context 有什么依赖? **答案**:靠 Agentic Search——不建索引、不做 RAG,像工程师一样用 grep 等命令行工具遍历目录定位;代价是必须有足够起始 context 才知道往哪看,所以关键在前置的 context 策展。见详解 1,[02:10](https://youtu.be/efRIrLXoOVA?t=130)。 2. "lean" 和 "layered" 两条 global rules 建议分别指什么? **答案**:lean = 只写核心信息(codebase 是什么、tech stack、通用约定与 gotcha、跑测试/起 dev server 的命令),规则过长反伤表现;layered = 子目录各放 CLAUDE.md,进该目录编辑时按位置叠加,是渐进式披露。见详解 3,[05:08](https://youtu.be/efRIrLXoOVA?t=308)。 3. 为什么 stop hook 被称作让 AI 层"自我改进"的机制? **答案**:会话结束、context 尚新时它起一个 headless 会话对照本次改动,检查 CLAUDE.md 是否需更新并输出 markdown 建议,防止规则随代码库演进而变陈旧。见详解 5,[11:19](https://youtu.be/efRIrLXoOVA?t=679)。 4. subagent 分离探索与编辑,和本库其他笔记的哪个概念是同一逻辑? **答案**:与 [[Context Rot]] 同源——探索动辄几十万 token,交给独立 context 的 subagent 跑完只回摘要,避免主会话到编辑阶段时上下文已臃肿。见详解 8,[22:08](https://youtu.be/efRIrLXoOVA?t=1328)。 > [!quote] 💬 热门评论 top-13 主 + 7 回(抓取 2026-07-07) > > [2] **@FernandoBurrito**:所有权问题很关键。大多数团队会忽略它。构建AI层是一回事，但随着代码库的演变维护它才是问题所在。 👍 1 > [3] **@GhostinDebt**:说真的，这才是工程真正所在。我见过团队痴迷于原始能力，却忽略了上下文脚手架。别追分数了，开始构建框架吧。 👍 3 > [4] **@مدارالعقول**:这非常棒。对于大型代码库，我认为框架往往比模型本身更重要。 👍 11 >   ↪ **@ColeMedin(UP)**:谢谢，我同意！ 👍 1 >   ↪ **@johnmadsen37**:是的。决定看哪里以及看什么来确定上下文中的内容。有些框架设计得像Claude一样消耗token。 👍 1 > [5] **@CreatingWithJackPines**:作为一个在近200万行代码项目中的独立开发者，几万或几十万行代码听起来很可爱，这也解释了我为什么很难让一个agent完成我一周内手动就能搞定的重构。 👍 1 > [7] **@theamargupta-i2p**:框架 > 模型正是我在部署自己的运维栈时学到的。swayam（定时任务）、sandesh（内容）、sankalp（求职申请）——都是独立的线程加标签组，这样注意力不会在任务间分散。一旦我把常规任务和代码编辑混在一个聊天会话里，每个任务的质量就大幅下降。分开就好了。 👍 2 > [9] **@PuppetZombieMuppet**:自我改进的钩子是有趣的部分。大多数团队跳过这个，然后奇怪为什么他们的AI层一个季度就衰退了。 > [10] **@stephanie446677**:一如既往的好内容，Cole。只是有个问题，如果反射钩子是在无头模式下更新而不是Claude，你觉得会有问题吗？我们试过用不同的模型比如GPT或Gemini在无头模式下调用Pi？ > ——其他 5 条:感谢/夸赞([6]@lucky.cat.777、[8]@SamirSELLAMI、[11]@RicardoG500、[12]@AIwithScott、[13]@jameswhitfield3053);1 条 spam 已略 >
英文原文[1] @ColeMedin(UP):If you're interested in building your own AI second brain to save yourself hours every week, check out the Dynamous community and the new second brain course: https://dynamous.ai/second-brain-bootcamp 👍 7
[2] @FernandoBurrito:The ownership point is critical. Most teams will ignore it. Building the AI layer is one thing. Maintaining it as the codebase evolves is where it falls apart. 👍 1
[3] @GhostinDebt:Seriously, this is where the engineering actually lives. I’ve watched teams obsess over raw capability while ignoring context scaffolding. Stop chasing scores. Start building harnesses. 👍 3
[4] @مدارالعقول:This is extraordinarily good. For large codebases, I think the harness often matters more than the model itself. 👍 11
  ↪ @ColeMedin(UP):Thanks and yes I agree! 👍 1
  ↪ @johnmadsen37:Yup. What determines where and what to look at to determine what is in the context. Some harnesses are designed to eat tokens like Claude. 👍 1
[5] @CreatingWithJackPines:As the solo dev on a nearly 2M LOC project, tens or hundreds of thousands of lines sounds quaint and explains why I struggle with getting an agent to do a refactor I could have done manually in a week. 👍 1
[6] @lucky.cat.777:Way too cool. Straightforward and easy to follow the concepts you’re covering 👍 6
  ↪ @ColeMedin(UP):I appreciate it! Glad to hear :)
[7] @theamargupta-i2p:harness > model is exactly what i learned shipping my own ops stack. swayam (cron routines), sandesh (content), sankalp (job-apps) — all separate threads + tab groups so attention doesn't bleed across tasks. the moment i mixed routine fires + code edits in one cc session, per-task quality dropped hard. carve-out fixed it. 👍 2
[8] @SamirSELLAMI:video + article + git repo are super handy ingredients to make any one use AI to easy grasp ur meaty content ! Thanks 👍 2
  ↪ @ColeMedin(UP):I appreciate it a lot, you bet! 👍 1
[9] @PuppetZombieMuppet:Self-improving hooks are the interesting piece here. Most teams skip that and wonder why their AI layer decays within a quarter.
[10] @stephanie446677:Great content as always, Cole. Just a question, do you see any issues if the reflection hook was updated instead of Claude in headless mode? We tried calling Pi in headless mode using a different model like GPT or Gemini?
[11] @RicardoG500:You have really good videos! Underrated ✨ 👍 1
  ↪ @ColeMedin(UP):I appreciate it!
[12] @AIwithScott:Great video Cole. It's awesome that you always provide a repo with lots of additional value. It really helps to drive home the concepts you cover in the video. 👍 2
  ↪ @ColeMedin(UP):Thanks Scott! My pleasure :)
[13] @jameswhitfield3053:Great article. Thank you for diving in so deep on this. Thayne is crawling through the details now. 👍 1
  ↪ @ColeMedin(UP):I appreciate it James, you are welcome!