9 Subagents 多智能体：代码审查、测试、文档分工处理

查看大图

Subagents 适合用在一个人脑子里装不下太多视角的时候。

比如你做完一个功能，既想有人看代码风格，又想有人查安全风险，还想有人补文档、跑测试。如果都让主会话一个角色处理，它可能顾此失彼。Subagents 可以把这些任务拆给不同的专门角色。

Subagents 的价值在于分工，不在于堆数量。一个负责代码审查，一个负责测试覆盖，一个负责文档一致性，比十个都在泛泛评论更可靠。

查看大图

我会给每个子代理写清楚输入、输出和禁止事项。比如安全审查只列风险和证据，不直接改代码；测试代理只补最小必要测试，不顺手重构。

用 /agents 管理

官方 Subagents 文档里推荐用：

查看大图

设计 Subagents 分工时，先拆出代码审查、测试补齐、文档整理和结果汇总，每个角色都要有清晰输入输出。

/agents

这个命令会打开管理界面。你可以创建个人级 subagent，也可以创建项目级 subagent。个人级通常保存在 ~/.claude/agents/，项目级可以放在 .claude/agents/，适合提交到仓库让团队共用。

Subagent 本质上是带 YAML frontmatter 的 Markdown 文件。你可以定义它的描述、提示词、工具范围、模型、权限模式、MCP server、hooks、最大轮数等。

新手先做三个角色

我建议先做三个：

查看大图

读《Subagents 多智能体：代码审查、测试、文档分工处理》时，可以先看配图里的任务、概念、练习和判断点，再回到正文补细节。这样更容易判断这篇内容能放到哪个真实场景里。

1. code-reviewer：只负责代码审查，优先找 bug、风险和缺测试。
2. test-planner：只负责根据改动建议测试点。
3. doc-writer：只负责把变更写成用户能读懂的说明。

不要一开始就做十个角色。角色太多，调度成本也会上来。

一个 code-reviewer 示例

可以让 Claude Code 帮你生成，也可以自己写：

---
name: code-reviewer
description: Reviews code changes for bugs, regression risk, and missing tests.
tools:
  - Read
  - Grep
  - Bash
---

You are a strict code reviewer.
Find behavioral bugs first.
Mention exact files and lines when possible.
Do not rewrite code unless asked.

这个角色的重点是“审查”，不是“顺手重构”。Subagent 的边界越清楚，输出越稳定。

什么时候用 Subagents

适合使用：

• 大改动之后做独立 review。
• 一个任务需要并行查资料、跑测试、写文档。
• 团队想共享某类固定审查标准。
• 你希望某些任务在后台运行。

不适合使用：

• 很小的文案改动。
• 你自己还没想清楚需求。
• 权限边界没设好。
• 只是想让场面看起来很“多智能体”。

Subagents 不是为了炫技，而是为了把复杂任务拆成可检查的角色。

前后台任务要分清

官方文档里提到，subagents 可以前台运行，也可以后台运行。前台会阻塞主会话，权限提示会正常传给你；后台可以并行，但遇到需要确认的工具调用通常会被自动拒绝。

查看大图

练习《Subagents 多智能体：代码审查、测试、文档分工处理》时，建议把输入条件、处理动作和可见结果写在一起，方便下次复查。

查看大图

复习《Subagents 多智能体：代码审查、测试、文档分工处理》时，建议把关键概念、操作步骤和可见结果放在同一页里回看。

所以高风险任务，比如改代码、跑部署、操作数据库，不建议一开始就放后台。查资料、整理文档、扫描风险，可以更适合后台。

下一篇是这套教程的收尾：Hooks、GitHub Actions 和团队化。也就是怎么把 Claude Code 从个人工具，慢慢放进工程流程。

参考资料：

• Create custom subagents
• Claude Code Commands
• Extend Claude Code