📒 学霸笔记：14｜智能分身：精通 Subagent，为复杂任务创建专家 AI

Top Student Notes: 14 | Intelligent Clones: Mastering Subagents to Create Expert AI for Complex Tasks

课程 / Course: AI 原生开发工作流实战 / AI-Native Development Workflow in Practice
讲师 / Instructor: Tony Bai
章节 / Chapter: 14
主题 / Topic: Subagent、多智能体系统、独立上下文、专家分身、Orchestrator、Subagent 定义文件、/agents、隐式调用、显式调用、链式编排

一、这一讲在解决什么问题？

What Problem Does This Lecture Solve?

到第 13 讲为止，我们已经给 Claude Code 加了很多能力：

• Slash Commands：快速启动固定流程
• Hooks：事件驱动自动化
• MCP：接入外部世界
• Agent Skills：让 AI 自主发现并调用专家知识

此时 AI 看起来已经很强了，但随着任务变复杂，会出现一个新的问题：

一个 AI 会很多，但不代表它能同时把多个冲突的专业角色都扮演好。

Tony 举的例子很典型：

“请重构 internal/billing 模块，提升性能，并确保整个过程符合公司安全规范。”

这个任务表面上是一句话，实际上至少包含两个高度不同的专家目标：

1. 性能优化专家

   • 倾向激进
   • 关注吞吐、缓存、并发、低层技巧
   • 有时甚至会接受 unsafe 等高风险手段

2. 安全审查专家

   • 倾向保守
   • 关注输入验证、最小权限、风险面
   • 会天然质疑 unsafe、动态执行和不受控优化

如果让一个单独 Agent 同时扮演这两个角色，就很容易出现：

• 思考摇摆
• 目标冲突
• 上下文混杂
• 重点漂移
• 结论折中但不专业

所以这一讲解决的问题是：

如何让 AI 不再作为一个“全能但混杂的通才”工作，而是以多个职责清晰、上下文隔离的专家分身协同作战。

Claude Code 的答案就是：

Subagent（智能分身）

二、本讲核心结论

Core Conclusion of This Lecture

一句话总结

Subagent 本质上是拥有独立上下文、独立系统提示和可控工具权限的“专家 AI 分身”，它让复杂任务从单体推理升级为多智能体协作。

三、为什么单一 Agent 会遇到瓶颈？

Why Does a Single Agent Hit a Bottleneck?

这一讲的起点不是“新功能介绍”，而是一次对单智能体局限性的揭示。

1. 单一 Agent 是线性探索的

A Single Agent Explores Linearly

面对复杂任务，单一 Agent 往往是一条线走到底：

• 一边看代码
• 一边思考架构
• 一边想着安全
• 一边又想着测试
• 一边还要维护主任务上下文

这会导致：

• 上下文越来越杂
• 推理越来越重
• 任务容易被次要问题带偏

2. 多个专家目标可能天然冲突

Multiple Expert Goals Can Naturally Conflict

性能、安全、可维护性、可测试性，这些目标经常不是完全一致的。

如果让同一个 Agent 同时承担所有目标，它会进入一种“精神分裂式”的状态：

• 想加速，又怕风险
• 想引入新库，又担心安全
• 想做大改造，又担心测试缺失

结果往往是不够聚焦。

3. 上下文污染是关键问题

Context Pollution Is the Key Problem

单一 Agent 会把：

• 主任务上下文
• 子任务过程
• 试探性思路
• 临时分析结果

全部堆在一个窗口里。

这很容易造成：

• 主线被子任务噪音干扰
• 临时探索污染最终思考
• 模型忘记初始目标

学霸理解

所以单一 Agent 的问题，不是“它不够聪明”，而是：

复杂问题需要分工、隔离和压缩，而不是所有认知活动都挤在一个脑子里。

四、为什么多智能体势在必行？

Why Is a Multi-Agent Approach Necessary?

Tony 这里实际上是在把人类团队协作逻辑，映射到 AI 工作流中。

现实世界里，复杂问题通常不会靠一个人完成，而是靠：

• 专家分工
• 并行探索
• 关注点分离
• 最后汇总

这正是：

Multi-agent System（多智能体系统）

的核心思想。

五、多智能体的两个核心优势

Two Core Advantages of Multi-Agent Systems

1. 上下文压缩与并行推理

Context Compression and Parallel Reasoning

这是 Tony 强调的最核心优势。

主 Agent 可以把一个大问题拆成多个子问题，然后分别交给多个 Subagent。

每个 Subagent：

• 在自己的独立上下文里工作
• 只关心自己的那部分任务
• 最后只返回高度压缩的结论

结果是什么？

你相当于拥有了：

多个独立上下文窗口并行工作

而不是把所有内容硬塞进一个窗口。

2. 关注点分离

Separation of Concerns

每个 Subagent 可以拥有：

• 不同的 Prompt
• 不同的角色人格
• 不同的工具集
• 不同的思考风格

于是：

• 安全专家只盯安全
• 性能专家只盯性能
• 测试专家只盯覆盖与边界

不会互相打架。

学霸理解

多智能体最大的价值不是“数量多”，而是：

通过上下文隔离和角色专注，让每个智能体都能成为一个干净的专家。

六、Subagent 在 Claude Code 里到底是什么？

What Exactly Is a Subagent in Claude Code?

Tony 给了一个非常好懂的比喻：

主会话像 CTO，Subagent 像各部门总监。

主会话（主 Agent）像什么？

像总指挥、项目经理、CTO：

• 理解整体任务
• 决定要不要委托
• 调度专家
• 汇总结果
• 给出最终对话响应

Subagent 像什么？

像一个可以随时召唤的专家总监：

• 安全总监
• 性能总监
• QA 总监
• 数据库总监
• 架构审查员

他们不会一直在主会话里发言，而是被委托后：

1. 拿着任务回到自己的办公室
2. 在独立上下文中研究
3. 最后只回报浓缩结论

七、Subagent 的三个核心特性

The Three Core Characteristics of a Subagent

1. 独立上下文窗口

Independent Context Window

这是 Subagent 最本质的价值。

每个 Subagent：

• 有自己的“内存空间”
• 不共享主会话的对话历史
• 不污染主会话上下文
• 也不会被主会话的历史噪音干扰

为什么这点如此重要？

因为这意味着：

• 子任务可以很深
• 主任务依然保持干净
• 专家可以专注，不受额外上下文干扰

2. 专属系统提示

Dedicated System Prompt

每个 Subagent 都由自己的 .md 文件定义，并带有专门的 System Prompt。

这意味着每个分身都拥有：

• 专业身份
• 行为准则
• 工作流程
• 输出结构
• 角色边界

3. 精细工具权限

Fine-Grained Tool Permissions

你可以为每个 Subagent 单独配置它能使用哪些工具。

例如：

• 代码审查员：只给 Read / Grep / Glob
• 安全扫描员：可加 Bash(gosec:*)
• DevOps 专家：可给部署相关工具
• 文档专家：不给 Bash

这遵循：

最小权限原则

八、Subagent 的物理形态：其实就是一个 Markdown 文件

The Physical Form of a Subagent: Just a Markdown File

和 Skills 一样，Subagent 这个看起来很高级的概念，在实现上其实非常朴素。

它的定义就是：

一个带 YAML Frontmatter 的 Markdown 文件

这点非常重要，因为这意味着：

• 易维护
• 易版本控制
• 易共享
• 易团队协作

九、Subagent 的两个标准位置

The Two Standard Locations for Subagents

1. Project-level Subagents

位置：

./.claude/agents/

特点

• 当前项目可用
• 团队共享
• 应提交 Git
• 适合项目特定专家

例子

• go-code-security-reviewer
• api-design-reviewer
• database-migration-generator

2. User-level Subagents

位置：

~/.claude/agents/

特点

• 个人私有
• 所有项目可用
• 不进项目仓库

例子

• english-polisher
• shell-script-optimizer

覆盖规则

如果同名 Agent 同时存在：

项目级覆盖用户级

这和前面 settings / skills 的层级治理逻辑是一致的。

十、一个 Subagent 定义文件的结构

Structure of a Subagent Definition File

Subagent 文件分成两部分：

1. YAML Frontmatter
2. Markdown 正文（System Prompt）

十一、name：唯一 ID

name: The Unique ID

这是 Subagent 的唯一标识。

要求通常是：

• 小写
• 连字符风格

例如：

go-code-security-reviewer

它也是主 Agent 调用它时使用的名字。

十二、description：Subagent 最重要的发现入口

description: The Most Important Discovery Entry Point

Tony 强调了很多次：

description 是主 Agent 决定是否委托这个 Subagent 的核心依据。

它要包含什么？

一个高质量的 description 至少包含三类信息：

1. 它能做什么

例如：

• review Go code for security vulnerabilities

2. 什么时候该用它

例如：

• when security is mentioned
• after implementing features that handle user input

3. 触发关键词

例如：

• security
• vulnerabilities
• auth logic
• input validation
• API endpoint

学霸理解

description 对 Subagent 的意义，和 description 对 Skill 的意义很像：

它是能力发现的索引、广告语和触发条件说明。

十三、tools：为 Subagent 单独定义能力边界

tools: Defining a Dedicated Capability Boundary for a Subagent

这是一个很重要的安全设计点。

如果你写了 tools 字段，那么这个 Subagent 只能用你列出来的工具。

如果省略呢？

则继承主会话工具权限。

推荐怎么做？

大多数情况下：

尽量显式写 tools，不要随便继承全部权限。

例如：

• 安全审查员：Read, Grep, Glob, Bash(gosec:*)
• 文档审查员：只读工具
• 测试增强专家：可读写+测试命令
• DevOps 专家：可用部署命令

十四、model：可为专家指定不同模型

model: Assigning Different Models to Different Experts

Subagent 可以指定模型，比如：

• opus
• sonnet
• haiku
• inherit

怎么理解这个能力？

不同专家任务有不同性价比要求：

深度安全审计 / 架构推理

可用：

opus

日常中等复杂分析

可用：

sonnet

简单、重复、低成本任务

可用：

haiku

想保持跟主会话一致

可用：

inherit

学霸理解

这使得 Subagent 不只是“角色分工”，还是：

模型资源调度单元

十五、Markdown 正文：这才是 Subagent 的“灵魂”

Markdown Body: This Is the “Soul” of the Subagent

Frontmatter 决定：

• 这个专家叫什么
• 何时被发现
• 能用什么工具
• 用什么模型

而正文决定：

• 它如何思考
• 它用什么标准做判断
• 它怎样输出结果
• 它是否稳定可靠

所以正文本质上是什么？

Subagent 的 System Prompt

这就是它的“灵魂”和“操作手册”。

十六、/agents：Subagent 的可视化管理中心

/agents: The Visual Management Center for Subagents

虽然你可以手动创建 .md 文件，但 Claude Code 提供了一个非常友好的管理入口：

/agents

这个界面能做什么？

• 查看已有 Agents
• 创建新 Agent
• 编辑 Agent
• 删除 Agent

为什么推荐初学者用它？

因为它可以避免：

• YAML 格式错误
• 字段漏写
• tools 名称拼错
• 文件放错位置

同时能帮助你建立：

• Subagent 有哪些可配置项
• 创建流程长什么样
• 权限选择怎么做

十七、Subagent 与 Skills / Commands 的最核心区别

The Most Fundamental Difference Between Subagents and Skills/Commands

这一讲再次回扣了上一讲的对比。

Slash Commands

• 用户显式调用
• 固定流程
• 在主会话上下文中运行

Skills

• AI 自主发现和调用
• 是能力说明和方法论注入
• 也运行在主会话上下文中

Subagents

• AI 主动委托给分身
• 最核心是：

  运行在独立上下文中

这意味着什么？

Subagent 的独特价值不是“也很智能”，而是：

它能把复杂、深度、容易污染主线的子任务隔离出去。

十八、实战：创建一个 Go 代码安全审查员

Practical Example: Creating a Go Code Security Reviewer

这个实战非常典型，因为它把 Subagent 的三大核心都用上了：

• 专业角色
• 工具最小权限
• description 触发发现

角色选择为什么合理？

安全审查是非常适合做成 Subagent 的工作，因为它具有：

• 专业性强
• 审查标准明确
• 适合只读分析
• 需要深度聚焦
• 容易成为独立子任务

十九、这个安全审查员的 System Prompt 有什么特点？

What Is Good About This Security Reviewer’s System Prompt?

Tony 写的 Prompt 非常值得学。

它的特点是：

1. 先定义身份

You are an elite security code reviewer specializing in Go applications.

不是模糊说“帮我看看代码”，而是明确人格与专长。

2. 给出明确检查维度

例如：

• 输入验证与净化
• 鉴权与授权
• Go 特有漏洞
• 错误处理
• 并发竞争
• unsafe 使用

这使得专家不是“自由发挥”，而是“按框架执行”。

3. 明确输出结构

按严重级别排序，并且每个问题必须包含：

• Vulnerability
• Location
• Impact
• Remediation

学霸理解

好的 Subagent Prompt 不是“有点像专家”，而是：

把专家的检查框架、判定标准和报告模板都写出来。

二十、这个 description 为什么写得好？

Why Is This description Well Written?

示例里的 description 包含了非常关键的三类内容：

1. 能力

• Go security code reviewer
• security vulnerabilities
• input validation
• authentication / authorization flaws

2. 触发条件

• when security is mentioned
• after implementing features that handle user input
• when dealing with API endpoints, auth logic

3. 语义关键词

• security
• input validation
• auth
• API
• user input

结果

主 Agent 在面对相关请求时，就更容易“想起”这个 Subagent。

二十一、Tools 为什么只给只读 + 特定扫描工具？

Why Only Grant Read-Only Tools + Specific Scanners?

因为这个角色的职责是：

审查，不是修改

所以应该贯彻：

最小权限原则

这样做的好处

安全上

防止它误改代码

认知上

防止它分心去做不属于它的事

角色上

强化“审查员”身份，而不是“开发者”身份

二十二、三种调用方式

Three Ways to Invoke and Orchestrate Subagents

这是这一讲非常实战的一部分。

二十三、方式一：隐式调用

Mode 1: Implicit Invocation

你只自然表达需求，比如：

帮我检查一下这个 Go 文件里有没有安全漏洞

如果主 Agent 根据 description 发现这个任务适合 go-code-security-reviewer，它会自动委托。

特点

• 最智能
• 最自然
• 最接近真实协作

前提

你的 description 必须写得足够好。

二十四、方式二：显式调用

Mode 2: Explicit Invocation

你可以在 Prompt 里直接点名：

使用 go-code-security-reviewer subagent 检查一下这个文件

特点

• 控制最强
• 适合你明确知道该找谁做
• 适合验证 Agent 是否按预期工作

二十五、方式三：链式编排

Mode 3: Chained Orchestration

这是最接近“多智能体系统”的高级用法。

例如：

1. 先让 performance-optimizer 重构模块
2. 再让 go-code-security-reviewer 做安全审计
3. 最后让 test-coverage-enhancer 补测试

这意味着什么？

你不再只是“问 AI 一个问题”，而是在：

编排一个专家团队的交付流程

这就是从用户升级为：

• Orchestrator
• 工作流设计者
• AI CTO

二十六、Subagent 设计的最佳实践

Best Practices for Designing Subagents

Tony 最后给了几条非常重要的经验法则。

二十七、最佳实践一：先让 AI 生成，再人工打磨

Best Practice 1: Let AI Generate the First Draft, Then Refine It

不要从零写一个完美 Subagent。

更好的做法是：

• 用 /agents
• 选 “Generate with Claude”
• 先让 AI 给你一个初稿
• 再用你的领域知识不断修正

这实际上是一种元工作流

用 AI 创造更好的 AI。

二十八、最佳实践二：保持专注，拒绝万能 Agent

Best Practice 2: Stay Focused; Reject the “Do-Everything” Agent

Subagent 的价值在于：

专业性，而不是通用性

所以不要做：

• code-quality-master
• all-in-one-reviewer
• everything-assistant

而要做：

• go-security-reviewer
• performance-optimizer
• test-coverage-enhancer

原因

• 更容易被正确发现
• 行为更稳定
• 上下文更干净
• 更容易组合

二十九、最佳实践三：精雕 System Prompt

Best Practice 3: Carefully Craft the System Prompt

Prompt 要：

• 明确角色
• 明确步骤
• 明确输出格式
• 给出示例
• 给出约束

不要只写：

“帮我做代码审查”

而应写成：

• 按哪些维度检查
• 如何分类问题
• 如何引用文件位置
• 如何给出修复建议

三十、最佳实践四：贯彻最小权限原则

Best Practice 4: Enforce Least Privilege

这是 Subagent 安全性的关键。

只给它完成核心职责所需的最小工具集。

为什么尤其重要？

因为 Subagent 可能在后台被自动委托。
它不像你手动敲 Bash 那么直观可见。

所以权限边界必须非常明确。

三十一、最佳实践五：纳入版本控制

Best Practice 5: Put Project Subagents Under Version Control

Project-level Subagent 是团队资产。

应当：

• 提交到 Git
• 用 PR 维护
• 允许团队共同优化
• 像代码一样迭代

学霸理解

Subagent 文件其实就是：

团队的 AI 专家定义资产

三十二、这一讲的真正认知升级

The Real Cognitive Upgrade in This Lecture

这一讲不是在告诉你“Claude 还能再开几个分身”，而是在推动你完成一次角色升级：

从与单个 AI 对话，升级为管理一个 AI 专家团队。

以前你做什么？

• 提问题
• 给命令
• 改 Prompt
• 控权限

现在你做什么？

• 设计专家角色
• 规划角色边界
• 决定谁负责什么
• 编排工作顺序
• 汇总专家结论

这就是“AI CTO”思维

你不再只是用户，而是：

多智能体系统的组织者与编排者

三十三、这一讲和前面课程怎么串起来？

How Does This Lecture Connect to the Earlier Lessons?

前面课程一直在做三类事：

1. 让 AI 更有能力
2. 让 AI 更安全
3. 让 AI 更懂规则和自动化

14 讲补上的是：

让 AI 更像一个组织，而不是一个个体。

串联来看

• Slash Commands：给 AI 快捷工作流入口
• Hooks：让工作流自动触发
• MCP：让 AI 接外部系统
• Skills：让 AI 按领域能力思考
• Subagents：让 AI 以多个专家分身协同工作

三十四、本讲知识结构图

Knowledge Structure of This Lecture

任务越来越复杂
        ↓
单一 Agent 开始出现瓶颈
├── 上下文混杂
├── 角色冲突
├── 线性探索低效
└── 主线易被污染
        ↓
需要多智能体系统
        ↓
Subagent
= 拥有独立上下文的专家分身
        ↓
三大核心特征
├── 独立上下文窗口
├── 专属系统提示
└── 精细工具权限
        ↓
具象化实现
├── ./ .claude/agents/
├── ~/.claude/agents/
└── 一个带 YAML Frontmatter 的 Markdown 文件
        ↓
关键字段
├── name
├── description
├── tools
└── model
        ↓
实战
└── go-code-security-reviewer
        ↓
调用方式
├── 隐式调用
├── 显式调用
└── 链式编排
        ↓
最终升级
从与一个 AI 对话
变成管理一支 AI 专家团队

三十五、学霸速记表

Quick Revision Table

三十六、学霸自检题

Self-Check Questions

基础题

1. 为什么一个单一 Agent 在复杂任务中容易“精神分裂”？
2. Subagent 与 Skills 最大的区别是什么？
3. description 在 Subagent 中起什么作用？

进阶题

4. 为什么 Subagent 的独立上下文是其最关键价值？
5. 为什么安全审查员这种角色特别适合做成只读 Subagent？
6. 为什么说链式编排是“多智能体系统的雏形”？

思辨题

7. 如果你要把一个 Go 项目的数据库迁移任务拆给多个 Subagent，你会如何划分角色？
8. 哪些工作更适合 Skill，哪些更适合 Subagent？
9. 你会如何为“性能优化专家”设计 Prompt 和 tools 边界？

三十七、学霸总结

Top-Student Summary

这一讲讲的是 Claude Code 中一个非常关键的高级能力：Subagent。
它解决的核心问题是：

当任务足够复杂、足够专业、足够容易相互干扰时，单一 AI Agent 已经不再是最优组织方式。

Tony 通过“性能优化 + 安全审查”这样的复合任务，揭示了单智能体模型的典型瓶颈：

• 一个上下文同时承载多个专业目标
• 多个角色之间目标冲突
• 推理线性展开，容易陷入局部最优
• 子任务探索噪音污染主线

于是，解决方案不再是“让一个 AI 更努力”，而是：

把任务拆给多个拥有独立上下文的专家分身。

这就是 Subagent 的本质。

在 Claude Code 中，Subagent 是一种可以被主 Agent 调度的专家 AI 分身，它具备三个最核心的特征：

1. 独立上下文窗口
   子任务可以在隔离环境中深度推理，而不污染主会话。

2. 专属系统提示
   每个分身都有自己明确的角色、任务边界和操作手册。

3. 精细工具权限
   每个分身都可以被赋予最小必要权限，提升安全性与任务聚焦度。

它的实现方式也非常优雅：
每个 Subagent 就是一个放在标准目录中的 Markdown 文件，顶部用 YAML Frontmatter 定义 name、description、tools、model，正文则作为该分身的 System Prompt。

其中最关键的字段之一是 description，因为它决定了主 Agent 是否能在合适的时机“想起”并委托这个专家分身；而 tools 则体现了上一讲安全哲学中的“最小权限原则”。

通过“Go 代码安全审查员”这个实战，Tony 展示了如何创建一个真正专业且安全的 Subagent：
它有清晰的安全审查职责、明确的检查框架、结构化的输出模板，并且只拥有只读和特定安全扫描工具权限。

在使用方式上，Subagent 有三种典型模式：

• 隐式调用：主 Agent 根据任务语义自动委托
• 显式调用：用户直接点名指定专家
• 链式编排：多个 Subagent 串联协作，形成完整交付流水线

这使得开发者的角色再次升级：
你不再只是 AI 的用户，甚至不只是 Prompt 设计者，而开始成为：

AI 专家团队的组织者、调度者和工作流编排者。

所以，这一讲最关键的思想并不是“AI 能开分身”，而是：

复杂问题的解决方式，从单体智能转向多智能体协作。

这标志着 AI 原生开发开始真正具备“组织能力”，而不仅仅是“生成能力”。

三十八、一句话记忆

One-Sentence Memory Hook

Subagent 的本质，是把复杂任务拆给多个拥有独立上下文和清晰角色边界的 AI 专家分身，让你从“和一个 AI 对话”升级为“指挥一支 AI 专家团队”。