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

Claude Code Subagents 多智能体工作流手绘图

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

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

用 /agents 管理

官方 Subagents 文档里推荐用：

/agents

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

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

新手先做三个角色

我建议先做三个：

code-reviewer：只负责代码审查，优先找 bug、风险和缺测试。
test-planner：只负责根据改动建议测试点。
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 可以前台运行，也可以后台运行。前台会阻塞主会话，权限提示会正常传给你；后台可以并行，但遇到需要确认的工具调用通常会被自动拒绝。

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

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

参考资料：