Claude Code 使用指南

主题

Tasks 任务系统 ​

Tasks System: Cross-Session Task Management

Tasks 系统是 Claude Code 中用于管理跨会话任务的高级编排工具。它基于 DAG（有向无环图）模型来协调任务之间的依赖关系，确保任务按照正确的顺序执行，同时最大化并行度。

核心概念 ​

Core Concepts

什么是 Tasks 系统？ ​

What Is the Tasks System?

Tasks 系统是一个任务编排框架，将复杂的工作流拆解为多个可管理的任务单元，并通过依赖关系图来协调执行顺序。

任务编排概念模型：

         ┌──────────┐
         │ Task A   │
         │ (代码分析) │
         └────┬─────┘
              │
      ┌───────┴───────┐
      ▼               ▼
┌──────────┐    ┌──────────┐
│ Task B   │    │ Task C   │
│ (前端修复) │    │ (后端修复) │
└────┬─────┘    └────┬─────┘
      │               │
      └───────┬───────┘
              ▼
         ┌──────────┐
         │ Task D   │
         │ (集成测试) │
         └──────────┘

DAG 依赖模型 ​

DAG (Directed Acyclic Graph) Dependency Model

Tasks 系统使用有向无环图来表达任务之间的依赖关系：

DAG 特性在 Tasks 系统中的含义
有向任务之间有明确的前后关系
无环不允许循环依赖
图支持复杂的多对多依赖

依赖关系示例：

Task A ──→ Task B ──→ Task D
  │                     ▲
  └──→ Task C ──────────┘

含义：
- Task B 和 Task C 都依赖 Task A
- Task D 依赖 Task B 和 Task C
- Task B 和 Task C 可以并行执行
- Task D 必须等 B 和 C 都完成

与 SubAgent 的区别 ​

Differences from SubAgent

Tasks 系统和 SubAgent 都是 Claude Code 的多任务处理机制，但它们面向不同的使用场景。

核心区别 ​

Key Differences

维度SubAgentTasks 系统
会话范围单一会话内跨会话
生命周期随主 Agent 结束可持久化
依赖管理手动协调DAG 自动协调
状态追踪运行中/完成pending/in_progress/completed/failed
复杂度简单的并行任务复杂的工作流编排
恢复能力无支持断点续执

选择指南 ​

When to Use Which

简单并行搜索？           → SubAgent
需要依赖协调的工作流？   → Tasks 系统
任务时间 < 5 分钟？      → SubAgent
任务时间 > 5 分钟？      → Tasks 系统
需要跨会话持久化？       → Tasks 系统
一次性快速分析？         → SubAgent

任务生命周期 ​

Task Lifecycle

每个任务在其生命周期内会经历多个状态转换。

状态流转图 ​

State Transition Diagram

  ┌─────────┐
  │ pending  │  任务已创建，等待依赖完成
  └────┬─────┘
       │ 所有依赖完成
       ▼
  ┌───────────┐
  │in_progress│  任务正在执行
  └─────┬─────┘
        │
   ┌────┴────┐
   ▼         ▼
┌──────┐  ┌──────┐
│comple│  │failed│
│ ted  │  │      │
└──────┘  └──┬───┘
              │ 重试
              ▼
         ┌─────────┐
         │ pending  │  重新排队
         └─────────┘

状态说明 ​

State Descriptions

状态英文说明可转换到
等待中pending任务已创建，等待前置任务完成in_progress
进行中in_progress任务正在被执行completed, failed
已完成completed任务成功完成终态
已失败failed任务执行失败pending（重试）

状态查询示例 ​

Querying Task Status

json
{
  "tool": "TaskGet",
  "parameters": {
    "task_id": "task-abc-123"
  }
}

// 返回结果
{
  "task_id": "task-abc-123",
  "name": "运行单元测试",
  "status": "in_progress",
  "progress": "75%",
  "started_at": "2025-01-15T10:00:00Z",
  "dependencies": ["task-abc-120", "task-abc-121"],
  "output": null
}

相关命令和工具 ​

Related Commands and Tools

/tasks 交互命令 ​

The /tasks Interactive Command

在 Claude Code 交互界面中，使用 /tasks 命令管理任务。

> /tasks

任务列表：
┌─────────────┬────────────────────┬─────────────┬──────────┐
│ ID          │ 名称               │ 状态        │ 依赖     │
├─────────────┼────────────────────┼─────────────┼──────────┤
│ task-001    │ 代码分析           │ ✓ completed │ 无       │
│ task-002    │ 前端组件重构       │ ◉ in_progress│ task-001 │
│ task-003    │ API 端点更新       │ ◉ in_progress│ task-001 │
│ task-004    │ 集成测试           │ ○ pending   │ 002, 003 │
│ task-005    │ 文档更新           │ ○ pending   │ task-004 │
└─────────────┴────────────────────┴─────────────┴──────────┘

命令：
  /tasks list          查看所有任务
  /tasks show <id>     查看任务详情
  /tasks cancel <id>   取消任务
  /tasks retry <id>    重试失败的任务

TaskCreate 创建任务 ​

TaskCreate: Creating Tasks

创建新任务并可选地指定依赖关系。

json
{
  "tool": "TaskCreate",
  "parameters": {
    "name": "重构用户认证模块",
    "description": "将 session-based 认证迁移到 JWT",
    "prompt": "在 src/auth/ 目录下，将现有的 session 认证替换为 JWT 认证。需要修改 login、logout、middleware 三个文件。",
    "dependencies": [],
    "run_in_background": true
  }
}

带依赖的任务创建：

json
// 第一步：创建分析任务
{
  "tool": "TaskCreate",
  "parameters": {
    "name": "分析现有认证架构",
    "prompt": "分析 src/auth/ 目录的代码结构，列出所有认证相关的函数和中间件",
    "dependencies": []
  }
}
// 返回：task_id = "task-100"

// 第二步：创建依赖于分析结果的实现任务
{
  "tool": "TaskCreate",
  "parameters": {
    "name": "实现 JWT 认证",
    "prompt": "基于分析结果，实现 JWT 认证替换",
    "dependencies": ["task-100"]
  }
}
// 返回：task_id = "task-101"

TaskUpdate 更新任务 ​

TaskUpdate: Updating Tasks

更新任务的状态或其他属性。

json
{
  "tool": "TaskUpdate",
  "parameters": {
    "task_id": "task-101",
    "status": "completed",
    "output": "JWT 认证已成功实现。修改了 3 个文件，新增 2 个文件。"
  }
}

TaskGet 获取任务信息 ​

TaskGet: Retrieving Task Information

获取单个任务的详细信息。

json
{
  "tool": "TaskGet",
  "parameters": {
    "task_id": "task-101"
  }
}

// 返回
{
  "task_id": "task-101",
  "name": "实现 JWT 认证",
  "status": "in_progress",
  "description": "基于分析结果，实现 JWT 认证替换",
  "dependencies": ["task-100"],
  "created_at": "2025-01-15T09:00:00Z",
  "started_at": "2025-01-15T09:05:00Z",
  "output": null
}

TaskList 列出任务 ​

TaskList: Listing All Tasks

列出所有任务或按条件筛选。

json
{
  "tool": "TaskList",
  "parameters": {
    "status": "in_progress"
  }
}

// 返回
{
  "tasks": [
    {
      "task_id": "task-101",
      "name": "实现 JWT 认证",
      "status": "in_progress"
    },
    {
      "task_id": "task-103",
      "name": "更新 API 文档",
      "status": "in_progress"
    }
  ],
  "total": 2
}

TaskStop 停止任务 ​

TaskStop: Stopping a Running Task

停止正在执行的任务。

json
{
  "tool": "TaskStop",
  "parameters": {
    "task_id": "task-101",
    "reason": "需求变更，暂停实现"
  }
}

TaskOutput 获取任务输出 ​

TaskOutput: Getting Task Results

获取已完成或正在运行的任务的输出。

json
{
  "tool": "TaskOutput",
  "parameters": {
    "task_id": "task-100"
  }
}

// 返回
{
  "task_id": "task-100",
  "status": "completed",
  "output": "分析完成。发现以下认证组件：\n1. loginHandler (login.ts:15)\n2. logoutHandler (logout.ts:8)\n3. authMiddleware (middleware.ts:22)\n4. sessionStore (session.ts:5)\n\n当前使用 express-session 进行会话管理。"
}

工具速查表 ​

Tool Quick Reference

工具用途关键参数
TaskCreate创建新任务name, prompt, dependencies
TaskUpdate更新任务状态task_id, status, output
TaskGet获取任务详情task_id
TaskList列出任务status (可选筛选)
TaskStop停止任务task_id, reason
TaskOutput获取任务输出task_id

任务依赖关系 ​

Task Dependencies

依赖类型 ​

Dependency Types

Tasks 系统支持灵活的依赖关系定义。

线性依赖：

Task A → Task B → Task C

代码：
TaskCreate(name="A", dependencies=[])        → task-1
TaskCreate(name="B", dependencies=["task-1"]) → task-2
TaskCreate(name="C", dependencies=["task-2"]) → task-3

扇出依赖（一对多）：

        ┌→ Task B
Task A ─┤
        └→ Task C

代码：
TaskCreate(name="A", dependencies=[])        → task-1
TaskCreate(name="B", dependencies=["task-1"]) → task-2
TaskCreate(name="C", dependencies=["task-1"]) → task-3
// B 和 C 在 A 完成后同时开始

扇入依赖（多对一）：

Task A ─┐
        ├→ Task C
Task B ─┘

代码：
TaskCreate(name="A", dependencies=[])                → task-1
TaskCreate(name="B", dependencies=[])                → task-2
TaskCreate(name="C", dependencies=["task-1","task-2"])→ task-3
// C 必须等 A 和 B 都完成

菱形依赖：

         Task A
        ╱      ╲
    Task B    Task C
        ╲      ╱
         Task D

代码：
TaskCreate(name="A", dependencies=[])                → task-1
TaskCreate(name="B", dependencies=["task-1"])        → task-2
TaskCreate(name="C", dependencies=["task-1"])        → task-3
TaskCreate(name="D", dependencies=["task-2","task-3"])→ task-4

循环依赖检测 ​

Circular Dependency Detection

Tasks 系统会自动检测并拒绝循环依赖。

json
// 以下操作会失败：
TaskCreate(name="A", dependencies=["task-3"]) → task-1
TaskCreate(name="B", dependencies=["task-1"]) → task-2
TaskCreate(name="C", dependencies=["task-2"]) → task-3

// 错误：检测到循环依赖 task-1 → task-2 → task-3 → task-1

后台任务执行 ​

Background Task Execution

后台执行机制 ​

Background Execution Mechanism

设置 run_in_background: true 的任务会在后台异步执行，不阻塞当前会话。

json
{
  "tool": "TaskCreate",
  "parameters": {
    "name": "运行完整测试套件",
    "prompt": "执行 npm test -- --coverage 并生成覆盖率报告",
    "run_in_background": true
  }
}
// 立即返回 task_id，不等待执行完成

后台任务监控 ​

Monitoring Background Tasks

轮询方式：
1. TaskGet(task_id) 检查状态
2. 状态为 completed/failed 时获取结果

事件方式：
1. Tasks 系统在任务完成时发送通知
2. 主 Agent 自动收到状态更新

后台执行流程示例 ​

Background Execution Workflow

时间线：

T0: 创建后台任务 A（测试）
    创建后台任务 B（lint 检查）
    主 Agent 继续与用户对话

T1: 任务 B 完成（lint 通过）
    主 Agent 可选择性地通知用户

T2: 任务 A 完成（测试失败）
    主 Agent 报告失败详情
    用户决定下一步操作

使用场景 ​

Use Cases

场景一：长时间运行的构建任务 ​

Scenario 1: Long-Running Build Tasks

json
// 创建构建流水线
{
  "tasks": [
    {
      "name": "安装依赖",
      "prompt": "执行 npm ci 安装项目依赖",
      "dependencies": []
    },
    {
      "name": "类型检查",
      "prompt": "执行 tsc --noEmit 进行类型检查",
      "dependencies": ["安装依赖"]
    },
    {
      "name": "单元测试",
      "prompt": "执行 npm run test:unit",
      "dependencies": ["安装依赖"]
    },
    {
      "name": "构建产物",
      "prompt": "执行 npm run build",
      "dependencies": ["类型检查", "单元测试"]
    },
    {
      "name": "E2E 测试",
      "prompt": "启动开发服务器并运行 E2E 测试",
      "dependencies": ["构建产物"]
    }
  ]
}

执行时间线：

安装依赖 ████████░░░░░░░░░░░░░░░░░░░░░░ (30s)
类型检查          ██████░░░░░░░░░░░░░░░░ (20s)
单元测试          ████████████░░░░░░░░░░ (40s)
构建产物                        ████████ (25s)
E2E 测试                                ████████████ (45s)

总耗时：约 140s（串行需要 160s，节省 20s）

场景二：多步骤数据处理流水线 ​

Scenario 2: Multi-Step Data Processing Pipeline

json
// 数据迁移流水线
[
  {
    "name": "备份现有数据",
    "prompt": "创建 database/backup/ 目录并导出当前数据库的所有表",
    "dependencies": []
  },
  {
    "name": "生成迁移脚本",
    "prompt": "分析新旧 schema 差异，生成 SQL 迁移脚本",
    "dependencies": ["备份现有数据"]
  },
  {
    "name": "验证迁移脚本",
    "prompt": "在测试环境中运行迁移脚本，检查是否有错误",
    "dependencies": ["生成迁移脚本"]
  },
  {
    "name": "执行数据转换",
    "prompt": "运行数据转换脚本，将旧格式数据转为新格式",
    "dependencies": ["验证迁移脚本"]
  },
  {
    "name": "数据完整性校验",
    "prompt": "对比迁移前后的数据记录数和关键字段，确保无数据丢失",
    "dependencies": ["执行数据转换"]
  }
]

场景三：并行测试执行 ​

Scenario 3: Parallel Test Execution

json
// 并行运行不同类型的测试
[
  {
    "name": "前端单元测试",
    "prompt": "运行 cd frontend && npm test -- --coverage",
    "dependencies": [],
    "run_in_background": true
  },
  {
    "name": "后端单元测试",
    "prompt": "运行 cd backend && npm test -- --coverage",
    "dependencies": [],
    "run_in_background": true
  },
  {
    "name": "API 集成测试",
    "prompt": "运行 cd backend && npm run test:integration",
    "dependencies": [],
    "run_in_background": true
  },
  {
    "name": "合并测试报告",
    "prompt": "合并所有测试覆盖率报告并生成总体统计",
    "dependencies": ["前端单元测试", "后端单元测试", "API 集成测试"]
  }
]

并行执行效果：

串行执行：   ████████████████████████████████████ 180s
并行执行：   ████████████████░░░░░████ 100s
                                (节省约 44%)

实际示例：编排复杂项目 ​

Real-World Example: Orchestrating a Complex Project

场景：全栈功能开发 ​

Scenario: Full-Stack Feature Development

需求：为电商平台添加"商品评论"功能，涵盖数据库、后端 API、前端界面和测试。

任务编排图 ​

Task Orchestration Graph

                    ┌──────────────────┐
                    │ Task 1: 需求分析  │
                    │ 分析需求并生成    │
                    │ 技术规格文档      │
                    └────────┬─────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
    ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
    │ Task 2:      │ │ Task 3:      │ │ Task 4:      │
    │ 数据库设计    │ │ API 设计     │ │ UI 设计      │
    │ 创建 Schema  │ │ 定义端点规格  │ │ 组件结构规划  │
    └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
           │                │                │
           ▼                ▼                │
    ┌──────────────┐ ┌──────────────┐       │
    │ Task 5:      │ │ Task 6:      │       │
    │ 数据库迁移    │ │ API 实现     │       │
    │ 执行迁移脚本  │ │ 编写路由和   │       │
    └──────┬───────┘ │ 控制器       │       │
           │         └──────┬───────┘       │
           │                │               ▼
           │                │        ┌──────────────┐
           │                │        │ Task 7:      │
           │                │        │ 前端实现      │
           │                │        │ React 组件   │
           │                │        └──────┬───────┘
           │                │               │
           └────────────────┼───────────────┘
                            ▼
                    ┌──────────────┐
                    │ Task 8:      │
                    │ 集成测试      │
                    │ E2E 验证     │
                    └──────────────┘

任务创建代码 ​

Task Creation Code

json
// Task 1: 需求分析
TaskCreate({
  "name": "需求分析",
  "prompt": "阅读 docs/requirements/reviews-feature.md，分析商品评论功能的需求，生成技术规格文档保存到 docs/specs/reviews-spec.md",
  "dependencies": []
})
// → task-201

// Task 2: 数据库设计
TaskCreate({
  "name": "数据库 Schema 设计",
  "prompt": "根据 docs/specs/reviews-spec.md，设计 reviews 表和 review_replies 表的 Schema，创建迁移文件",
  "dependencies": ["task-201"]
})
// → task-202

// Task 3: API 设计
TaskCreate({
  "name": "API 端点设计",
  "prompt": "根据 docs/specs/reviews-spec.md，设计 RESTful API 端点，创建 OpenAPI 规格文件",
  "dependencies": ["task-201"]
})
// → task-203

// Task 4: UI 设计
TaskCreate({
  "name": "UI 组件规划",
  "prompt": "根据 docs/specs/reviews-spec.md，规划 React 组件结构，创建组件树文档",
  "dependencies": ["task-201"]
})
// → task-204

// Task 5: 数据库迁移
TaskCreate({
  "name": "执行数据库迁移",
  "prompt": "运行数据库迁移脚本，创建 reviews 相关的表",
  "dependencies": ["task-202"]
})
// → task-205

// Task 6: API 实现
TaskCreate({
  "name": "API 实现",
  "prompt": "根据 OpenAPI 规格实现评论的 CRUD API 端点",
  "dependencies": ["task-203", "task-205"]
})
// → task-206

// Task 7: 前端实现
TaskCreate({
  "name": "前端组件实现",
  "prompt": "实现评论列表、评论表单、评论卡片等 React 组件",
  "dependencies": ["task-204", "task-206"]
})
// → task-207

// Task 8: 集成测试
TaskCreate({
  "name": "集成测试",
  "prompt": "编写并运行 E2E 测试，验证评论功能的完整流程",
  "dependencies": ["task-207"]
})
// → task-208

执行过程追踪 ​

Execution Progress Tracking

> /tasks

项目：商品评论功能开发
进度：5/8 任务完成

┌──────────┬─────────────────┬──────────────┬────────────┐
│ ID       │ 名称            │ 状态         │ 耗时       │
├──────────┼─────────────────┼──────────────┼────────────┤
│ task-201 │ 需求分析        │ ✓ completed  │ 2m 15s     │
│ task-202 │ 数据库设计      │ ✓ completed  │ 1m 45s     │
│ task-203 │ API 设计        │ ✓ completed  │ 1m 30s     │
│ task-204 │ UI 组件规划     │ ✓ completed  │ 1m 20s     │
│ task-205 │ 数据库迁移      │ ✓ completed  │ 0m 30s     │
│ task-206 │ API 实现        │ ◉ in_progress│ 3m 10s...  │
│ task-207 │ 前端组件实现    │ ○ pending    │ -          │
│ task-208 │ 集成测试        │ ○ pending    │ -          │
└──────────┴─────────────────┴──────────────┴────────────┘

预计剩余时间：约 8 分钟

错误恢复 ​

Error Recovery

当任务失败时，Tasks 系统提供了恢复机制。

场景：Task 6 (API 实现) 失败

> TaskGet({ task_id: "task-206" })

{
  "status": "failed",
  "error": "TypeScript 编译错误：找不到模块 '@/models/Review'",
  "failed_at": "2025-01-15T10:15:00Z"
}

恢复步骤：
1. 分析错误原因（模型文件缺失）
2. 修复问题（创建模型文件或更新导入路径）
3. 重试任务：
   TaskUpdate({ task_id: "task-206", status: "pending" })

下游任务 (task-207, task-208) 保持 pending 状态，
不会因为上游失败而被标记为失败。
等待 task-206 成功完成后自动恢复执行。

高级用法 ​

Advanced Usage

动态任务创建 ​

Dynamic Task Creation

可以在任务执行过程中根据中间结果动态创建新任务。

Task A: 扫描代码库找出所有需要迁移的文件
  → 输出：发现 15 个文件需要迁移

主 Agent 根据 Task A 的结果动态创建：
  Task B1: 迁移 batch 1 (文件 1-5)
  Task B2: 迁移 batch 2 (文件 6-10)
  Task B3: 迁移 batch 3 (文件 11-15)
  Task C: 验证所有迁移 (依赖 B1, B2, B3)

条件执行 ​

Conditional Execution

主 Agent 可以根据任务结果决定后续任务的创建和执行。

Task A: 运行测试
  └→ 如果全部通过 → Task B: 部署到 staging
  └→ 如果有失败   → Task C: 生成失败报告
                   → Task D: 自动修复尝试

任务优先级 ​

Task Priority

虽然 Tasks 系统主要通过依赖关系决定执行顺序，但在多个任务同时就绪时，可以通过提示词暗示优先级。

json
TaskCreate({
  "name": "关键路径：核心 API",
  "prompt": "[高优先级] 这是关键路径任务，请优先执行...",
  "dependencies": ["task-201"]
})

总结 ​

Summary

Tasks 系统是 Claude Code 中最强大的任务编排工具，适合管理复杂的、有依赖关系的工作流。核心要点：

  • 基于 DAG 模型管理任务依赖，自动优化执行顺序
  • 支持跨会话的任务持久化和状态追踪
  • 通过 TaskCreate、TaskGet、TaskList、TaskUpdate、TaskStop、TaskOutput 六大工具进行全生命周期管理
  • 任务状态清晰：pending → in_progress → completed / failed
  • 支持后台执行、动态创建和条件执行等高级特性
  • 适合长时间运行的构建、测试、数据处理和多模块开发场景
  • 失败任务可重试，下游任务自动等待恢复