主题
Subagents 子代理
Subagent 是独立 context 的 AI 助手，主 Claude 把任务委派给它执行。
一句话
用 subagent 跑会污染主对话 context 的脏活。
适用场景
| 场景 | 用 Subagent | 别用 |
|---|---|---|
| 跑 100 个测试看结果 | ✅ | 自己跑会爆 context |
| 同时审多个 PR | ✅ | 串行慢 |
| 探索陌生代码库 | ✅ | 减少主对话噪声 |
| 写单个函数 | ❌ | 直接做更快 |
| 并发 3 个方案对比 | ✅ | 一次跑出 3 个 |
特点
- ✅ 独立 context — subagent 看不到你跟主 Claude 的对话
- ✅ 并发 — 最多同时 10 个
- ✅ 可指定模型 — subagent 用 Haiku 省钱，主用 Opus
- ⚠️ 无状态 — subagent 跑完就死，下次重新启动
- ⚠️ 5 分钟超时 — 单个 subagent 最多 5 分钟
文件结构
~/.claude/agents/ ← 个人级
└── code-reviewer/
└── AGENT.md
或
<项目根>/.claude/agents/ ← 项目级
└── api-tester/
└── AGENT.mdAGENT.md 模板
markdown
---
name: code-reviewer
description: 资深代码审查员，专注安全和性能
model: claude-sonnet-4-6
tools: Read, Glob, Grep, Bash
---
# 代码审查 Subagent
你是一位**资深代码审查员**，专注：
- 🔒 安全漏洞（OWASP Top 10）
- 🐎 性能问题（复杂度、N+1、内存泄露）
- 🧪 测试覆盖
- 📐 编码规范（看项目 CLAUDE.md）
## 工作流程
1. 用 Glob 找出变更文件
2. 用 Read 读每个文件
3. 用 Bash 跑 `git diff` 看具体改动
4. 按以下格式输出结论：
\`\`\`
🔴 必改：
- file.ts:42 — SQL 注入风险，应该用参数化查询
🟡 建议：
- ...
🟢 亮点：
- ...
\`\`\`
## 限制
- 不要直接修改任何文件
- 不要执行破坏性命令
- 发现问题用 description 详细说明主 Claude 怎么调用
方式 1：用 Task 工具
主 Claude 内部用 Task 工具：
Task({
description: "审查 PR",
subagent_type: "code-reviewer",
prompt: "审查 src/api/auth.ts 的改动..."
})方式 2：手动 /agent
/agent code-reviewer 审查 PR #234方式 3：主动建议
Claude 自动判断："这个任务复杂，我开个 subagent 并行处理。"
实战例子：3 个超有用的 Subagent
1. test-runner（专门跑测试）
markdown
---
name: test-runner
description: 跑测试并修复失败的，独立 context 不污染主对话
model: claude-haiku-4-5-20251001
tools: Bash, Read, Edit
---
跑全测试套件：
1. `pnpm test 2>&1`
2. 解析失败的测试
3. 读相关源码
4. 修复（最多重试 3 次）
5. 重跑确认
6. 输出简报：通过/失败/修复了什么
只关注测试，不做其他事。2. code-explorer（探索陌生代码库）
markdown
---
name: code-explorer
description: 探索陌生代码库，输出架构地图
model: claude-sonnet-4-6
tools: Read, Glob, Grep, Bash
---
探索 $ARGUMENTS 这个项目：
1. 用 Glob 找入口（main, index, app）
2. 用 Read 看 package.json / Cargo.toml / go.mod
3. 跑 `tree -L 3` 看结构
4. 找关键模块（router/controller/handler）
5. 输出：
- 一句话总结
- 技术栈
- 入口点
- 关键目录功能
- 推荐起步阅读顺序3. fork-and-compare（并发跑多方案）
markdown
---
name: fork
description: 同时尝试多个实现方案对比
model: claude-opus-4-7
tools: Read, Edit, Bash
---
对于用户给的需求，并发尝试 3 种实现：
- 方案 A：保守传统
- 方案 B：现代最佳实践
- 方案 C：实验性
每种方案：
1. 简述思路
2. 写出代码
3. 跑测试
4. 列优缺点
最后并排对比，让用户选。用 fork 提升 PR 质量
/agent fork "实现用户认证" →
Subagent 1: JWT + Redis session
Subagent 2: 纯 cookie + signed cookie
Subagent 3: OAuth + supabase auth3 个方案并行 → 5 分钟拿到 3 套完整实现 → 你选最满意的合入。
用 Haiku 做 subagent 省钱
yaml
model: claude-haiku-4-5-20251001Haiku 速度快 5×，价格便宜 15×。简单任务（跑测试、查文档、格式化）用 Haiku 完全够。
性能 vs 复杂度权衡
| Subagent 数 | 并发收益 | Token 消耗 |
|---|---|---|
| 1 | 不如直接做 | 同 |
| 2-3 | 显著收益 | 适中 |
| 4-7 | 收益递减 | 高 |
| 8-10 | 边际收益小 | 极高 |
| >10 | 不允许 | — |
3-5 个 subagent 是甜蜜点。
调试 subagent
/agents # 列出所有可用 subagent
/agent <name> # 强制启动
/usage # 看每个 subagent 的 token 消耗注意事项
WARNING
- Subagent 独立 context 意味着主 Claude 的 todo/记忆它看不到
- 必须在 prompt 里显式传它需要的信息
- subagent 不能调用其他 subagent（避免递归爆炸）
- subagent 共享主 Claude 的工具白名单
跟 Skills / Hooks 配合
你说："审 PR + 跑测试"
↓
主 Claude 触发 code-review skill
↓
skill 指示主 Claude 开 2 个 subagent：
- subagent: code-reviewer
- subagent: test-runner
↓
并发跑，5 分钟出双结果
↓
主 Claude 综合输出热门 Subagent 库
| 仓库 | 内容 |
|---|---|
| rohitg00/awesome-claude-code-toolkit | 135 个生产级 subagents |
| VoltAgent/awesome-agent-skills | 跨工具 subagent + skill |
一键安装：
bash
cd ~/.claude
git clone https://github.com/rohitg00/awesome-claude-code-toolkit
ln -s awesome-claude-code-toolkit/agents agents重启 claude 即可识别。
Subagent vs Skill vs Hook
| Subagent | Skill | Hook | |
|---|---|---|---|
| context | 独立 | 共享主对话 | 无（脚本） |
| 触发 | 主 Claude 委派 | 任务匹配 | 生命周期事件 |
| 并发 | ✅ 最多 10 | ❌ 串行 | ✅ |
| 用途 | 委派重活 | 复用提示词 | 强制规则 |