给AI招帮手：Subagent深度定制
约 21 分钟驭光者首发于微信公众号「羲和Lab」
一个人干不过来就招人——给AI配一支编外团队
阅读时长约12分钟 | 教程型 | 智能编码进化论 06/10
导读
前五篇我们给AI配齐了全套装备：岗位说明书（CLAUDE.md）、结构化任务输入、工具箱（Skills）、外线电话（MCP）。但有个问题越来越明显——AI什么都能干，但不是什么都该在主会话里干。
让AI审查代码？它要读几十个文件，上下文塞满了diff和源码。让AI调研架构方案？它搜索半天，对话历史被日志淹没。这些探索性、辅助性的任务，结果有用，过程是噪音。
Subagent就是解决方案——在独立上下文中派一个"编外员工"去干活，干完了只把结论带回来。主会话保持干净，任务照样完成。本文讲清楚：内置Subagent怎么用、怎么自定义一个专业"员工"、进阶配置有哪些、以及什么场景该用Subagent而不是其他方案。
一、为什么需要Subagent：主会话的上下文危机
一个真实的痛点
你在做一个API重构任务。AI需要审查当前的代码变更——读diff、查测试覆盖率、检查安全风险。三分钟后，审查报告出来了，但你的主会话上下文已经被以下内容占满：
- 300行git diff输出
- 12个源文件的完整内容
- 各种中间分析过程
问题：主会话被"过程数据"污染了。接下来你要继续重构，但AI的注意力被大量审查细节分散，响应变慢，甚至丢失之前的上下文。
Subagent的解决思路
Subagent在独立上下文窗口中运行。主会话派任务，Subagent在自己"办公室"里干活，干完只交一份"报告"回来。
主会话："帮我审查这次变更"
↓
Subagent（独立上下文）：读文件 → 分析 → 生成报告
↓
主会话：收到审查报告，继续重构
这带来三个直接好处：
上下文隔离：探索、搜索、审查产生的中间数据不污染主会话。主会话始终保持聚焦。
成本控制：Subagent可以选择更便宜的模型（比如Haiku）。简单搜索用Haiku就够了，不用每次都烧Opus。
行为约束：Subagent可以被限制工具权限——只读不能写、只能搜索不能执行。该看的不该碰的，边界清晰。
Subagent vs 其他方案：什么时候用什么
| 方案 | 适用场景 | 上下文 | 通信 |
|---|---|---|---|
| 主会话直接做 | 简单任务，几步搞定 | 共享主会话 | 无 |
| Skills按需加载 | 注入参考知识或SOP | 加载到主会话 | 无 |
| Subagent | 探索/审查/调研等辅助任务 | 独立上下文 | 返回结果 |
| Agent Teams | 多Agent并行协作（第8篇） | 各自独立 | 双向通信 |
一句话决策：过程比结果重要→主会话做。结果比过程重要→Subagent做。多个任务需要互相协调→Agent Teams。
二、内置Subagent：开箱即用的三个员工
理解了为什么需要Subagent，我们先看看Claude Code自带了哪些——不需要任何配置就能用。
Explore：只读探索专家
模型：Haiku（快且便宜） 工具：只读（Read、Grep、Glob等） 用途：文件搜索、代码库探索、代码分析
当你让AI"找一下用户认证相关的代码"、"看看这个函数在哪里被调用"，Claude会自动委派给Explore。它只读不改，在独立上下文中搜索，把结果摘要返回。
Explore支持三个搜索深度：
quick：快速查找，适合精确目标（如"找config.ts在哪"）medium：适度探索，适合一般查询（如"用户模块有哪些接口"）very thorough：全面搜索，适合开放式问题（如"这个项目的架构是什么样的"）
大多数场景用默认的medium就行。只在明确需要快速定位或全面调研时调整深度。
Plan：规划研究员
模型：继承主会话模型 工具：只读 用途：进入Plan Mode时自动委派，收集上下文、研究方案
Plan和Explore的区别：Explore回答"是什么"（搜索），Plan回答"怎么做"（规划）。你在Plan Mode中提出的任务，Plan Subagent会先调研代码库，理解现状，再生成实施方案。
General-purpose：全能打工人
模型：继承主会话模型 工具：所有工具 用途：复杂多步任务、代码修改、综合研究
这是最灵活的内置Subagent，能读能写能执行。当你需要一个"什么都能干"的助手时，它就出场了。
三个内置Subagent一览
| 名称 | 模型 | 工具 | 一句话场景 |
|---|---|---|---|
| Explore | Haiku | 只读 | 找文件、搜代码、理解项目结构 |
| Plan | 继承主会话 | 只读 | 调研现状、生成实施方案 |
| General-purpose | 继承主会话 | 全部 | 复杂多步任务、需要修改代码 |
注意Plan和Explore都是只读，区别是Explore用Haiku做搜索、Plan继承主会话做规划。General-purpose是唯一能修改代码的内置Subagent。如果内置的权限粒度不够精确——比如你想让Agent只能读和执行但不能写——那就需要自定义了。
两个辅助Subagent
| 名称 | 模型 | 用途 |
|---|---|---|
statusline-setup | Sonnet | 执行 /statusline 配置状态栏 |
claude-code-guide | Haiku | 回答Claude Code使用问题 |
这两个是功能性的，不需要手动调用。
禁用内置Subagent
如果你不想让AI自动委派给某个内置Subagent（比如不想用Explore），可以在权限中拒绝：
{
"permissions": {
"deny": ["Agent(Explore)"]
}
}
或命令行：
claude --disallowedTools "Agent(Explore)"
三、自定义Subagent：招聘你的专业员工
但内置的只有两种权限级别——Explore和Plan只读，General-purpose全工具。如果你想要一个"能读能执行但不能修改代码"的Agent，就需要自己定制。
第一步：创建Agent文件
在项目目录 .claude/agents/ 下创建一个Markdown文件：
---
name: code-reviewer
description: Reviews code for quality, security, and best practices. Use proactively after code changes.
tools: Read, Glob, Grep, Bash
model: sonnet
---
You are a senior code reviewer. When invoked:
1. Read the changed files
2. Analyze for:
- Security vulnerabilities (SQL injection, XSS, etc.)
- Code quality (naming, structure, error handling)
- Best practices violations
3. Output a structured report with severity levels (🔴 Critical / 🟡 Warning / 🟢 Info)
就这么简单。一个frontmatter头 + 一段系统提示词 = 一个自定义Subagent。
第二步：调用
三种方式触发你的自定义Subagent：
自然语言：在对话中提到它——"让code-reviewer帮我审查一下"。Claude根据description匹配。
@提及：@"code-reviewer (agent)" 或 @agent-code-reviewer。精确指定，不依赖匹配。
命令行指定：claude --agent code-reviewer。整个会话都以这个Subagent身份运行。
frontmatter配置详解
Agent文件的frontmatter控制Subagent的全部行为：
| 字段 | 必填 | 说明 |
|---|---|---|
name | 是 | 唯一标识，小写字母+连字符 |
description | 是 | AI根据这个判断何时委派 |
tools | 否 | 可用工具列表，不填则继承全部 |
disallowedTools | 否 | 明确禁用的工具 |
model | 否 | sonnet/opus/haiku/inherit（默认inherit） |
permissionMode | 否 | 权限模式（default/acceptEdits/auto/dontAsk/bypassPermissions/plan） |
maxTurns | 否 | 最大交互轮次，防止失控 |
skills | 否 | 启动时预加载的Skills |
mcpServers | 否 | 可用的MCP服务器 |
memory | 否 | 持久记忆作用域 |
background | 否 | true=始终后台运行 |
isolation | 否 | worktree=在隔离工作树中运行 |
effort | 否 | 努力程度：low/medium/high/xhigh/max |
color | 否 | 显示颜色（red/blue/green等） |
hooks | 否 | Subagent生命周期钩子（PreToolUse/PostToolUse/Stop） |
initialPrompt | 否 | 自动提交的首轮用户提示词 |
按使用频率排序的实用组合：
只读审查：tools: Read, Glob, Grep + model: haiku — 快速便宜，不改文件。
带执行的研究：tools: Read, Glob, Grep, Bash + model: sonnet — 可以跑命令验证假设。
高安全操作：tools: Read, Bash + permissionMode: plan — 先规划再执行，不可直接改。
作用域：员工归谁管
| 位置 | 作用域 | 优先级 |
|---|---|---|
| Managed settings | 全组织 | 最高 |
--agents CLI参数 | 当前会话 | 高 |
.claude/agents/ | 当前项目 | 中 |
~/.claude/agents/ | 你的所有项目 | 低 |
| Plugin的agents目录 | 启用插件的项目 | 最低 |
最常见的两种：
项目级（.claude/agents/）：跟着代码仓库走，团队共享。代码审查、部署检查这类项目特定的Agent放这里。
个人级（~/.claude/agents/）：跨项目通用。你的个人编码风格检查、常用调试流程放这里。
模型选择策略
Subagent的模型不一定要和主会话一样。合理搭配能省钱又保质：
| 任务类型 | 推荐模型 | 理由 |
|---|---|---|
| 代码搜索、文件查找 | Haiku | 快、便宜，搜索不需要深度推理 |
| 代码审查、质量检查 | Sonnet | 平衡成本和质量 |
| 架构规划、复杂调试 | 继承主会话 | 需要最强推理能力 |
模型优先级：环境变量 CLAUDE_CODE_SUBAGENT_MODEL > 调用时指定 > frontmatter的model字段 > 主会话模型。
四、进阶：Subagent的组合技
前台 vs 后台运行
前台模式（默认）：Subagent运行时主会话等待。权限确认会传递到终端让你审批。
后台模式：Subagent在后台运行，主会话可以继续工作。权限确认自动拒绝，所以后台Subagent需要预授权工具。
两种切换方式：
# 方式一：frontmatter中声明
background: true
# 方式二：运行中按 Ctrl+B 切到后台
什么时候用后台：任务耗时较长、不需要交互确认、结果可以稍后查看。比如后台跑一个全项目的安全审计。
Fork模式：带着记忆分身
Fork模式（实验性，需 CLAUDE_CODE_FORK_SUBAGENT=1）让Subagent继承主会话的完整对话历史，而不是从空白上下文开始。
普通Subagent：
主会话(完整历史) → 启动Subagent(空白上下文) → 只带提示词干活
Fork Subagent：
主会话(完整历史) → Fork(复制完整历史) → 基于对话上下文干活
Fork vs 普通Subagent的关键区别：
| 维度 | Fork | 普通Subagent |
|---|---|---|
| 上下文 | 完整对话历史 | 只有传入的提示词 |
| 系统提示词 | 继承主会话 | 来自Agent定义文件 |
| 模型 | 继承主会话 | 来自model字段 |
| 提示缓存 | 与主会话共享 | 独立 |
| 权限确认 | 显示在终端 | 后台自动拒绝 |
适用场景：你在主会话讨论了一个复杂架构方案，想派一个分身基于已有讨论去验证可行性——用Fork，它记得你们聊了什么。
注意：开启Fork模式后，所有Subagent（包括普通的非Fork类型）都会在后台运行。这是全局行为，不只是Fork本身。
持久记忆：让员工记住上次的事
Subagent默认是无状态的——每次启动都是白纸。但有些任务需要跨会话记忆：
---
name: test-runner
description: 运行测试并跟踪历史通过率
memory: project
---
检查 .claude/agent-memory/test-runner/MEMORY.md 了解历史测试结果。
运行完整测试套件，记录通过率，与上次对比。
memory 字段三个作用域：
| 值 | 存储位置 | 生命周期 |
|---|---|---|
user | ~/.claude/agent-memory/<name>/ | 跨项目持久 |
project | .claude/agent-memory/<name>/ | 跟随项目 |
local | .claude/agent-memory-local/<name>/ | 本地，不提交git |
记忆文件是 MEMORY.md，Subagent可以读写。首次运行自动创建，前200行（25KB）会被加载到上下文中。比如test-runner的MEMORY.md可能长这样：
# test-runner Memory
## 最近一次运行
- 时间：2026-06-08 14:30
- 通过率：94.2%（243/258）
- 失败用例：auth.test.ts (3), api.test.ts (12)
## 历史趋势
- 上周平均：93.1%
- 趋势：↑ 1.1%
Subagent每次运行后更新这个文件，下次启动时读取前200行了解历史状态——本质上就是一个Markdown文件的读写。
MCP和Skills：给员工配专属工具
Subagent可以拥有独立的MCP服务器和Skills，和主会话的配置互不干扰：
---
name: db-analyst
description: 数据库分析和查询优化
tools: Read, Grep, Bash
mcpServers:
postgres:
type: http
url: http://localhost:5432/mcp
skills:
- sql-conventions
---
你是一个数据库分析专家。使用连接的PostgreSQL数据库进行查询分析。
参考 sql-conventions Skill 中的SQL规范。
MCP范围：Subagent的MCP只在它自己的上下文中可用。主会话看不到Subagent的MCP连接。
Skills预加载：skills 字段中列出的Skill会在启动时注入完整内容（不只是描述）。Subagent开箱即用，不需要额外触发。
五、实战：代码审查Subagent全流程
目标：创建一个项目级的代码审查Agent，每次提交前自动审查。
创建Agent文件
.claude/agents/code-reviewer.md：
---
name: code-reviewer
description: 代码审查专家。在代码变更后自动触发，检查质量、安全和最佳实践。
tools: Read, Glob, Grep
model: sonnet
maxTurns: 30
---
你是一位资深代码审查专家。收到审查请求后：
## 审查流程
1. 运行 `!git diff --name-only HEAD` 获取变更文件列表
2. 逐个阅读变更文件，重点关注：
- 安全漏洞（注入、XSS、敏感信息泄露）
- 错误处理缺失
- 不符合项目规范的代码
3. 输出结构化报告
## 报告格式
按严重程度分级：
- 🔴 Critical：必须修复（安全漏洞、数据丢失风险）
- 🟡 Warning：建议修复（代码质量、可维护性）
- 🟢 Info：可选优化（风格、命名）
每个问题包含：文件路径:行号、问题描述、修复建议。
如果没有发现问题，明确说"未发现问题"。
调用方式
最简单的方式——在对话中说：
让 code-reviewer 审查一下这次变更
或者更精确地用@提及：
@agent-code-reviewer 审查 src/auth/ 下的所有变更
进阶：搭配Hooks自动触发
在第7篇我们会详细讲Hooks，这里先剧透：你可以配置一个Hook，每次文件保存后自动触发代码审查Subagent。实现"写完代码自动审查"的闭环。在Hooks章节出来之前，你可以养成习惯——每次提交前手动输入"让code-reviewer审查一下变更"。虽然手动，但审查质量不打折。
进阶：安全审查 + 性能审查并行
定义两个专业Subagent，分别负责不同维度：
# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: 安全审查专家。检查注入、认证、授权等安全问题。
tools: Read, Glob, Grep
model: haiku
---
你专注于安全审查。检查：
- SQL注入、XSS、命令注入
- 认证和授权逻辑
- 敏感信息处理
输出 🔴/🟡/🟢 分级报告。
# .claude/agents/perf-reviewer.md
---
name: perf-reviewer
description: 性能审查专家。检查N+1查询、内存泄漏、不必要的重渲染等。
tools: Read, Glob, Grep
model: haiku
---
你专注于性能审查。检查：
- 数据库查询效率（N+1、缺失索引）
- 内存使用（大对象、未清理的监听器）
- 前端渲染性能（不必要的重渲染、大包体积）
输出 🔴/🟡/🟢 分级报告。
两个Agent都用Haiku模型，成本低，速度快。Claude可以根据你的请求同时委派两个，并行审查不同维度——两个Haiku Subagent并行审查，成本大约是Sonnet主会话审查的1/5，速度却快了两倍。
六、避坑指南
坑一：Subagent触发不了
你定义了一个Agent，但Claude不用它。
排查路径：
description是否清晰？AI靠description判断何时委派。写"代码审查"不如写"审查git diff中的变更，检查安全和代码质量"。- Agent文件位置对不对？项目级放
.claude/agents/，个人级放~/.claude/agents/。 - 用
@agent-名称精确调用试试。能触发说明Agent本身没问题，是description匹配问题。
坑二：Subagent权限不够
Subagent执行时报权限错误。
原因：tools 字段限制了可用工具。比如定义了 tools: Read, Grep，但Agent执行时需要跑命令——没有Bash权限。
解法：根据实际需求配置tools。审查类任务可以只读（Read+Grep+Glob），执行类任务需要加Bash和Write。也可以用 disallowedTools 只排除危险工具，其余继承。
坑三：Subagent结果没回到主会话
后台运行的Subagent，结果看起来丢了。
原因：后台Subagent完成后，结果存储在子代理输出中。主会话不会自动显示完整内容。
解法：前台运行的Subagent会直接返回结果到主会话。后台运行的，通过消息系统接收摘要。如果结果很长，建议用前台模式。
坑四：Fork模式上下文过大
Fork继承完整对话历史，如果主会话已经很长，Fork的上下文也很大，可能影响性能。
解法：在主会话上下文较短时使用Fork。长会话中，用普通Subagent + 精心编写的提示词，把必要信息显式传递。
坑五：循环委派——Subagent里又启Subagent
Subagent默认不能再派Subagent。但如果你通过 claude --agent 以主线程方式运行一个Agent，而它的tools中给了Agent工具，可能出现A派B、B派A的循环。
解法：明确限制可派发的Subagent类型：tools: Read, Grep, Agent(security-reviewer) — 只能派security-reviewer这一个。
结语
六篇文章下来，AI"员工"已经从单打独斗进化到能带团队了：CLAUDE.md让它了解规矩，结构化输入让它听懂指令，Skills让它有专业工具，MCP让它能对接外部系统，现在Subagent让它能派分身并行干活。
五个关键要点：
Subagent是独立上下文的编外员工——过程噪音不污染主会话，只带结论回来。
内置Explore是日常搜索首选——Haiku模型、只读工具、快且便宜。
自定义Agent是真正的威力所在——frontmatter控制行为，prompt定义专业能力。
模型选择省钱又保质——搜索用Haiku、审查用Sonnet、复杂推理继承主会话。
组合使用效果最强——Subagent + MCP + Skills，让每个"员工"都有专属工具和专业能力。
下一篇，我们给AI定规矩——Hooks与权限工程。如果说Subagent是给AI招了帮手，Hooks就是给所有员工（包括帮手）装上了门禁和监控系统——什么能做、什么不能做、做了要通知谁，全部自动化。
互动话题
你的项目里，哪些重复性任务适合交给Subagent？是代码审查、安全扫描、性能分析，还是自动化测试？来评论区分享你的Subagent设计思路。
智能编码进化论 | 第6篇/共10篇
下一篇：给AI定规矩：Hooks与权限工程
本文内容仅供学习交流，所述方法需结合实际场景灵活运用。 AI工具输出结果仅供参考，关键业务决策请结合人工判断。
本文由AI辅助创作，经人工审核编辑后发布。
本文首发于微信公众号「羲和Lab」，公众号内可留言交流
阅读公众号原文