# Subagents 完整参考 ## 概览 Subagents 是专门处理某类任务的独立 AI 助手。它们拥有隔离的上下文、自己的提示词和工具权限，适合把复杂工作拆分给不同角色。 ## 主要好处 - 上下文隔离 - 角色分工清晰 - 适合并行和委派 - 便于把复杂任务拆开 ## 文件位置 - 项目级：`.claude/agents/` - 用户级：`~/.claude/agents/` ## 配置 ### 文件格式 Subagent 通常是一个带 frontmatter 的 Markdown 文件。 ```yaml --- name: code-reviewer description: 审查代码质量和安全问题 tools: Read, Grep, Bash --- # Code Reviewer ``` ### 配置字段 | 字段 | 说明 | |------|------| | `name` | subagent 名称 | | `description` | 何时该调用它 | | `tools` | 允许使用的工具 | | `model` | 指定模型 | | `prompt` | 任务提示词 | | `context` | 上下文策略 | ### 工具配置选项 - 只读审查 - 限制 Bash - 允许更强工具集 ### 基于 CLI 的配置 你也可以通过命令行或设置文件定义 subagent。 ## 内置 Subagents Claude Code 自带一些常见角色，例如： - 通用助手 - Planning agent - Explore agent - Bash agent - Statusline 相关 agent - Claude Code Guide agent ## 管理 Subagents ### 使用 `/agents` 命令（推荐） ```bash /agents ``` ### 直接管理文件 #### 创建项目 subagent ```bash mkdir -p .claude/agents ``` #### 创建用户 subagent ```bash mkdir -p ~/.claude/agents ``` ## 使用 Subagents ### 自动委派 主 agent 可以根据任务描述自动把工作分配给合适的 subagent。 ### 显式调用 你也可以明确让 Claude 使用某个 subagent。 ### `@` 提及调用 在一些场景里，可以通过 `@agent-name` 方式引用。 ### 会话级 agent 可以在整个会话中固定使用某个 agent。 ### 列出可用 agents ```bash claude agents ``` ## 可恢复的 agents 某些 subagent 可以先启动，之后再恢复，便于长任务接力。 ## 串联 Subagents 复杂任务里可以让多个 subagent 依次协作，例如： 1. 代码审查 2. 测试生成 3. 文档更新 ## Subagents 的持久记忆 Subagents 可以拥有自己的 memory 范围，让它们在各自职责内保持一致。 ### Memory 范围 - 项目级 - 用户级 - 子目录级 ### 工作方式 Subagent 会在自己的上下文中读取对应记忆，不和主会话完全混在一起。 ## 后台 Subagents ### 配置 有些 subagent 可以作为后台任务执行，不阻塞主会话。 ### 快捷键 在支持的界面中，可用快捷键查看或切换后台 subagent。 ### 关闭后台任务 如果你不想让任务后台运行，可以在设置中关闭。 ## Worktree 隔离 ### 配置 可以为 subagent 分配独立的 worktree。 ### 工作方式 这样不同任务就不会互相污染文件状态。 ## 限制可启动的 Subagents 你可以限制 Claude 只能 spawn 某些 subagent，以降低风险。 ### 示例 - 只允许审查类 agent - 禁止高风险自动化 agent ## `claude agents` CLI 命令 用于查看和管理当前可用的 agent。 ## Agent Teams（实验性） Agent teams 是更高级的协作模式，适合多个 subagent 并行处理复杂任务。 ### Subagents vs Agent Teams - Subagents 侧重委派单个任务 - Agent teams 侧重多角色协作 ### 启用 Agent Teams 通过设置打开实验性功能。 ### 启动团队 团队模式会把不同任务分配给不同角色。 ### 显示模式 可以选择更适合终端或图形界面的显示方式。 ### 导航 你可以在 team 中切换角色、查看状态和读取消息。 ### 团队配置 适合为大型流程定义清晰角色。 ### 架构 agent team 本质上是多个专门角色围绕同一任务协作。 ### 任务分配与消息 主 agent 会负责把任务拆分并转发给对应 subagent。 ### 计划审批流程 如果是 plan 驱动流程，团队会先审计划再执行。 ### 团队相关 hook 事件 一些 hook 可以在 team 生命周期里触发。 ### 最佳实践 - 角色定义要清楚 - 任务边界要明确 - 不要让多个 agent 做重复工作 ### 局限 - 实验性功能可能会变化 - 复杂团队需要更多配置 ## 插件中的 Subagent 安全 插件分发的 subagent 要特别注意权限、工具范围和边界条件。 ## 架构 ### 高层架构 主 agent、subagent、文件系统和工具权限共同构成执行链。 ### 生命周期 1. 创建 2. 分配任务 3. 执行 4. 返回结果 5. 结束或恢复 ## 上下文管理 ### 关键点 - 子上下文尽量小 - 让每个 subagent 只负责自己的事 - 避免把所有信息都塞进去 ### 性能考虑 过多的上下文会拖慢速度并降低准确性。 ### 关键行为 subagent 在隔离上下文里工作，但仍能把结果汇总回主会话。 ## 什么时候使用 Subagents - 任务可拆分 - 需要隔离上下文 - 需要明确角色分工 - 需要并行协作 ## 最佳实践 ### 设计原则 - 单一职责 - 描述明确 - 工具权限最小化 ### System Prompt 最佳实践 - 任务说明要具体 - 不要写太长 - 只保留执行任务所需的信息 ### 工具访问策略 - 审查型 subagent 只读 - 实现型 subagent 适度开放写权限 - 高风险动作要保持审批 ## 本目录中的示例 Subagents ### 1. [Code Reviewer](./code-reviewer.md) 用于全面代码质量审查。 ### 2. [Test Engineer](./test-engineer.md) 用于测试策略、覆盖率和测试生成。 ### 3. [Documentation Writer](./documentation-writer.md) 用于技术文档写作和更新。 ### 4. [Secure Reviewer](./secure-reviewer.md) 用于安全检查，通常只读。 ### 5. [Implementation Agent](./implementation-agent.md) 用于功能实现和代码修改。 ### 6. [Debugger](./debugger.md) 用于定位 bug 和分析异常。 ### 7. [Data Scientist](./data-scientist.md) 用于分析数据、解释结果和生成报告。 ### 8. [Clean Code Reviewer](./clean-code-reviewer.md) 用于按 Clean Code 原则做专门审查。 ## 安装说明 ### 方法 1：使用 `/agents` ```bash /agents ``` ### 方法 2：复制到项目 ```bash mkdir -p .claude/agents cp 04-subagents/*.md .claude/agents/ ``` ### 方法 3：复制到用户目录 ```bash mkdir -p ~/.claude/agents cp 04-subagents/*.md ~/.claude/agents/ ``` ### 验证 - 运行 `/agents` - 检查对应 agent 是否出现在列表中 - 试着让 Claude 委派一个简单任务 ## 文件结构 ```text .claude/agents/ ├── clean-code-reviewer.md ├── code-reviewer.md ├── data-scientist.md ├── debugger.md ├── documentation-writer.md ├── implementation-agent.md ├── secure-reviewer.md ├── test-engineer.md └── README.md ``` ## 相关概念 - [Skills 中文指南](../03-skills/README.md) - [Memory 中文指南](../02-memory/README.md) - [Hooks 中文指南](../06-hooks/README.md) - [Plugins 中文指南](../07-plugins/README.md)