在 AI 辅助编程的时代，如何让 AI 更好地协助我们完成复杂任务？Claude Code 的 Subagents 功能提供了一个优雅的解决方案：通过专业化、模块化的 AI 助手，将复杂任务分解为多个子任务，每个子任务由专门的 AI Agent 处理。

本文将深入探讨 Subagents 的设计理念、架构实现、配置方法和实战技巧，帮助你构建高效的 AI 助手体系。

Subagents（子代理）是 Claude Code 中的专业化 AI 助手，它们具有以下核心特征：

• 独立上下文窗口：每个 Subagent 拥有独立的对话上下文，不会污染主对话
• 专业化定位：通过自定义 System Prompt 针对特定领域进行优化
• 工具访问控制：可以限制 Subagent 只能访问特定的工具集
• 任务委托机制：主 Agent 可以将任务委托给最适合的 Subagent

MERMAID_BLOCK_0

Subagents 最重要的设计特性是上下文隔离。每个 Subagent 启动时都获得一个干净的上下文窗口，只接收完成任务所需的最少信息。

MERMAID_BLOCK_1

这种设计的优势：

1. 防止上下文污染：复杂任务的分析过程不会影响主对话
2. 节省 Token：只有最终结果被传递回主对话
3. 并行执行：多个 Subagent 可以同时工作
4. 专业化优化：每个 Subagent 可以针对特定任务优化

MERMAID_BLOCK_2

Subagents 可以定义在多个位置，按以下优先级加载（优先级高的覆盖优先级低的）：

--- name: code-reviewer description: 专家代码审查员。在编写或修改代码后主动使用以确保质量、安全性和可维护性。 tools: Read, Grep, Glob, Bash model: inherit permissionMode: default maxTurns: 20 skills: security-analysis mcpServers: github memory: project background: false effort: high isolation: worktree initialPrompt: "首先分析最近的代码变更" hooks:  PreToolUse:  - matcher: "Bash"  hooks:  - type: command  command: "./scripts/security-check.sh" --- 

Claude Code 提供了多个内置 Subagents，开箱即用：

• 模型：继承父 Agent
• 工具：所有工具
• 用途：复杂研究任务、多步骤操作、代码修改

• 模型：Haiku（快速、低延迟）
• 工具：Glob、Grep、Read、Bash（只读命令）
• 用途：快速代码库搜索和分析

探索深度级别：
- "quick" - 快速搜索，最小化探索
- "medium" - 中等探索，平衡速度和深度（默认）
- "very thorough" - 全面分析，涵盖多个位置和命名约定

• 模型：继承父 Agent
• 工具：Read、Glob、Grep、Bash
• 用途：在计划模式下自动研究代码库

• 模型：继承父 Agent
• 工具：Bash
• 用途：在独立上下文中执行终端命令

--- name: code-reviewer description: 专家代码审查员。在编写或修改代码后主动使用以确保质量、安全性和可维护性。 tools: Read, Grep, Glob, Bash model: inherit --- # Code Reviewer Agent 你是一位高级代码审查员，确保高质量的代码标准和安全性。 调用时： 1. 运行 git diff 查看最近的变更 2. 专注于修改的文件 3. 立即开始审查  审查优先级（按顺序） 1. 安全问题 - 认证、授权、数据泄露 2. 性能问题 - O(n²) 操作、内存泄漏、低效查询 3. 代码质量 - 可读性、命名、文档 4. 测试覆盖 - 缺失的测试、边界情况 5. 设计模式 - SOLID 原则、架构  审查输出格式 对于每个问题： - 严重性：严重 / 高 / 中 / 低 - 类别：安全 / 性能 / 质量 / 测试 / 设计 - 位置：文件路径和行号 - 问题描述：问题是什么以及为什么 - 建议修复：代码示例 - 影响：这如何影响系统 按优先级组织反馈： 1. 严重问题（必须修复） 2. 警告（应该修复） 3. 建议（考虑改进） 

--- name: test-engineer description: 测试自动化专家，用于编写全面的测试。在实现新功能或修改代码时主动使用。 tools: Read, Write, Bash, Grep model: inherit --- # Test Engineer Agent 你是一位专业的测试工程师，专注于全面的测试覆盖。 调用时： 1. 分析需要测试的代码 2. 识别关键路径和边界情况 3. 遵循项目约定编写测试 4. 运行测试以验证通过  测试策略 1. 单元测试 - 隔离测试单个函数/方法 2. 集成测试 - 组件交互 3. 端到端测试 - 完整工作流 4. 边界情况 - 边界条件、空值、空集合 5. 错误场景 - 失败处理、无效输入  覆盖要求 - 最低 80% 代码覆盖率 - 关键路径 100% 覆盖（认证、支付、数据处理） - 报告缺失的覆盖区域 

--- name: debugger description: 调试专家，用于错误、测试失败和意外行为。遇到任何问题时主动使用。 tools: Read, Edit, Bash, Grep, Glob model: inherit --- # Debugger Agent 你是一位专业的调试专家，专注于根因分析。 调用时： 1. 捕获错误消息和堆栈跟踪 2. 识别复现步骤 3. 隔离故障位置 4. 实现最小修复 5. 验证解决方案  调试过程 1. 分析错误消息和日志  - 读取完整的错误消息  - 检查堆栈跟踪  - 查看最近的日志输出 2. 检查最近的代码变更  - 运行 git diff 查看修改  - 识别可能的破坏性变更  - 审查提交历史 3. 形成和测试假设  - 从最可能的原因开始  - 添加战略性调试日志  - 检查变量状态 4. 隔离故障  - 缩小到特定函数/行  - 创建最小复现案例  - 验证隔离 5. 实施和验证修复  - 进行最小的必要更改  - 运行测试确认修复  - 检查回归 

memory 字段为 Subagent 提供一个跨对话持久化的目录，允许 Subagent 随着时间积累知识。

--- name: researcher memory: project --- 你是一位研究助手。使用你的内存目录存储发现、跟踪跨会话的进度， 并随着时间的推移建立知识。 每次会话开始时检查你的 MEMORY.md 文件以回忆之前的上下文。 

内存作用域：

Subagent 可以在后台运行，释放主对话用于其他任务。

--- name: long-runner background: true description: 在后台执行长时间运行的分析任务 --- 

快捷键：
- Ctrl+B - 将当前运行的 Subagent 任务后台化
- Ctrl+F - 终止所有后台 Agent（按两次确认）

isolation: worktree 设置为 Subagent 提供自己的 git worktree，允许它独立进行更改而不影响主工作树。

--- name: feature-builder isolation: worktree description: 在隔离的 git worktree 中实现功能 tools: Read, Write, Edit, Bash, Grep, Glob --- 

使用 Agent(agent_type) 语法控制 Subagent 可以生成哪些其他 Subagent：

--- name: coordinator description: 协调专业化代理之间的工作 tools: Agent(worker, researcher), Read, Bash --- 你是一个协调代理。你只能将工作委托给 "worker" 和 "researcher" 子代理。 使用 Read 和 Bash 进行你自己的探索。 

应该做的：

1. 从 Claude 生成的 Agent 开始 - 用 Claude 生成初始 Subagent，然后迭代定制
2. 设计专注的 Subagent - 单一、明确的职责，而不是一个做所有事情
3. 编写详细的提示 - 包括具体指令、示例和约束
4. 限制工具访问 - 只授予 Subagent 目的所需的工具
5. 版本控制 - 将项目 Subagent 纳入版本控制以进行团队协作

不应该做的：

1. 创建具有相同角色的重叠 Subagent
2. 给予 Subagent 不必要的工具访问权限
3. 对简单的单步骤任务使用 Subagent
4. 在一个 Subagent 的提示中混合关注点
5. 忘记传递必要的上下文

1. 明确角色
   你是一位专门从事 [特定领域] 的专家代码审查员
   
   
   
   
   
2. 清晰定义优先级
   
   审查优先级（按顺序）：
   
   
   
   
   
   
   
   
   
   
   
   
3. 安全问题
4. 性能问题
5. 代码质量
   
   
   
   
   
   
6. 指定输出格式
   对于每个问题提供：严重性、类别、位置、描述、修复、影响
   
   
   
   
   
7. 包含操作步骤
   
   调用时：
   
   
   
   
   
   
   
   
   
   
   
   
8. 运行 git diff 查看最近的变更
9. 专注于修改的文件
10. 立即开始审查
    
    
    
    
    

1. 从限制性开始：仅从基本工具开始
2. 按需扩展：根据需求添加工具
3. 尽可能只读：对分析 Agent 使用 Read/Grep
4. 沙箱执行：将 Bash 命令限制为特定模式

MERMAID_BLOCK_3

Agent Teams 协调多个 Claude Code 实例一起处理复杂任务。与 Subagents（委托子任务并返回结果）不同，teammates 独立工作，拥有自己的上下文窗口，可以通过共享邮箱系统直接相互消息传递。

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 

或在 settings.json 中：

{  “env”: {  “CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS”: “1”  } } 

• 主对话保护：Subagents 保护主上下文，实现更长的会话
• Token 优化：只有结果被传递回主对话
• 并行执行：多个 Subagents 可以同时工作

• 初始化开销：Subagents 从干净的上下文开始，可能会增加收集初始上下文的延迟
• 自动压缩：Subagent 上下文在约 95% 容量时自动压缩

• 无嵌套生成：Subagents 不能生成其他 Subagents
• 后台权限：后台 Subagents 自动拒绝任何未预先批准的权限
• 后台化：按 Ctrl+B 将当前运行的任务后台化
• 转录存储：Subagent 转录存储在 ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl

Claude Code 的 Subagents 功能为构建专业化 AI 助手体系提供了强大的基础设施。通过合理设计和配置 Subagents，你可以：

1. 提高开发效率：将复杂任务分解为专业化的子任务
2. 保护上下文：防止长对话中的上下文污染
3. 并行执行：多个 Subagents 同时工作
4. 专业化优化：每个 Subagent 针对特定任务优化
5. 团队协作：通过版本控制共享 Subagents 配置

关键是从小处开始，逐步迭代，根据实际需求设计和优化你的 Subagents。记住，最好的 Subagent 是专注于单一职责、配置合理、提示明确的 Agent。

参考资源：Claude Code Subagents 官方文档 | GitHub Repository