04-Sub Agent 任务分发

使用 Claude Code 的 Agent 工具实现多任务并行处理，大幅提升复杂项目的开发效率。

---

一、Sub Agent 基础概念

1.1 什么是 Sub Agent

Sub Agent 是 Claude Code 的任务分发机制，允许并行执行多个独立的子任务。

工作流程:

主任务
    ├── 子任务1（并行执行）
    ├── 子任务2（并行执行）
    ├── 子任务3（并行执行）
    └── 子任务4（并行执行）
              ↓
         结果汇总
              ↓
         主任务继续

1.2 Claude Code 的并行机制

Claude Code 有两种并行执行方式：

方式	触发条件	适用场景
自动并行	独立的简单任务	文件创建、读取、简单修改
Agent 工具	复杂多步骤任务	代码探索、深度分析、大型重构

自动并行示例：

# Claude Code 会自动并行执行这些独立任务
> 生成 test.py，打印 test
> 生成 hello_world.py，打印 hello world

# Claude 在一条消息中并行调用多个 Write 工具

Agent 工具示例：

# 复杂任务需要使用 Agent
> 探索项目的数据库架构，找出所有使用外键的表
# Claude 会启动 Explore Agent 进行深度搜索

1.3 与 Cursor 的区别

特性	Claude Code	Cursor
调用方式	自动判断或显式 Agent	隐式自动并行
控制粒度	可精确控制每个子任务	系统自动管理
可见性	显示每个工具调用	内部处理
适用场景	复杂任务拆分、代码探索	编辑器内自动优化

---

二、Agent 工具详解

2.1 可用的 Agent 类型

Claude Code 提供多种专用 Agent：

Agent 类型	用途	典型场景
general-purpose	通用任务	复杂多步骤任务
Explore	代码库探索	查找文件、搜索代码、理解架构
Plan	实现规划	设计实现方案、架构决策
code-improvement-advisor	代码质量分析	代码审查、改进建议

2.2 Agent 工具参数

{
  "subagent_type": "Explore",        // Agent 类型
  "description": "搜索认证代码",      // 简短描述（3-5词）
  "prompt": "在项目中查找所有与用户认证相关的代码，包括登录、注册、JWT 处理",
  "model": "sonnet",                 // 可选：指定模型
  "run_in_background": true          // 可选：后台运行
}

2.3 使用场景对比

任务复杂度	推荐方式	示例
简单直接	自动并行	创建文件、读取内容、简单修改
中等复杂	自动判断	批量重命名、多文件修改
高度复杂	使用 Agent	代码库探索、架构分析、大型重构

---

三、任务管理工具

3.1 Task 系列工具

Claude Code 提供任务管理工具用于跟踪进度：

工具	功能	使用场景
TaskCreate	创建任务	开始复杂任务前
TaskList	列出所有任务	查看进度
TaskGet	获取任务详情	了解任务依赖
TaskUpdate	更新任务状态	标记完成/进行中

3.2 任务管理示例

# 创建复杂任务列表
> 帮我实现用户认证系统

# Claude 会自动创建任务：
1. 设计 User 数据模型
2. 实现密码加密
3. 创建登录 API
4. 实现 JWT 验证
5. 编写测试

3.3 任务依赖关系

任务1: 数据模型设计
    ↓ (blocks)
任务2: 数据库迁移 ──→ 任务3: API 实现
                         ↓
                    任务4: 测试编写

---

四、实战应用场景

场景1：并行生成 CRUD

# 简单任务：Claude 自动并行
> 创建以下文件：
  - src/models/user.py：User Pydantic 模型
  - src/services/user_service.py：UserService 类
  - tests/test_user.py：用户测试

# Claude 在一条消息中并行创建三个文件

场景2：复杂代码探索

# 复杂任务：使用 Agent
> 分析项目的整体架构，找出：
  1. 所有 API 端点
  2. 数据库模型关系
  3. 服务层依赖关系
  4. 潜在的性能瓶颈

# Claude 启动 Explore Agent 进行深度分析

场景3：批量代码审查

# 中等任务：自动并行 + 汇总
> 审查 src/services/ 下所有服务类，检查：
  - 代码规范性
  - 错误处理
  - 安全漏洞

# Claude 并行读取文件，汇总审查报告

---

五、任务拆分原则

5.1 何时需要显式拆分

不需要显式拆分：

• 简单的文件操作
• 明确的小范围修改
• Claude 能自动判断的任务

需要显式拆分：

• 大型功能开发
• 有依赖关系的多步骤任务
• 需要用户确认关键节点

5.2 任务拆分示例

好的拆分：

任务：开发完整的用户系统

第一批（并行，无依赖）：
1. 创建 User 数据模型
2. 创建 UserService 骨架
3. 创建 API 路由骨架

第二批（顺序，有依赖）：
4. 实现数据库迁移（依赖任务1）
5. 实现服务层逻辑（依赖任务1、2）
6. 编写集成测试（依赖任务3、5）

不好的拆分：

❌ 并行执行有依赖的任务：
   任务1：读取配置并解析
   任务2：基于配置生成代码
   （任务2依赖任务1结果，不应并行）

5.3 任务描述规范

每个子任务应包含：
- 任务名称
- 具体目标
- 输出要求
- 输入依赖（如果有）

---

六、后台任务

6.1 后台运行 Agent

对于耗时的探索任务，可以后台运行：

# 后台运行代码分析
> 在后台分析整个项目的依赖关系，完成后告诉我

# Claude 设置 run_in_background: true
# 完成后会自动通知

6.2 检查后台任务

# 查看后台任务状态
> /tasks

# 输出：
# Task ID: abc123
# Status: running
# Description: 分析项目依赖

---

七、最佳实践

7.1 选择正确的执行方式

场景	推荐方式	原因
创建 2-3 个简单文件	自动并行	无需额外开销
探索代码库结构	Explore Agent	需要多轮搜索
设计实现方案	Plan Agent	需要架构思考
代码质量分析	code-improvement-advisor	专用优化建议
大型重构	分批 + Agent	需要协调管理

7.2 效率优化建议

建议	说明
信任自动并行	简单任务无需手动指定
使用专用 Agent	复杂任务用专用类型更高效
合理分批	大任务分批处理，中间验证
后台运行	耗时探索任务后台执行

---

八、常见问题

Q1: 任务执行顺序不对

原因：任务之间可能有隐式依赖

解决：

# 明确说明依赖关系
> 先创建模型，然后基于模型创建服务，最后写测试

Q2: Agent 执行太慢

原因：复杂任务需要多轮探索

解决：

# 缩小范围
> 只在 src/api/ 目录下搜索认证相关代码

Q3: 结果不符合预期

解决：

1. 提供更明确的任务描述
2. 指定具体的文件路径
3. 分步骤执行并验证

---

九、下一步学习

完成本指南后，建议学习：

1. 05-Hooks自动化.md - 自动化工作流
2. 09-实战：PythonWebAPI开发.md - Sub Agent 实战应用

---