功能对比
| Subagent 角色 | 适合场景 | 预期输出 |
|---|---|---|
| Researcher | 文档、代码搜索、依赖或 API 调研 | 带来源、约束和建议路径的 brief |
| Implementer | 已知范围内的聚焦代码修改 | 改动摘要和 changed files 说明 |
| Test fixer | 失败检查、不稳定测试、缺失覆盖 | 失败原因、修复和验证命令 |
| Reviewer | 合并或交接前的风险审查 | 带文件和行号的 findings |
| Migration planner | 大重构、框架升级、package 迁移 | 分阶段计划、负责人和回滚说明 |
什么是 Claude Code Subagents
Claude Code subagents 是命名的专家代理，Claude 可以把聚焦工作委派给它们。每个 subagent 可以有 description、system prompt、allowed tools、model choice 和独立上下文窗口。
- 项目 subagents 放在 .claude/agents/，可随仓库共享。
- 个人 subagents 放在 ~/.claude/agents/，可跨项目使用。
- 文件使用 YAML frontmatter 加 Markdown 指令。
- Claude Code 可根据 description 自动选择，也可以由用户点名使用。
官方与社区资源
语法和生命周期行为以官方文档为准；社区模板需要审查权限和提示词后再使用。
什么时候使用 Subagents
当工作可拆分、需要专业角色，或同类任务频繁重复时使用 subagents。简单单文件修改通常留在主会话更快。
- 文档、代码搜索和依赖调研用 researcher。
- 实现后风险审查用 reviewer。
- 测试失败诊断用 test fixer。
- 大型迁移前用 migration planner。
- 认证、权限、密钥或工具访问变化时用 security reviewer。
20 个常用 Subagent 模板
下方生成器包含 20 个高频模板。
- code-reviewer、test-writer、bug-hunter、frontend-implementer、api-integrator
- database-migration-planner、security-reviewer、performance-profiler、docs-writer、release-notes-writer
- dependency-upgrader、refactor-planner、mcp-config-reviewer、prompt-engineer、qa-scenario-builder
- monorepo-coordinator、design-implementation-auditor、incident-investigator、data-analyst、localization-reviewer
可复制 Markdown Subagent
从小而明确的 subagent 开始。description 说明何时使用，prompt 定义范围、输出和验证。
--- name: code-reviewer description: Review diffs for correctness, security, regressions, and missing tests. tools: Read, Grep, Glob, Bash(git diff *) model: sonnet --- Inspect the current diff. Return findings first with file and line references, then list test gaps and residual risks.
Subagents、Hooks、MCP 与 Worktrees
Subagents 可以和 hooks、MCP、隔离 worktrees 配合，但每一层都需要清晰边界。
- Hooks 执行确定性生命周期命令；subagents 负责专家推理或审查。
- MCP 提供 GitHub、docs、browser 或 database 等外部上下文。
- 多个代理修改独立任务时，worktree isolation 更安全。
- Reviewer、security、docs agents 的工具权限应保持窄范围。
常见错误
角色重叠、工具权限太宽、没有最终集成负责人，都会让 subagents 变得嘈杂。
- 避免多个 subagents 同时编辑同一批文件。
- 避免 be helpful 或 write clean code 这类空泛提示。
- 审查型 agent 不要给过宽 Bash 权限。
- 保留一个主代理整合结果并运行最终检查。
Subagent 模板库与生成器
选择角色、切换输出格式，然后复制项目或个人 subagent 文件。
--- name: code-reviewer description: Review diffs for correctness, security, regressions, and missing tests. tools: Read, Grep, Glob, Bash(git diff *) model: sonnet --- # code-reviewer Inspect the current diff. Return findings first with file and line references, then list test gaps and residual risks. ## Scope - Category: Review - Stay inside the requested files or workstream. - Do not expose secrets or broaden permissions. ## Handoff Return the result, files touched, validation evidence, and remaining risks.
常见问题
如何创建 Claude Code subagent？
在 .claude/agents/ 创建项目 subagent，或在 ~/.claude/agents/ 创建个人 subagent。文件包含 YAML frontmatter 和 Markdown 指令。
如何在 Claude Code 中使用 subagents？
Claude Code 可以根据 description 自动选择，也可以由用户直接要求使用某个命名 subagent。
Subagents 总是更快吗？
不是。只有任务能干净拆分或需要专家上下文时才有帮助。
主代理应该做什么？
协调范围、只委派可拆分工作、整合结果并验证最终状态。
Subagents 能使用 MCP tools 吗？
可以，前提是环境暴露这些工具且 subagent 被允许使用。权限应保持窄范围并记录清楚。
Subagents 和 hooks 有什么区别？
Hooks 是确定性生命周期自动化；subagents 是面向特定角色的 Claude 专家助手。
Subagents 和 custom commands 有什么区别？
Custom commands 是用户触发的提示词快捷方式；subagents 是 Claude 可在任务中委派的专家角色。
好的 subagent 模板应包含什么？
角色、触发描述、工具、模型、范围、禁止事项、输出格式和验证命令。