AI Spark 知识库

外观

任务管理工作流 ​

版本：Claude Code v2.1.16+前提条件：理解多会话工作流，具备基本 CLI 熟练度时间：15-30 分钟学习，适用于所有复杂项目

概述 ​

Claude Code 的任务管理功能在 v2.1.16 版本中通过引入 Tasks API 得到了显著改进，对原有的 TodoWrite 工具进行了补充。本工作流将教你何时使用各个系统，以及如何利用多会话任务协调来处理复杂项目。

适用此工作流的情况：

  • 跨越多个编码会话的项目
  • 多智能体协调场景
  • 具有依赖关系的复杂任务层次
  • 需要在上下文压缩或会话中断后恢复工作

不适用此工作流的情况：

  • 单会话、直接的实现
  • 快速修复或探索性编码
  • 可在 10 分钟内完成的任务

系统对比快速参考 ​

功能TodoWrite（旧版）Tasks API（v2.1.16+）
持久化仅会话记忆磁盘存储（~/.claude/tasks/）
多会话❌ 会话结束后丢失✅ 跨会话保存
依赖关系❌ 手动排序✅ 任务阻塞（A 阻塞 B）
协调单智能体✅ 多智能体广播
状态追踪pending/in_progress/completedpending/in_progress/completed
适用场景简单的单会话待办事项复杂的多会话项目

迁移标志（v2.1.19+）：

Bash
# 使用旧系统（TodoWrite）
CLAUDE_CODE_ENABLE_TASKS=false claude

# 使用新系统（Tasks API）—— v2.1.19 起默认启用
claude

工作流阶段 1：任务规划 ​

目标：将复杂工作分解为可追踪、可执行的单元

第 1 步：分析范围 ​

在创建任务之前，了解你要构建的内容：

Bash
# 发现模式
claude
> "分析此代码库以实现 JWT 认证：
  - 使用 Glob 查找现有的认证模式
  - 使用 Grep 搜索安全相关代码
  - 识别集成点"

第 2 步：设计任务层次 ​

将工作分解为带有依赖关系的逻辑阶段：

示例：认证系统

Plain
认证系统（父任务）
├── 1. 登录端点（无依赖）
├── 2. 令牌刷新（依赖 #1）
├── 3. 退出端点（依赖 #1）
└── 4. 集成测试（依赖 #1、#2、#3）

第 3 步：创建任务结构 ​

使用 TaskCreate 将计划具体化：

Bash
# 会话 1：规划阶段
export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2"
claude

# 在 Claude 会话中：
> "为 JWT 认证创建任务层次：

  父任务：'实现 JWT 认证系统'
  - 描述：添加带有刷新令牌和安全存储的 JWT 认证

  子任务：
  1. '创建登录端点'（无依赖）
  2. '实现令牌刷新逻辑'（依赖任务 1）
  3. '创建退出端点'（依赖任务 1）
  4. '编写集成测试'（依赖任务 1、2、3）

  使用 TaskCreate 并附带适当的元数据。"

Claude 的预期输出：

JSON
{
  "tasks": [
    {
      "id": "task-auth-parent",
      "title": "Implement JWT authentication system",
      "status": "pending",
      "children": ["task-login", "task-refresh", "task-logout", "task-tests"]
    },
    {
      "id": "task-login",
      "title": "Create login endpoint",
      "status": "pending",
      "dependencies": [],
      "metadata": {"priority": "high", "estimated_duration": "2h"}
    },
    {
      "id": "task-refresh",
      "title": "Implement token refresh logic",
      "status": "pending",
      "dependencies": ["task-login"],
      "metadata": {"priority": "high", "estimated_duration": "1h"}
    }
    // ... 其他任务
  ]
}

工作流阶段 2：任务执行 ​

目标：系统地执行任务并追踪进度

执行模式 ​

Plain
TaskList → TaskGet（下一个待处理）→ 执行 → TaskUpdate → 验证 → 重复

第 1 步：发现下一个任务 ​

Bash
# 会话 2：开始实现
export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2"
claude

> "TaskList 显示所有待处理任务"

输出：

Plain
'auth-system-v2' 的任务：
✅ task-login：创建登录端点 [已完成]
⏳ task-refresh：实现令牌刷新逻辑 [待处理，无阻塞]
⏳ task-logout：创建退出端点 [待处理，无阻塞]
⏳ task-tests：编写集成测试 [待处理，被 task-refresh、task-logout 阻塞]

第 2 步：获取任务详情 ​

Bash
> "TaskGet task-refresh 查看完整需求"

输出：

JSON
{
  "id": "task-refresh",
  "title": "Implement token refresh logic",
  "description": "Create endpoint POST /auth/refresh that validates refresh token and issues new access token",
  "status": "pending",
  "dependencies": ["task-login"],
  "metadata": {
    "priority": "high",
    "estimated_duration": "1h",
    "files": ["src/auth/refresh.ts", "src/middleware/auth.ts"]
  }
}

第 3 步：执行并更新 ​

Bash
> "将 task-refresh 标记为进行中，然后按需求实现令牌刷新端点"

# Claude 执行：TaskUpdate task-refresh status=in_progress
# Claude 实现该功能...
# 完成后：

> "将 task-refresh 标记为已完成"
# Claude 执行：TaskUpdate task-refresh status=completed

第 4 步：验证 ​

Bash
> "运行令牌刷新功能的测试"

# 测试通过：
# ✅ 任务保持已完成状态

# 测试失败：
> "TaskUpdate task-refresh status=in_progress，将错误详情添加到元数据并修复问题"

工作流阶段 3：会话管理 ​

目标：跨会话和上下文边界无缝恢复工作

持久化机制 ​

存储位置：~/.claude/tasks/<task-list-id>/

任务在以下情况后仍会保留：

  • 会话终止
  • 上下文压缩（/compact）
  • 系统重启
  • 多天的中断

⚠️ 字段可见性限制 ​

TaskList 仅返回：id、subject、status、owner、blockedBy

TaskList 输出中缺失：

  • description（需要逐个使用 TaskGet）
  • metadata（自定义字段如优先级、估时）
  • activeForm（进度显示文字）

工作流调整：

Bash
# 不要：假设可以扫描所有描述
TaskList  # 仅显示主题

# 应该：有选择地获取
TaskList                    # 获取概览（存在哪些任务、状态）
TaskGet(task-auth-login)    # 获取特定任务的完整详情
TaskGet(task-auth-tests)    # 获取下一个任务的详情

这一点何时重要：

  • 每个任务描述较长的复杂项目（>50 字/任务）
  • 需要共享上下文可见性的多智能体协调
  • 需要快速扫描所有任务备注以决定恢复点

成本意识：

  • TaskList = 1 次 API 调用
  • 获取 N 个任务的描述 = 1 + N 次调用
  • 对于 20 个任务，若需要所有描述，开销是 20 倍

缓解措施：

  • 在 subject 字段中放关键信息（TaskList 中可见）
  • 保持 description 简洁（最多 50-100 字）
  • 将详细计划存储在 markdown 文件中（docs/plan-*.md）

恢复模式 ​

Bash
# 数天后，在不同的终端会话中
export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2"
claude

> "TaskList 显示当前状态"

# 输出精确显示你上次停在哪里：
# ✅ task-login [已完成]
# ✅ task-refresh [已完成]
# ⏳ task-logout [待处理]
# ⏳ task-tests [待处理，被 task-logout 阻塞]

> "继续下一个未被阻塞的待处理任务"

多终端协调 ​

用例：运行多个 Claude 实例处理同一项目

Bash
# 终端 1：前端工作
export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2"
claude
> "处理 task-logout 端点"

# 终端 2：编写测试（同时进行）
export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2"
claude
> "TaskList - 检查已完成的内容，这样我可以编写测试"

# 两个终端都能看到实时状态更新

⚠️ 警告：使用仓库特定的任务列表 ID，避免跨项目污染：

Bash
# ❌ 差：跨多个仓库使用通用 ID
export CLAUDE_CODE_TASK_LIST_ID="my-project"

# ✅ 好：带上下文的仓库特定 ID
export CLAUDE_CODE_TASK_LIST_ID="mycompany-api-auth-refactor"

集成：TDD（测试驱动开发）+ 任务管理 ​

将测试驱动开发与任务追踪结合，实现系统性的测试覆盖。

模式：测试优先任务执行 ​

Bash
export CLAUDE_CODE_TASK_LIST_ID="tdd-feature-x"
claude

# 用测试优先方法创建任务
> "为功能 X 创建任务层次：

  对每个功能组件：
  1. 任务：'为[组件]编写失败测试'
  2. 任务：'实现[组件]使测试通过'（依赖 #1）
  3. 任务：'重构[组件]'（依赖 #2）

  每个任务使用 TDD（测试驱动开发）红绿重构循环。"

示例：带 TDD 的登录功能 ​

Bash
# 阶段 1：红（失败测试）
TaskCreate: {
  title: "Write failing tests for login endpoint",
  description: "Test cases: valid credentials, invalid password, user not found, rate limiting",
  status: "pending"
}

# 执行测试编写
> "实现 task-login-tests，确保所有测试初始时失败"

# 阶段 2：绿（最简实现）
TaskCreate: {
  title: "Implement login endpoint (minimal)",
  description: "Make tests pass with simplest possible implementation",
  dependencies: ["task-login-tests"],
  status: "pending"
}

# 阶段 3：重构
TaskCreate: {
  title: "Refactor login endpoint",
  description: "Optimize, remove duplication, improve readability",
  dependencies: ["task-login-impl"],
  status: "pending"
}

完整工作流参考：参见 「TDD with Claude」

集成：计划驱动 + 任务管理 ​

将战略计划转化为可执行的任务层次。

模式：计划到任务的转换 ​

Bash
# 第 1 步：进入计划模式
claude
> [按 Shift+Tab 进入计划模式]

# 第 2 步：创建架构计划
> "设计微服务迁移的架构：
  - 识别服务边界
  - 规划数据迁移策略
  - 设计 API 契约"

# 第 3 步：退出计划模式并创建任务
> "用 TaskCreate 将此计划转化为任务层次"

示例：微服务迁移 ​

计划输出：

Plain
阶段 1：分析（第 1 周）
- 映射单体依赖
- 识别有界上下文
- 设计服务边界

阶段 2：基础设施（第 2 周）
- 设置服务模板
- 配置 API 网关
- 建立监控

阶段 3：迁移（第 3-6 周）
- 提取用户服务
- 提取订单服务
- 迁移数据库 Schema

任务转换：

Bash
TaskCreate: {
  title: "Microservices migration",
  children: [
    {
      title: "Phase 1: Analysis",
      children: [
        {title: "Map monolith dependencies", priority: "critical"},
        {title: "Identify bounded contexts", dependencies: ["map-deps"]},
        {title: "Design service boundaries", dependencies: ["bounded-contexts"]}
      ]
    },
    {
      title: "Phase 2: Infrastructure",
      dependencies: ["phase-1"],
      children: [
        {title: "Set up service templates"},
        {title: "Configure API gateway", dependencies: ["templates"]},
        {title: "Establish monitoring"}
      ]
    }
    // ... 阶段 3
  ]
}

完整工作流参考：参见 「计划驱动开发」

TodoWrite 迁移指南 ​

何时迁移 ​

继续使用 TodoWrite 如果：

  • ✅ 所有工作在单次会话中完成
  • ✅ 无需多智能体协调
  • ✅ 简单线性任务列表（无依赖关系）
  • ✅ 使用 Claude Code < v2.1.16

迁移到 Tasks API 如果：

  • ✅ 工作跨越多个会话
  • ✅ 需要任务跨天/跨周持久化
  • ✅ 复杂的依赖图
  • ✅ 多终端协作
  • ✅ 希望在上下文压缩后恢复

迁移步骤 ​

第 1 步：识别 TodoWrite 用法 ​

Bash
# 在你的 CLAUDE.md 或工作流中查找现有的 TodoWrite 用法
grep -r "TodoWrite" .claude/

第 2 步：将 TodoWrite 列表转换为任务 ​

之前（TodoWrite）：

Markdown
- [ ] 实现用户认证
- [ ] 添加密码哈希
- [ ] 创建会话管理
- [ ] 编写测试

之后（Tasks API）：

Bash
export CLAUDE_CODE_TASK_LIST_ID="user-auth-2026"
claude

> "创建任务：
  1. '实现用户认证'（父任务）
     - 子任务：'添加密码哈希'
     - 子任务：'创建会话管理'（依赖哈希）
     - 子任务：'编写测试'（依赖认证、哈希、会话）"

第 3 步：更新 CLAUDE.md 指令 ​

之前：

Markdown
对于复杂任务：
- 使用 TodoWrite 创建任务列表
- 顺序执行任务

之后：

Markdown
对于复杂任务：
- 设置 CLAUDE_CODE_TASK_LIST_ID=<项目名称>
- 使用 TaskCreate 进行层次化规划
- 用 TaskUpdate 状态追踪执行
- 新会话中用 TaskList 恢复

第 4 步：测试迁移 ​

Bash
# 创建测试任务列表
export CLAUDE_CODE_TASK_LIST_ID="migration-test"
claude

> "创建 3 个带依赖关系的测试任务，标记一个为已完成，然后退出"

# 在新会话中重新启动
export CLAUDE_CODE_TASK_LIST_ID="migration-test"
claude

> "TaskList - 验证任务已正确持久化"

# 预期：看到所有 3 个任务及其正确状态

模式与反模式 ​

✅ 好的模式 ​

1. 层次化任务分解 ​

Bash
项目（父任务）
└── 功能 A（项目的子任务）
    ├── 组件 A1（功能 A 的子任务）
    │   ├── 实现（叶任务）
    │   └── 测试（叶任务，依赖实现）
    └── 组件 A2
        └── ...

为何有效：与自然项目结构一致，使依赖关系明确

2. 依赖优先排序 ​

Bash
# 创建任务时始终定义依赖关系
TaskCreate: {
  title: "Deploy to production",
  dependencies: ["run-tests", "code-review", "backup-database"],
  metadata: {blocking_reason: "Safety checks required"}
}

为何有效：防止过早执行，强制执行质量门控

3. 细粒度状态更新 ​

Bash
# 差：大任务完成时没有中间更新
TaskCreate: {title: "Build entire auth system"}
# ... 数小时后 ...
TaskUpdate: {id: "auth-system", status: "completed"}

# 好：随工作推进频繁更新状态
TaskUpdate: {id: "auth-system", status: "in_progress", progress: "25%"}
TaskUpdate: {id: "auth-system", status: "in_progress", progress: "50%"}
TaskUpdate: {id: "auth-system", status: "in_progress", progress: "75%"}
TaskUpdate: {id: "auth-system", status: "completed"}

为何有效：提供可见性，支持上下文感知的恢复

4. 富元数据任务 ​

Bash
TaskCreate: {
  title: "Optimize database queries",
  description: "Reduce query time for user dashboard from 2s to <200ms",
  metadata: {
    priority: "high",
    estimated_duration: "3h",
    related_files: ["src/db/queries.ts", "src/db/indexes.sql"],
    performance_baseline: "2000ms",
    performance_target: "200ms",
    related_issue: "https://github.com/org/repo/issues/123"
  }
}

为何有效：上下文丰富的恢复、更易委托、更好的文档

❌ 反模式 ​

1. 单体任务（>10 步） ​

Bash
# ❌ 差：任务过大，难以追踪进度
TaskCreate: {
  title: "Implement entire payment system",
  description: "Stripe integration, webhooks, refunds, disputes, reporting, admin UI, ..."
}

# ✅ 好：按阶段拆分
TaskCreate: {
  title: "Payment system - Phase 1: Core integration",
  children: [
    {title: "Stripe SDK setup"},
    {title: "Payment intent creation"},
    {title: "Webhook handling"}
  ]
}

2. 缺少依赖关系 ​

Bash
# ❌ 差：任务可能以错误顺序执行
TaskCreate: {title: "Deploy to production"} # 无依赖
TaskCreate: {title: "Write tests"} # 无依赖

# ✅ 好：明确排序
TaskCreate: {
  title: "Deploy to production",
  dependencies: ["write-tests", "run-tests", "code-review"]
}

3. 缺乏上下文的孤立任务 ​

Bash
# ❌ 差：未来的你不会记得这是什么意思
TaskCreate: {
  title: "Fix the bug",
  description: "That one from yesterday"
}

# ✅ 好：自包含的上下文
TaskCreate: {
  title: "Fix login timeout on Safari",
  description: "Safari 17.2+ 上的用户 5 分钟后遇到会话超时。预期：30 分钟超时。根因：cookie SameSite=Strict 不支持。",
  metadata: {
    browser: "Safari 17.2+",
    error_message: "Session expired",
    related_commit: "a1b2c3d",
    slack_thread: "https://slack.com/archives/C123/p456"
  }
}

4. 状态不匹配 ​

Bash
# ❌ 差：任务标记为已完成但测试失败
TaskUpdate: {id: "login-feature", status: "completed"}
# 测试稍后运行：3 个失败

# ✅ 好：完成前先验证
> "运行登录功能的测试"
# 测试通过：
TaskUpdate: {id: "login-feature", status: "completed", metadata: {test_results: "pass"}}
# 测试失败：
TaskUpdate: {id: "login-feature", status: "in_progress", metadata: {test_results: "3 failures", error_log: "..."}}

故障排查 ​

问：跨会话任务不持久 ​

症状：重启 Claude 后 TaskList 显示为空

解决方案：

Bash
# 确保启动前设置了 CLAUDE_CODE_TASK_LIST_ID
export CLAUDE_CODE_TASK_LIST_ID="your-project-name"
claude

# 验证存储目录存在
ls ~/.claude/tasks/your-project-name/

问：多项目共享任务列表 ​

症状：处理项目 B 时看到项目 A 的任务

原因：跨不同仓库使用了相同的任务列表 ID

解决方案：

Bash
# 使用带上下文的仓库特定 ID
cd ~/projects/api
export CLAUDE_CODE_TASK_LIST_ID="api-v2-migration"
claude

cd ~/projects/frontend
export CLAUDE_CODE_TASK_LIST_ID="frontend-redesign"
claude

问：仍在使用 TodoWrite 而非 Tasks API ​

症状：即使设置了任务列表 ID，任务仍不持久

原因：环境中设置了 CLAUDE_CODE_ENABLE_TASKS=false

解决方案：

Bash
# 检查环境
env | grep CLAUDE_CODE_ENABLE_TASKS

# 若存在则取消设置
unset CLAUDE_CODE_ENABLE_TASKS

# 或明确启用（v2.1.19+ 默认启用）
export CLAUDE_CODE_ENABLE_TASKS=true

问：任务依赖关系未被强制执行 ​

症状：Claude 在依赖任务完成前执行被阻塞的任务

原因：TaskCreate 中依赖关系定义不正确

解决方案：

Bash
# 确保依赖关系使用正确的任务 ID
TaskCreate: {
  title: "Task B",
  dependencies: ["task-a-id"], # ✅ 使用实际的任务 ID
  # 不是 dependencies: ["Task A"] # ❌ 任务标题无效
}

# 验证依赖关系：
TaskGet task-b-id
# 应显示："blockedBy": ["task-a-id"]

高级：自定义任务元数据 ​

用特定领域的元数据扩展任务以增强工作流。

元数据约定 ​

性能优化任务：

JSON
{
  "metadata": {
    "type": "performance",
    "baseline_metric": "2000ms",
    "target_metric": "200ms",
    "profiling_tool": "Chrome DevTools",
    "measurement_location": "dashboard load time"
  }
}

安全任务：

JSON
{
  "metadata": {
    "type": "security",
    "severity": "critical",
    "cve_id": "CVE-2024-1234",
    "affected_versions": "< 2.1.0",
    "mitigation": "Update package X to v3.0+"
  }
}

Bug 修复任务：

JSON
{
  "metadata": {
    "type": "bugfix",
    "issue_url": "https://github.com/org/repo/issues/456",
    "reported_by": "user@example.com",
    "reproduction_steps": "1. 登录 2. 导航到仪表板 3. 点击导出",
    "error_message": "TypeError: Cannot read property 'map' of undefined"
  }
}

按元数据查询 ​

Bash
# 按类型过滤任务（需要脚本，非内置功能）
TaskList | jq '.tasks[] | select(.metadata.type == "security")'

# 查找高优先级待处理任务
TaskList | jq '.tasks[] | select(.metadata.priority == "high" and .status == "pending")'

会话生命周期协议 ​

每个智能体会话遵循相同的十步顺序，从启动到提交。明确定义这些步骤，而不是让其隐含，正是使会话在中断后可靠恢复的关键。Anthropic 自己的工程团队直接观察到了这一点：在一个游戏编辑器实验中，裸跑 Claude 在中途失败，而相同的工作量在结构化会话框架的包裹下成功完成（来源：Anthropic 工程博客）。

步骤操作制品
启动读取项目指令AGENTS.md 或 CLAUDE.md
初始化运行环境引导init.sh / npm install && npm run check
读取加载上一次会话状态progress.md
选择选择一个功能，将状态设为活跃feature_list.json
执行只实现该功能源代码文件
验证运行三层验证（lint、测试、e2e）退出码
收尾记录完成情况和证据progress.md、feature_list.json
清理删除临时文件，验证仓库可干净重启仓库状态
提交在 Git 中标记会话边界Git 历史
交接编写或更新交接说明claudedocs/handoffs/

连续性制品：progress.md ​

progress.md 是让读取步骤在数秒而非数分钟内完成的文件。它存放在项目根目录，保持在 50 行以内，为下一个智能体会话而写，而不是为人工审查者写。这一区别很重要。交接文档（收尾和交接步骤）天然是详细的：它告诉人类发生了什么、为何做出这些决定、需要注意什么。progress.md 做的事情更窄。它记录活跃的功能 ID、最后的提交哈希、当前的阻碍因素，以及智能体应该采取的下一个单一行动。不要散文，不要叙事。

Markdown
# 会话进度

last_updated: 2026-05-04
active_feature: feat-002
last_commit: a3f92c1
session_count: 3

## 状态
- feat-001: 通过（已验证 2026-05-01）
- feat-002: 活跃（进行中）
- feat-003: 未开始

## 下一步行动
完成分块实现，然后运行：npm test -- --grep 'chunking'

## 阻碍
无

下一次会话在读取步骤时读取这个文件，找到 active_feature: feat-002，检查最后的提交哈希以在 Git 历史中定位自己，然后直接进行下一步行动。无需冷启动简报。

与交接三合一的组合方式 ​

本工作流前面文档记录的交接三合一模式（创建、恢复、更新）和 progress.md 为读取同一会话边界的不同受众服务。progress.md 给智能体一个机器可读的起点。交接文档给人工审查者一个关于变更内容和原因的叙述性说明。两者互不替代，并在同一步骤（收尾）中更新，使它们在不增加额外开销的情况下保持同步。

提交步骤作为会话边界 ​

提交步骤中的提交不仅仅是一个版本控制操作。它是对仓库处于可重启状态的断言。规则与交接三合一中相同：只有当功能完整且经过验证时才提交。一个处于损坏状态的半实现功能意味着下一次会话以损坏的环境开始，而初始化步骤的 npm run check 将立即失败，在任何新工作开始前就暴露出问题。这个失败是有信息价值的，但通过等待验证步骤干净通过后才提交来预防它更好。

关于跳过验证步骤时发生的失败模式，参见 「tdd-with-claude.md」 中的"验证缺口"。

相关工作流 ​

  • 「TDD with Claude」 - 带任务追踪的测试优先开发
  • 「计划驱动开发」 - 从战略规划到任务层次
  • 「迭代精化」 - 带任务的渐进式改进
  • 「探索工作流」 - 任务创建前的发现阶段

参考 ​

工具文档：参见 《Claude Code：从入门到大师》第 5.X 节

来源：

版本追踪：本工作流记录 Claude Code v2.1.16+（发布于 2026-01-22）。最新变更请在 claude-code-releases.yaml 中查看。

来源：飞书 · AI Spark 知识库 ｜ 原文（最新版）：https://lcnniolukk80.feishu.cn/wiki/APnewhwTximy7Akw37pcaXx8nog ｜ 归档：2026-06-04