用 Claude Code 做项目时，最容易遇到的不是“AI不会写代码”，而是主对话很快被搜索结果、日志、文件片段和临时推理塞满。等真正要改代码时，上下文已经变得很乱。
Subagents 解决的就是这个问题：把某类重复任务交给专用 AI 助手，让它在独立上下文里完成搜索、分析或执行，最后只把结论交回主对话。对长期维护项目的人来说，它比临时喊一句“帮我检查代码”更稳定，也更容易形成团队规范。
如果你还在比较不同 AI 编程工具，可以先看 AI编程工具专题 和 Claude专题。本文重点放在 Claude Code Subagents 的实际用法，不再重复安装和基础命令。
Subagents适合解决什么问题
Anthropic 官方文档把 Subagents 定义为专门处理特定任务的 AI 助手。它们有自己的上下文窗口、系统提示词、工具访问范围和权限设置。换句话说，Subagent 不是简单的提示词模板，而是一个可复用的“角色 + 权限 + 工具边界”。
我更建议把它用在三类任务上。
- 代码库探索：搜索目录、阅读相关文件、梳理模块关系，但不直接改代码。
- 质量检查：做代码审查、测试失败分析、安全风险检查，把问题汇总给主对话。
- 重复交付：生成变更说明、补文档、整理迁移清单、检查发布前事项。
这些任务都有一个共同点：过程材料很多，但最终你只需要结论。把它们留在主对话里，会消耗上下文，也会影响后续决策。
先不要一上来就建很多代理
很多人第一次看到 Subagents，会想给每个岗位都建一个：架构师、测试员、安全员、文档员、产品经理。这样很快会变成另一种混乱。
更稳的做法是从一个高频痛点开始。例如你每次提交前都要让 AI 检查代码质量，可以先建一个 code-reviewer。它只负责阅读变更、找风险、给出建议，不负责重写整个项目。
一个好的 Subagent 描述应该具体到“什么时候用它”。例如：
Use this agent when you need a read-only review of recent code changes,
including correctness risks, missing tests, security concerns, and maintainability issues.
Return findings with file references and severity.这类描述比“你是一个资深程序员，请帮我看代码”有效得多，因为 Claude Code 可以根据 description 判断是否应该委派任务。
推荐的三个入门Subagent
1. 只读代码审查助手
这是最适合新手的第一个 Subagent。它只开放只读工具，不允许写文件。你可以让它检查最近修改、潜在 bug、边界条件、缺失测试和不一致的项目规范。
它的价值不在于替你写代码，而在于把“发现问题”从“解决问题”里拆出来。这样主对话可以专注于取舍和修改，避免一边搜索一边改、一边改一边忘。
2. 测试失败分析助手
测试失败时，主对话经常会被日志淹没。一个 test-debugger 可以专门读取失败日志、定位相关测试和源文件、判断是实现问题还是测试问题，然后给出最小修复建议。
如果你正在用 Hooks 把格式化和测试接入 Claude Code，可以结合这篇旧文：Claude Code Hooks怎么用？把格式化、测试和安全检查自动接进AI编程流程。Hooks 负责触发检查，Subagent 负责分析结果，两者分工并不冲突。
3. 文档和交接助手
很多项目不是败在代码写不出来，而是改完以后没人知道改了什么。一个 docs-writer 可以根据变更整理 README、迁移说明、PR 描述、用户可见更新点。
这类助手适合开放读写文档的权限，但不要让它直接改业务代码。权限边界越清楚，后续越容易信任它。
配置时最重要的是权限边界
Subagents 可以通过不同作用域保存：项目级适合团队共享，用户级适合个人跨项目复用。对真实项目，我更推荐把项目相关的代理放在项目目录下，让团队一起维护；个人习惯类代理再放到用户级目录。
配置时要重点看三件事。
- 工具权限：只读分析助手不要给写入权限；真正要执行改动的助手再开放编辑工具。
- 模型选择：简单搜索和整理可以用更轻的模型，复杂重构或跨文件判断再用更强模型。
- 记忆范围：如果要跨会话积累项目规律，才启用长期记忆；一次性任务不一定需要。
这和 Claude Code 项目记忆怎么写？CLAUDE.md 实战模板与避坑清单 的思路是一致的：规则不是越多越好，而是要让 AI 在关键时刻少猜一点。
Subagents和主对话怎么分工
主对话应该负责目标、取舍和最终决策；Subagents 负责收集证据、执行局部检查和输出结构化结论。
一个比较稳的工作流可以这样安排：
- 主对话说明目标：例如“准备发布这个功能，先做风险检查”。
- 代码审查 Subagent 只读扫描变更，列出问题和文件位置。
- 测试分析 Subagent 查看失败日志，判断是否需要补测试。
- 主对话综合结论，决定改哪些、不改哪些。
- 必要时再让执行型助手改代码，最后由主对话复核。
如果你习惯让 Claude Code 和 Codex 协作，也可以把 Subagents 看成 Claude Code 内部的细分岗位。跨工具协作的思路，可以参考 Claude Code 和 Codex 怎么协作？一个项目里分工使用两款 AI 编程工具。
什么时候不该用Subagents
Subagents 不是所有任务的默认答案。下面几种情况，直接在主对话里做反而更清楚。
- 任务很小，只需要改一两行代码。
- 你还没有搞清目标，正在和 AI 一起讨论方案。
- 任务需要连续决策，拆出去反而会丢失上下文。
- 项目规范还没稳定，给专用代理写规则会频繁返工。
简单说，Subagents 适合“重复、边界清楚、过程材料多、结果可汇总”的任务。不符合这四点，就先别急着拆。
老达点评
Claude Code Subagents 真正有价值的地方，不是让一个项目里出现很多 AI 角色，而是把 AI 编程从“单线程聊天”推进到“可控分工”。
对个人开发者和站长来说，最应该优先落地的是只读审查、测试分析和文档交接。它们风险低、收益稳定，也容易形成可复用的项目资产。等这些流程跑顺了，再考虑更复杂的执行型代理。
如果你正在系统搭建 AI Agent 工作流，可以继续看 AI智能体与自动化专题。Subagents 不是终点，它更像是把 AI 助手纳入工程流程的一个关键零件。
