Cole Medin · 28:10 · 发布 2026-05-21 · 6.2万次观看(截至抓取) · 观看原视频
🔥 观众最高回放 10:25 — 讲用 stop/start hook 让 AI 层自我更新规则
主旨
逐段解读 Anthropic 官方文章《How Claude Code works in large codebases》,把它偏 high-level 的观点落成 7 个可操作的 Harness（作者称 AI 层）构件,并各配一段 demo,专讲如何让编码 agent 在几万到几十万行的真实代码库里有效导航与工作。
核心论点
- harness 与模型同等重要——决定编码 agent 实战效果的不只是底层模型多强,而是围绕它搭的那层 context 与工具。(→ 详解 2)
- agent 靠 agentic search 导航,前提是有足够起始 context——Claude Code 不建索引、不做 RAG,像工程师一样 grep;代价是它得先知道”该往哪看”。(→ 详解 1)
- global rules 要 lean 且 layered——根目录规则全程加载,子目录规则按所在位置叠加;规则越堆越长反而拖垮表现。(→ 详解 3)
- 让 AI 层自我改进——stop hook 在会话结束、context 尚新时反思并提议规则更新,防止 CLAUDE.md 随代码库演进而变陈旧。(→ 详解 5)
- 按路径作用域收窄 skills 与规则——skills 是 workflow、rules 是 convention,都可 scope 到相关子目录,只在该处触发。(→ 详解 6)
- 用 LSP 做符号级检索、用 subagent 隔离探索与编辑——大库里 grep 慢且费 token,而探索类任务丢给独立 context 的 subagent 跑完只回摘要。(→ 详解 7、8)
- AI 层需要有人 own——由小团队在”安静投入期”先搭好组织级标准再逐步推广,避免各自演化出割裂的配置。(→ 详解 9)
知识点详解
1. 大库难题与 agentic search 02:10
简单代码库能用的 agent 策略,库一大就”当场翻车”。Anthropic 先给一堆重量级例子(千万行 monorepo、几十年遗留系统、跨数十仓库的分布式架构),意思是别觉得自家库太复杂喂不动。
Claude Code 的导航方式叫 Agentic Search:不做传统 RAG 或语义检索,也没有需要保持同步的代码库索引,而是像工程师那样用 grep 等命令行工具看目录结构、逐步定位要改的地方。
好处是没有索引要维护;代价是它”有足够起始 context 才知道往哪看”。于是后面所有策略的共同母题,就是如何前置策展好 context,让 agent 在复杂库里也能找准入口。
2. harness 与模型同等重要,harness = AI 层 03:04
文章的主命题:很多人过度盯着模型 benchmark,以为 Claude Code、Codex 的力量全来自底层 LLM。模型当然重要,但更重要的是围绕模型搭的生态——Harness。Cole 把它重命名为更直白的 AI 层。
关键的具象化在这里 03:47:传统代码库有两部分——code 和 tests;AI 层是第三个组件,包含 global rules、skills、MCP servers、subagents 等一切给 agent 提供 context 或工具的东西。
文中列出 7 样构件(含较陌生的 LSP、hooks),每一样恰好对应一条策略。全片就是逐个拆这 7 层并配 demo。
3. global rules 要 lean 且 layered 05:08
在整个会话里,别的构件(hooks、skills、LSP)都是零星调用,只有 CLAUDE.md 全称 global rules 是从头到尾主导 agent 行为的地基,所以最值得投入策展。
第一条建议是 lean:很多人写上千行的规则文件,有研究证明这反而拖垮表现。只需核心信息——codebase 是什么、tech stack/架构一句带过、通用约定与 gotcha、跑测试和起 dev server 的命令。
第二条是 layered:子目录可放各自的 CLAUDE.md。根规则每次会话必加载,一旦进到某子目录编辑,就自动叠加该目录规则——这正是 渐进式披露:只加载当前工作切片需要的约定。
更进一步 07:03:若你确知只在某子目录干活,可直接 cd 进去再开 Claude Code。它会自动沿目录树向上逐级加载每层 CLAUDE.md(根 context 不丢),同时把工作范围收敛在此目录——由你替 agent 完成了导航。
4. 目录结构不够时,建 codebase map 08:08
如果你不知道从哪下手,而目录结构本身又不足以自解释,就在全局规则里加一段 codebase map:列出各子目录并对每个写一句职责说明。
这样 agent 能帮你做”发现”——根据手上的 issue/ticket 判断该聚焦大库的哪个切片。总之定位要么你当场就知道(直接在那初始化),要么让 agent 借这张 map 帮你找。
5. 用 hooks 让 AI 层自我改进 10:51
多数团队只把 hook 当”拦截器”(如 pre-tool-use 阻止 agent 删文件),但更有价值的用法是持续改进,让整个 AI 层自我进化。
stop hook(会话结束触发)11:19:趁 context 还新,起一个 headless 会话对照本次改动,检查 CLAUDE.md 是否需要更新,把建议输出成 markdown。这解决了规则随代码演进而变陈旧、CLAUDE.md 与实际脱节的老问题——你事后再决定是否 action。
start hook(会话开始触发):按角色或所改代码块动态加载团队 context,比如去 Confluence 拉对应文档,或像 demo 那样注入 git 现状(未暂存改动、近期 commit)给 agent 定向。
6. skills:workflow vs convention,按路径作用域 16:52
skill 是可复用的流程/提示,大库里有几十上百种任务类型(如”加 API 端点”)。它同样靠渐进式披露:先只给 agent 看 name 与 description,agent 判断相关才读完整 skill.md,不给当前任务加载无关 workflow。
多数人不知道的参数:skill 可 scope 到特定 path,只在相关子目录激活。等于强制”碰这块代码就带上这套 workflow”。
和子目录 CLAUDE.md 有重叠,Cole 的区分是 17:35:global rules 是 convention(必须遵守的规矩),skills 是 workflow(要走的流程)。但更重要的不是二选一,而是都把约定 scope 到真正相关的代码处,别用无关 context 淹没 agent。
7. LSP + MCP:符号级检索 18:17
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
建议朴素但有力:用 subagent 把探索从编辑里拆出来。派一个探索任务(web 调研架构最佳实践、或勘察该改代码库哪块),subagent 在自己的 context 窗口里跑完,只把摘要回传给主会话去推理与动手。
探索动辄消耗几十万 token。若让主会话亲自做调研或勘察,等真要编辑时 context 早已臃肿。而探索往往只需要那份摘要,所以正适合外包给 subagent——这与对抗 Context Rot 是同一逻辑。
如今 Claude Code、Codex 都内置了 subagent,不必自定义:一句”开三个 subagent 分别查数据库/后端/前端”即可,它会自动调度并回收摘要。
9. 组织落地:给 AI 层指派 owner 26:31
文章结尾的组织建议:指派一个人或小团队来 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 概念页与 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 按位置叠加)是动态加载的直接演示。
- 侧重差异:Omnigent 元 Harness 讲的是 Meta Harness——编排多个助手;本片的 subagent 只是单个 harness 内的分工,未上抬到 meta 层。
一手来源与延伸
- Anthropic 官方文章(本片逐段解读的原文):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 库刻意做得简单,真·超大库需自行放大;组织落地那段则偏认知。
- 与 Harness为王的能动工程大师课 重叠,但本片独有”大型代码库”场景聚焦 + Anthropic 官方七层拆解(那篇是 harness 占 90% 的总纲)。
自检问题
- Claude Code 在大代码库里如何”找路”?它对起始 context 有什么依赖? 答案:靠 Agentic Search——不建索引、不做 RAG,像工程师一样用 grep 等命令行工具遍历目录定位;代价是必须有足够起始 context 才知道往哪看,所以关键在前置的 context 策展。见详解 1,02:10。
- “lean” 和 “layered” 两条 global rules 建议分别指什么? 答案:lean = 只写核心信息(codebase 是什么、tech stack、通用约定与 gotcha、跑测试/起 dev server 的命令),规则过长反伤表现;layered = 子目录各放 CLAUDE.md,进该目录编辑时按位置叠加,是渐进式披露。见详解 3,05:08。
- 为什么 stop hook 被称作让 AI 层”自我改进”的机制? 答案:会话结束、context 尚新时它起一个 headless 会话对照本次改动,检查 CLAUDE.md 是否需更新并输出 markdown 建议,防止规则随代码库演进而变陈旧。见详解 5,11:19。
- subagent 分离探索与编辑,和本库其他笔记的哪个概念是同一逻辑? 答案:与 Context Rot 同源——探索动辄几十万 token,交给独立 context 的 subagent 跑完只回摘要,避免主会话到编辑阶段时上下文已臃肿。见详解 8,22:08。
💬 热门评论 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!