Claude Code Subagents多智能体实战教程：测试、审查、文档、安全四个AI角色怎么协同开发？

如果说 2025 年的 AI 编程关键词是 Cursor、Copilot、代码补全，那么 2026 年最明显的变化就是：AI 编程开始从“单个助手”变成“AI 开发团队”。

最近 Claude Code 相关教程里，Subagents、Agent Teams、多智能体并行开发这些词越来越火。很多人第一次听到会觉得很玄：是不是让几个 AI 在一起聊天？是不是会变成一堆不可控的 Token 黑洞？到底有没有真实开发价值？

我自己的结论是：Claude Code Subagents 不是噱头，它最适合把重复、专业、边界清晰的工程角色固定下来。比如测试 Agent 专门补测试，审查 Agent 专门看 diff，文档 Agent 专门写 README，安全 Agent 专门看权限和注入风险。

这篇文章写一份实战教程：Claude Code Subagents 到底怎么理解？如何设计测试、审查、文档、安全四个 AI 角色？怎么和 Codex 配合？国内开发者又如何用 bblabu API 中转站 控制多 Agent 带来的 Token 成本？

一、什么是 Claude Code Subagents？

简单说，Subagent 就是给 Claude Code 固定一个“专业角色”。它不是普通提示词里的“你是一个资深工程师”，而是更工程化的角色配置：有明确职责、上下文边界、工具权限和输出格式。

你可以把主会话理解为项目经理，把 Subagents 理解为团队成员：

它解决的不是“让 AI 更聪明”，而是“让 AI 分工更稳定”。

二、为什么不要一个 Agent 做所有事？

很多人用 Claude Code 或 Codex 的方式是：直接说“帮我修这个 Bug”。这当然能跑，但问题也明显：

• 上下文越来越长，容易污染；
• 模型一边分析一边改代码，容易跑偏；
• 测试、审查、文档、安全检查混在一起，质量不稳定；
• 失败后反复重试，Token 成本不可控。

我更推荐把任务拆成几段：

1. 主会话负责定义目标；
2. 分析阶段用 Claude Code 理清原因；
3. 执行阶段可以交给 Codex；
4. 测试、审查、文档、安全由 Subagents 各自负责；
5. 最后由人做一次最终确认。

这套方式更像真实团队协作：一个人写代码，另一个人 review，另一个人补测试，另一个人看安全。

三、四个最实用的 Subagent 角色

我建议不要一上来设计十几个 Agent。先从四个最实用的开始。

3.1 测试 Agent

职责：只关心测试，不负责大范围改业务逻辑。

你是测试 Agent。你的职责是根据当前 diff 或需求补充测试。
规则：
1. 优先补单元测试和边界测试；
2. 不要大范围修改业务代码；
3. 输出新增测试点、涉及文件和验证命令；
4. 如果缺少上下文，先提出需要读取的文件，不要全项目扫描。

适合场景：修 Bug 后补回归测试、重构后验证兼容性、给核心函数补边界 case。

3.2 审查 Agent

职责：像 code reviewer 一样看 diff。

你是代码审查 Agent。你的职责是审查当前 git diff。
重点检查：
1. 是否解决原始需求；
2. 是否有过度重构；
3. 是否影响兼容性；
4. 是否遗漏边界情况；
5. 是否存在明显性能问题。
只输出 review 结论，不要修改代码。

审查 Agent 非常适合放在 Codex 改完代码之后，用来做二次把关。

3.3 文档 Agent

职责：写文档、PR 描述、迁移说明。

你是文档 Agent。你的职责是根据代码变更生成文档。
输出格式：
- 变更背景
- 使用方式
- 配置项说明
- 兼容性影响
- PR 描述
要求：语言简洁，不夸大，不写营销话术。

很多项目的问题不是没人改代码，而是改完没人写说明。文档 Agent 可以把这件事固定下来。

3.4 安全 Agent

职责：看权限、输入校验、密钥泄漏、注入风险。

你是安全审查 Agent。你的职责是检查当前变更是否引入安全风险。
重点检查：
1. API Key、Token、密码是否泄漏；
2. 是否有 SQL 注入、命令注入、路径穿越风险；
3. 权限判断是否被绕过；
4. 日志是否输出敏感信息；
5. 新增依赖是否可疑。
只输出风险清单和修复建议，不要直接修改代码。

安全 Agent 不一定每次都能发现高危问题，但它能帮你建立固定检查习惯。

四、推荐工作流：Claude Code 规划，Codex 执行，Subagents 把关

我实际用下来，最稳定的流程是：

这比让一个 Agent 从头干到尾更稳。因为每个角色只做一件事，上下文更干净，输出也更可控。

五、一个真实例子：登录接口加限流

假设需求是：

登录接口需要增加限流，防止同一个 IP 或账号短时间内暴力尝试密码。

第一步，让 Claude Code 主会话分析：

请阅读登录接口相关代码，分析当前认证流程，并输出限流方案。
要求：
1. 只分析，不修改；
2. 说明需要修改的文件；
3. 给出最小实现方案；
4. 给出测试建议。

第二步，让 Codex 执行：

请按下面方案实现登录限流：
- 修改 auth/login.ts 和 tests/auth/login.test.ts；
- 按 IP + username 组合计数；
- 5 分钟内失败超过 5 次返回 429；
- 成功登录后清理失败计数；
- 补充超过限制、成功清理、不同 IP 不互相影响的测试。
先展示计划，再修改文件。

第三步，测试 Agent 补充测试：

请只审查测试覆盖，不改业务代码。检查是否覆盖：
1. 同 IP 同账号连续失败；
2. 成功登录后清理计数；
3. 不同 IP 隔离；
4. 不同账号隔离；
5. 边界次数 5 和 6。

第四步，安全 Agent 检查风险：

请审查当前 diff 的安全风险，重点看：
1. 是否泄漏登录失败原因；
2. 是否可被绕过；
3. 是否存在内存无限增长；
4. 是否会误伤正常用户。

第五步，文档 Agent 写 PR 描述：

请根据当前 diff 生成 PR 描述，包含背景、修改内容、测试结果、风险和回滚方式。

这就是 Subagents 的价值：不是让 AI 更花哨，而是让流程更像真实工程团队。

六、Subagents 会不会让 Token 成本暴涨？

会，如果你不控制。多智能体不是免费午餐。每多一个 Agent，就可能多一次上下文读取、多一次推理、多一次输出。

所以我会把多 Agent 成本拆开管理。通过 bblabu API 中转站 给不同角色建不同 Key：

这样好处很明显：哪个 Agent 最费钱，一眼能看出来。某个 Agent 跑飞，也不会影响主力 Key。

这也是我推荐重度 AI 编程用户用 bblabu 的原因：不只是便宜，而是能把多工具、多 Agent 的成本拆清楚。

七、API 配置：Claude Code 和 Codex 分开填

Claude Code 走 Anthropic 兼容接口：

export ANTHROPIC_API_KEY="你的 bblabu Claude Key"
export ANTHROPIC_BASE_URL="https://api.bblabu.cn"

Codex 走 OpenAI 兼容接口：

export OPENAI_API_KEY="你的 bblabu Codex Key"
export OPENAI_BASE_URL="https://api.bblabu.cn/v1"

注意两个区别：

• Claude Code：https://api.bblabu.cn，不加 /v1；
• Codex：https://api.bblabu.cn/v1，要加 /v1。

完整安装和配置流程可以看 docx.kkkliao.cn，里面把 Node.js、Claude Code、Codex、CC Switch 都写成了从零教程。

八、主备线路：多 Agent 更需要稳定性

单个 Agent 出问题，还可以手动重试。多 Agent 流程一旦跑起来，中间某个请求断掉，就会影响整条链路。

所以我建议一开始就配置主备线路：

如果你用 CC Switch，建议把主线和备线都做成 Provider，托盘里一键切换。

九、Subagents 的使用原则

我总结了几条实践原则：

1. 一个 Agent 只做一件事：不要让测试 Agent 又写文档又改业务。
2. 先分析后修改：能降低跑偏概率。
3. 限制读取范围：不要动不动全项目扫描。
4. 输出格式固定：让结果更容易被主会话整合。
5. 高风险操作人工确认：数据库、权限、部署相关不要全自动。
6. 每个角色独立预算：防止某个 Agent 成本失控。

Subagents 的目标不是炫技，而是把 AI 工作变得可重复、可审查、可控制。

十、什么时候不适合用 Subagents？

不是所有任务都需要多 Agent。

我的经验是：超过 3 个文件、涉及测试或安全、需要 PR 审查的任务，就值得上 Subagents。

总结：多智能体不是让 AI 更乱，而是让 AI 更像工程团队

Claude Code Subagents 的核心价值，不是“多个 AI 一起聊天”，而是把工程里的重复角色固定下来：测试、审查、文档、安全、执行。

我的推荐组合是：

• Claude Code 主会话：需求分析和任务拆解；
• Codex：执行代码修改和测试；
• 测试 Agent：补测试和边界 case；
• 审查 Agent：review diff；
• 安全 Agent：看权限、注入、密钥泄漏；
• 文档 Agent：生成 PR 描述和说明；
• bblabu API 中转站：统一模型入口、Key、账单和主备线路。

如果你还在一个聊天窗口里让 AI 从头干到尾，可以试试这套分工方式。先从测试 Agent 和审查 Agent 两个角色开始，跑通之后再加安全和文档。你会发现，AI 编程的质量会稳定很多，返工也会少很多。

相关资源

• 🏠 bblabu API 中转站主线
• 🔄 bblabu API 中转站备线
• 📖 Claude Code / Codex / CC Switch 完整教程
• 🧠 Claude Code + Codex 从 Issue 到 PR 工作流
• 🔌 MCP 接入 Claude Code / Cursor / Codex 教程
• ⚖️ AI 编程工具横评

—— 廖万里 · 2026年6月6日实测整理