Nate Herk · 26:42 · 发布 2026-06-09 · 5.9万次观看(截至抓取) · 观看原视频
🔥 观众最高回放 18:57 — 视频里 Nate 强调 subagent 的真正价值是”让每个 agent 是一名专家”,主会话+一队专精 agent 取代”一个万能助理”;这一段也是 GitHub 上 awesome-claude-code-subagents 仓库被首次点名的位置。
主旨
把 Claude Code 的 Subagent 从”听过名字”用到”按场景自己造”:搞清它与 skill 的边界(干净上下文 vs 主会话内调用)、用 YAML 描述精准触发、用 read-only 工具集合做权限隔离,并学会把任务切成可并行的派单。
核心论点
- Subagent 之所以存在,核心价值是让主会话上下文不被淹——任何”我以后不会回看的输出”都应该派给派生 agent,主会话只收一份小摘要。(→ 详解1、详解2)
- Subagent 与 skill 几乎完全同形(都是带 YAML front matter 的 markdown),唯一硬差别是 subagent 拥有干净上下文窗口且可换模型、可并行,skill 在主会话内运行。(→ 详解3、详解4)
- Progressive disclosure 决定触发准度:Claude Code 只在判定描述匹配时才会把 subagent 全文加载并执行,描述要精准到能区分”什么时候用”与”什么时候不用”,否则会要么哑火要么误触发。(→ 详解5)
- Subagent 的安全护栏不是”提示它别做”,而是给它一份”只能调的工具白名单”——显式声明 read-only 或限定 MCP 是默认动作,凡 agent 读得到就要假设它会读。(→ 详解6)
- 专家化是 subagent 的真正杠杆:与其”一个智能体配一堆 skill 啥都干”,不如”一个智能体 + 一队专精 subagent 各自负责一件事”,Opus 当 boss、Haiku 当廉价劳动力,既省钱又干净。(→ 详解7、详解8)
知识点详解
1. 什么是 subagent:主会话当编排器,subagent 干脏活 01:42
Nate 开篇演示让 Claude Code 同时派生五个不同人格的 subagent(退休老师、COO、企业老板、出版人、工程师)并行审书稿——重点不是”五个 agent”,而是主会话是 orchestrator,subagent 只跟主会话单线汇报:Nate 直接引述主会话的角色陈述——“I am the one who’s actually talking to Nate, but what I can do is I can spin up a bunch of sub agents I can only talk to me”(01:47)。
这个单线汇报意味着 subagent 的产出不会互相串门,也不会回写到主对话;主会话拿到的是一段总结,而不是五千行原始输出。Nate 把这个结构归纳成”主会话 = orchestrator,subagent = 可以被换模型、换人设、换技能的独立子进程”。
实际收益是上下文污染被切断——主会话里”研究 fireflies.ai”那种动辄好几千 token 的网页抓取、文件读取,丢给 subagent 干之后主会话的 token 几乎不动,主对话里看到的只是一句”研究完成,核心要点如下”。
2. 为什么需要 subagent:让主会话上下文保持干净 02:04
Nate 给出的最直接理由是”it keeps your context clean”——他展示了一段主会话从 0 token 涨到 48,000 token 的过程,指出”上下文会逐渐被信息污染”(02:04)。一旦你打算读一堆文件、爬一堆网页、跑一堆命令,主会话的有效注意力就会被稀释,后面的回答质量跟着掉。
subagent 的解法是给主会话一个”隔离沙箱”:派生出去的 subagent 在自己独立的 chat 里干完全部脏活——读 30 个文件、跑 5 个 grep、调用 web 工具——完成后只把要点摘要回给主会话(03:05)。这套机制在概念上等价于把Harness的”上下文工程”推到了派生进程层——主会话与 subagent 各自只承担自己角色所需的注意力。
Nate 在收尾总结时再次强调这条线:“if you want to get better results by letting a fresh agent review your work or do work in parallel”(25:38)——subagent 不只是”省 token”,更是”得到更好结果”。
3. 内置 vs 自定义 subagent:都是 markdown,差别在谁写的 03:32
Nate 把”内置”与”自定义”做了一次切分:内置 subagent 是 Claude Code 写好、放在 engine 里的(比如你看到 main 上面写着 “general purpose” 那个),自定义 subagent 是你自己写在 .claude/agents/*.md 里的 markdown 文件(03:32)。
关键澄清:内置的”general purpose”也是靠不同 prompt 区分的派生 agent,不是真的”通用”——你给主会话一句”让一个初学者视角审稿”,主会话就会派生一个被提示成”你是 58 岁退休老师 Linda”的 general purpose agent。所以”我之前没建过 subagent 也用过 subagent”是常态。
真正的”自定义”门槛很低:Nate 调出自己 agents 目录里的 clickup-searcher.md(05:10),整份文件就是一段 YAML 头 + 一段说明文字——YAML 头里写名字、描述、模型、颜色,正文写它该做什么。
4. Subagent 与 skill 几乎同形,差别在上下文 04:35
Nate 明确给出”a sub-agent is the exact same actual tangible thing as a skill.md file”(04:35)——两份文件都是带 YAML front matter 的 markdown,落地路径、加载机制、YAML 字段几乎一致。
差别只在运行时:“the main difference really is that one has a clean context window and one doesn’t”(08:53)。skill 是在主会话里触发的——主会话看到一段指令、调出 skill 文档照着做、上下文继续累加;subagent 是被派生出去的——主会话写一份任务、subagent 在自己干净的 chat 里跑完全部步骤、只回传摘要。
另一个并行能力差别:subagent 可以”a ton of different sub agents in parallel”(08:56)地派出去,skill 不行(主会话一次只能做一件事)。反过来,Nate 强调”sub-agents can invoke skills, and skills can invoke sub agents”(08:21)——两者不是竞争关系,可以互调。
5. Progressive disclosure:描述决定 subagent 是否会被触发 05:43
Nate 把 YAML front matter 称为 progressive disclosure(05:43)——Claude Code 不会一上来把所有 subagent 全文塞进上下文,而是先扫一遍 YAML 头里的名字 + 描述,判断这条描述是否匹配当前用户指令,匹配才会把对应 subagent 全文加载并执行。不匹配就完全不读,省 token。
这条机制反过来决定了你写 subagent 的核心动作:写好描述。Nate 直接说”the description is really important”(06:37)——它既是触发器(让 Claude Code 知道该不该用),也是护栏(让 Claude Code 知道不该用的时候别用)。
实操上 N 给的调优口诀是”边用边修”——subagent 该触发没触发、不该触发乱触发,都回去改描述。在他的实操演示里,他建好 plan-roaster(对商业计划唱反调的子代理)后第一次调用它没有触发,他就让 Claude Code 回去读自己刚写的描述,告诉他”为什么这次没触发”,然后让 Claude Code 改描述,再试一次(16:15 前后)。
想要”频繁触发”也可以在描述里加”use proactively if you want it to fire off”(08:07)——但这是个开关,要用对场景。
6. 安全护栏:read-only 工具集 + 显式 MCP 列表 20:50
Nate 给的安全原则很硬:“if my AI could touch data or could read data, I have to assume that it will”(20:50)——这是最小权限在 subagent 层的具体落地,不是”提示它别做”,而是”显式声明它不能做”。
实现路径在 YAML front matter 的 tools 字段:给 subagent 一个白名单,只列它能用的工具——比如 plan-roaster 就只被允许用 read-only 工具(grep/read/glob),它就跑不了 Write、Edit、Bash(写文件)。也可以反向用 disallowed tools 字段禁止特定工具;更细粒度还能限定允许的 MCP server,或者干脆不允许任何 MCP(06:00 前后 Nate 演示高级选项)。
Nate 还提了一个”反向用法”——下载别人开源的 subagent 时,先用一个 read-only 的”subagent 验证器”去读它、看是否被注入恶意指令(19:30 前后),确认干净再装到自己的 .claude/agents/。
7. Subagent 当专家:一个 boss + 一队专精 agent 18:23
Nate 的核心理念是”have each AI be a specialist”(18:23)。主会话可以借 skill 把自己变成”做 LinkedIn 帖子很在行”或”做脚本很在行”的多面手,但真要处理复杂任务,subagent 才是”真专家”——它有专门的人设、专门的工具集、专门的经验,可以做成安全审计、单元测试、文档生成、数据库架构、SQL 查询等一个个独立角色。
这套架构在 Nate 看来是”借别人的专业知识”:GitHub 上有 awesome-claude-code-subagents 仓库(19:06)聚合了 API 设计师、后端工程师、GraphQL 架构师、各语言专家等,直接拷进自己的 agents 目录就能用——别人花一周调好的 subagent,对你就是一行拷贝。
收尾的”一张幻灯片”总结里 Nate 把这层抽象成”smart lead + 一队便宜 worker”:Opus 跑主会话,Haiku 跑一堆 subagent,各自干自己最擅长的活(25:34)。
8. 省钱:Opus 当 boss,Haiku 当苦力 21:27
从省钱角度,Nate 给的实战场景是:如果你需要从 300 页研究报告里挑三个有趣的点,你不需要 Opus 跑全文——“delegate that to a Haiku sub-agent to read everything and then send back just a small summary to your main session”(21:27)。Haiku 比 Opus 便宜一个量级,做这种纯摘取任务质量也够。
Nate 提的另一个节省成本的杠杆是 max turns(21:56)——给 subagent 设一个”最多 10 轮对话”的上限,避免它进入研究循环或代码审查循环里烧 token 烧到停不下来。他自己说他很少用这个(因为他做的研究任务一般都很窄),但当作”防失控”的兜底是合理的。
9. 什么时候该用 subagent:看”主会话里你会不会再读它” 22:25
Nate 给了一条自检式判断标准——“is this about to dump a pile of stuff into my chat that I’ll never read again”(22:25):如果一项任务的输出是”我会再读它”的(短的、关键的),那就放主会话里;如果是”我以后再也不会读它”的(大段抓取、整篇审读),那就派给 subagent。
他给的五条触发信号:① 要读很多文件;② 要吐一大段输出;③ 是会重复做的任务(适合做自定义 subagent);④ 是独立可并行的(15 章书稿各章独立审读);⑤ 要一个无偏见的审稿人(subagent 醒来无记忆、没上下文污染,review 更诚实)(22:40 前后)。
反过来说,不该用 subagent 的情况也有明确边界:Nate 强调”sub agents do not work that way”(23:29)——subagent 之间互相不通信,只是”sub agent and main session, not like a one-to-many”(23:33);如果任务需要 subagent 之间对话、需要 subagent 反过来向你提问、需要 subagent 拿到主会话的完整上下文,那应该用 Agent Teams 而不是 subagent(23:36)。
10. Project vs Global:在哪个目录决定谁能用 09:48
subagent 的可见范围由落盘位置决定:项目级(.claude/agents/*.md)只在本项目可用——Nate 的 Herc 2 项目里那一堆 clickup-searcher、carousel-planner 都是项目级(09:48);全局级(~/.claude/agents/*.md 或用户级目录)在本机所有项目里都能用——“global ones are usable by every product on your machine”(10:20)。
这个区分和 Claude Code 里的 skill、MCP server、hook 是一套规则——全都是”项目级”+“全局级”两档,语义完全一致。Nate 给的实操建议是默认放项目级(他推荐 project scope 而不是 user/local),除非你明确想让某个 subagent 跨项目共用;把 GitHub 仓库分享给同事时,“if I share this GitHub repo to someone, they won’t get that skill”(10:31)——仓库里只有项目级 subagent,不会自动带上你机器上的全局 subagent。markdown 文件本身的可移植性让两者可以一键互转。
11. Dynamic Workflows:Opus 4.8 之后的”一把梭”并行 23:46
视频最后一节讲一个相对新的特性——dynamic workflows。它是 Opus 4.8 之后引入的”动态编排”,主会话在判定任务够大时直接 spin up 一整批 subagent 并行跑(23:46)。
Nate 自己测试时一次性派了 41 个 subagent,另一次派了 210 个——后者”ate through my context or sorry, it ate through my session limit like crazy”(24:10 前后),所以这是双刃剑:用对了能横扫大任务,用错了 session 额度直接烧穿。触发词后来被官方从”workflow”改成了”ultra code”——你如果不想让 Claude Code 动不动就派一大堆 subagent,描述里避开这两个词。
Nate 给的安全用法的”一张幻灯片”是:dynamic workflow 适合那种”我有一堆独立可并行的脏活要做”的场景——比如 100 个长报告各要一份摘要、100 段代码各要一次 review——而对日常小任务则明确”just because this feature is awesome … that doesn’t mean to force it”(25:14)。
可执行步骤
- 列出你最近一周在 Claude Code 里做过的所有任务,把每条标一个”我以后还会再读这段输出吗”——标”不会”的全派给 subagent。
- 在
.claude/agents/(或全局目录)里建一个plan-roaster.md:YAML 头里 description 写明”trigger on ‘roast my plan’ / ‘review my plan’“;tools 限定 read-only;model 选 haiku。正文写”扮演对立面审查者,挑出每个漏洞与失败模式”。 - 把一个常做的脏活(比如从一堆文件里找出提到某关键词的几段)写成自定义 subagent,在 description 里同时给一个明确的触发词与一条不触发的反例,以最大化 progressive disclosure 的命中率。
- 给自己已经建好的 subagent 跑一轮”边用边修”:主动用三句它应该触发的指令、三句不该触发的指令,统计触发准确率,回头改 description。
- 装一个 read-only subagent 专门用来”审别人分享的 subagent 是否有 prompt injection”——只允许 Read/Grep/Glob,跑过之后才把别人的 markdown 拷进自己的 agents 目录。
- 测一下 dynamic workflow 触发:对一段明确”100 个独立单元”的任务说”ultra code”试试;在主会话 context 快满时主动停手,看 session limit 的实际开销。
关联
- 印证 Subagent:本片把 subagent 的”上下文独立 + 并行执行 + 可换模型”三角定义与 Subagent 词条一致(后者出自同主讲的另一门高阶课);本片的实操增量是 YAML 描述的 progressive disclosure 调优路径与 read-only 工具集,词条暂未覆盖。
- 印证 上下文隔离:本片 1-2 详解讲的”主会话不被研究/抓取/审稿污染 = subagent 在自己 chat 里干完全部脏活只回摘要”与 上下文隔离 词条(出自 CC高阶课·子代理)定义一致;词条强调”独占干净窗口干脏活”,本片加上”读到的 token 不回流到主会话”这条量化的对照。
- 印证 最小权限:本片 6.详解给的”显式 tools 白名单 + disallowed tools + 限定 MCP”实现路径,正是 最小权限 词条(出自 CC高阶课·子代理)的安全模式;词条没给 YAML 字段名,本片补了
tools:/disallowedTools:的具体配置形态。 - 互补 Harness:本片与 Harness 的关系是”harness 的一个子集”——harness 涵盖 rules/skills/hooks/MCP/CLAUDE.md,subagent 只是其中一个可派生的执行单元;但本片给的具体 YAML 字段(
name/description/tools/model/color/memory)是 harness 其他组件没有的。 - 互补 渐进式披露:本片 5.详解的 progressive disclosure(子代理名+描述 = 触发器,只有匹配才加载全文)是 渐进式披露 在 Claude Code 派生 agent 层的具体落地;但 渐进式披露 词条说的是知识库检索场景(笔记场景),本片说的是 agent 工具调用场景——同一思路在不同层面的应用。
- 进阶 2026-06-18-从提示到导演：把Claude Code agent编排成可复用工作流:本片是 subagent 的”基础概念 + 实操入门”,那份笔记是同主题的进阶版——后者讲 plan→implement→validate 三段串行 + handoff 文档 + dumb zone 应对,本片没碰;先看本片把基础打牢,再去看那份能理解 subagent 之外的更大设计面。
一手来源与延伸
- 视频中点名的资源:
awesome-claude-code-subagentsGitHub 仓库(视频 19:06 提到,作为”借别人专业 subagent”的入口):聚合了 API 设计师、后端工程师、GraphQL 架构师、各语言专家等可直接复用的 subagent 集合- Anthropic 官方 Claude Code subagent 文档(视频 06:00 前后提到 “the actual Claude Code documentation on the sub-agents”):可查到 YAML 全部可配字段(tools/disallowedTools/mcp servers/skills/memory 等)
- Nate 自己之前那条 “ranking all favorite Claude Code features” 视频(视频 01:12 提到):subagent 在他的 Top features 里排第 6,本片是那条视频的”subagent 详解篇”
术语
- Subagent(子代理):由主 agent 派生、上下文独立的子进程,可换模型、可并行
- Built-in subagent(内置子代理):Claude Code 自带、由 main session 凭 prompt 区分的派生 agent(如 general purpose、Explore、Plan)
- Custom subagent(自定义子代理):用户写在
.claude/agents/*.md的 markdown 文件,YAML 头定义元数据,正文定义行为 - Progressive disclosure(渐进披露):Claude Code 只在描述匹配时才加载 subagent/skill 全文的检索机制
- YAML front matter(子代理头):subagent markdown 文件顶部的元数据块,字段包括 name/description/tools/model/color/memory
- Project scope vs Global scope(项目级 vs 全局级):subagent 落盘在
.claude/agents/(项目级)还是用户级目录(全局级),决定可见范围 - max turns(最大轮次):subagent 派生出去后能跑多少轮对话的上限,用来防失控
- Dynamic workflow(动态工作流):Opus 4.8 之后引入的”主会话判定任务大、一次性派一批 subagent 并行跑”的机制,后改触发词为”ultra code”
- Read-only subagent(只读子代理):tools 字段只列只读工具的 subagent,用作权限隔离
金句
“the main session is basically the orchestrator.” (01:42) → 一句话钉死 subagent 的架构地位——主会话不是”另一个 worker”,它是把任务拆给 subagent 的指挥棒,所有 subagent 产出汇到主会话再对外汇报。 “it keeps your context clean.” (02:04) → subagent 存在最直接的理由——把”以后不会再看的输出”挡在主会话外,主会话注意力才能留给下一轮决策。 “the description is really important.” (06:37) → progressive disclosure 把描述从”说明文字”变成”触发器”,写得不准就哑火或误触发——这条把”写 subagent”从写 prompt 改写成写 trigger spec。 “if my AI could touch data or could read data, I have to assume that it will.” (20:50) → 安全护栏不是”提示它别做”,而是”显式声明它不能做”——这是 subagent 安全性的根本态度,适用于所有 agent 体系。 “is this about to dump a pile of stuff into my chat that I’ll never read again?” (22:25) → 判断”该派 subagent 还是该放主会话”的最朴素问句,答案 Yes 即派,No 即留——这条比”看任务类型”更直接,免去脑内分类。 “just because this feature is awesome … that doesn’t mean to force it.” (25:14) → 反过度工程的一句——subagent 不是炫技工具,该用就用、不该用就别用,强派 subagent 反而出更差结果。
立场与利益
Nate 经营一个 AI 自动化社区(本片 description 头两条链接就是该社区的免费社群与 Plus 会员入口,带 el=claude-code-subagents 追踪参数),靠免费社群 + 付费会员变现;同时他推 UppitAI 服务、Hostinger 联盟链接(视频中念出”NATEHERK”折扣码)、Glaido 语音转文字免费月、播客申请入口等。这是一份完全服务于他个人业务的实操教程视频——教你怎么用 Claude Code subagent,目的是拉你进他的社区。
- 与利益同向(待印证):“专家化 subagent > 万能 skill 堆叠”——Nate 自己卖 AI OS 课程,这种”每个 agent 是一类专家”的方法论,有助于”用 Claude Code 干活”的人群进入更系统的 harness——他的课程正是卖给这群人。独立信源(同主讲另一门高阶课)对”专家化”有同向支持,可印证。
- 与利益同向(待印证):“用 read-only subagent 做安全护栏”——Nate 推的 Hostinger VPS 用来跑自托管 Claude Code 自动化,read-only subagent 是一套普适模式,与联盟利益无直接绑定,但与他倡导的”自托管”框架方向一致。
- 利益中性:“progressive disclosure 触发逻辑”、“max turns 防失控”、“subagent 不互相通信所以不能取代 Agent Teams”——这些是 Claude Code 平台特性,独立于任何商业主张。
- 与利益反向(可信度最高):Nate 多次直接劝退过度派单——“just because this feature is awesome … that doesn’t mean to force it”(25:14)。这条与”卖课就要让你多用 subagent”的卖方本能相反,可信度高。
- 与利益反向(可信度最高):Nate 自爆一次 dynamic workflow 翻车——“it ate through my session limit like crazy”(24:10 前后),主动给观众提示成本风险,没有粉饰。可信度高。
利益证据:本片 description 顶部两条带 el=claude-code-subagents 追踪参数的 skool 链接(免费社群 + 付费 Plus)是本片最大导流入口;Hostinger 联盟 + Glaido 联盟 + 播客申请 + UppitAI 服务是次级利益;但视频本身未插入 sponsor 段落,推 Hostinger/Glaido 集中在 description 而非口播。
价值定位
对已经在用 Claude Code、但还把 subagent 当”听过的功能”的人,这是把 subagent 从概念用到实操的最直接入门——YAML 字段、project/global 选择、read-only 工具集、描述调优、动态并行,五件事一次给齐。对已经会建几个 subagent 的中级用户,Nate 的”边用边修描述”工作流、读 Open source repo 时的 read-only 验证 subagent 用法、dynamic workflow 的成本与触发词风险,是三个本片独有的实操细节。
本片独有:① 把 subagent 与 skill 的同形异质关系讲得最清楚——“都是 markdown,但一个在主会话内、一个派生出去”——这条对初学者是关键的认知锚点;② 一段”边用边修描述”的实操演示(plan-roaster 第一次没触发 → 回去改描述 → 再触发),把 progressive disclosure 调优的具体动作做出来;③ 显式点出 “read-only subagent 用来审别人分享的 subagent” 的反向用法,把安全护栏和开源复用两件事接起来。
对完全没听过 Claude Code subagent 的新手,视频中间开始节奏会变快(高级选项、YAML 字段列举、dynamic workflow 细节),建议先看 2026-06-18-从提示到导演：把Claude Code agent编排成可复用工作流 把 harness 和 subagent 在更大工作流里的位置搞清楚,再回来用本片建第一个自定义 subagent。
自检问题
- Subagent 与 skill 几乎完全同形,本片给出的”硬差别”是哪两条?为什么这两条让它们在用法上不重合? 答案:详解 4。硬差别是”subagent 有干净上下文窗口 + 可并行”,skill 在主会话内运行、上下文累加、不并行。这两条决定:输出大且要并行的用 subagent,主会话内即时触发的用 skill。
- Progressive disclosure 在 subagent 上具体是怎么作用的?为什么”描述写得准”是写 subagent 最核心的动作? 答案:详解 5。Progressive disclosure 指 Claude Code 只在子代理的描述匹配当前用户指令时,才把 YAML 头之外的全文加载并执行;不匹配完全不读,省 token。描述写得准,既能”该触发就触发”,也能”不该触发不误触发”——所以它是触发器 + 护栏的合一。
- Subagent 的安全护栏为什么不能是”提示它别做某事”?本片推荐的具体实现路径是哪几条?
答案:详解 6。原因是 agent 能读能写的数据”假设它一定会做”(Nate 原话),提示词是软约束、挡不住。实现路径:① YAML 头
tools:字段给白名单(只列它能用的工具);②disallowedTools:反向禁止;③ 限定可用的 MCP server;④ 用一个 read-only subagent 专门审别人分享的 subagent,装之前先审。 - 什么时候该用 subagent、什么时候不该?本片给的”自检问句”和”五条触发信号”分别是什么? 答案:详解 9。自检问句:“is this about to dump a pile of stuff into my chat that I’ll never read again?”——答 Yes 即派。五条触发信号:① 要读很多文件;② 要吐一大段输出;③ 是会重复做的任务(适合做自定义 subagent);④ 是独立可并行的;⑤ 要一个无偏见的审稿人。
- Project 级和 Global 级 subagent 的可见性差异由什么决定?如果把一个 GitHub 仓库分享给同事,对方能直接用到你的全局 subagent 吗?
答案:详解 10。可见性由落盘位置决定——
.claude/agents/是项目级只本项目可用,用户级目录是全局级本机所有项目可用。GitHub 仓库只含项目级配置,“if I share this GitHub repo to someone, they won’t get that skill”——对方拿不到你的全局 subagent。markdown 文件本身可移植,可手动互转。