Claude Code 任务列表更新指南：TaskUpdate 工具的完整状态管理与依赖编排手册

• 文档
• 提示工程
• 人工智能

导读

TaskUpdate是 Claude Code 任务列表体系中的核心更新工具，用于修改任务的状态、标题、描述、负责人、元数据以及任务间依赖关系。本文以仓库中的 TaskUpdate 工具描述文档 为骨架，结合同仓库的 TaskCreate、TaskGet、TaskList 等配套工具描述与系统提醒，系统讲解任务的完整生命周期管理、可更新字段语义、状态流转规则、依赖编排方法与实战调用示例，帮助你在复杂多步任务、Plan 模式与多人协作场景下正确维护任务列表。

一、TaskUpdate 在任务工具链中的定位

Claude Code 的任务列表体系由一组相互配合的内置工具组成，TaskUpdate 是其中的"写入端"，负责对已创建任务进行一切后续变更：

从源码结构看，这些工具描述文件均位于 system-prompts 目录，每个文件头部以 YAML frontmatter 声明name、description与ccVersion字段。例如 TaskUpdate 描述文档 的元数据为：

name: "Tool Description: TaskUpdate" description: "Description for the TaskUpdate tool, which updates Claude's task list" ccVersion: "2.1.173"

ccVersion字段表明该描述随 Claude Code 各版本持续演进，仓库中的 tools/updatePrompts.js 即负责按版本化流程生成与更新这些系统提示文件。

二、何时使用 TaskUpdate

根据原文档，"使用此工具更新任务列表中的某个任务"。具体触发场景分为三类：

1. 标记任务为已完成（resolved）

• 当你完成了任务描述中的工作时
• 当任务不再需要、或已被新任务取代时
• 重要：完成分配给你的任务后，务必将其标记为 resolved
• 解析完成后，调用 TaskList 查找你的下一个任务

这与 tool-description-tasklist.md 中的指引完全衔接："完成任务后，检查新解除阻塞的工作或认领下一个可用任务"。

2. 删除任务

• 当任务不再相关、或属于误创建时，将状态置为deleted可永久移除该任务

3. 更新任务细节

• 当需求变更或变得更加清晰时
• 当需要建立任务之间的依赖关系时

三、可更新字段详解

TaskUpdate 支持对任务的七个维度进行更新，字段语义如下：

其中subject与activeForm的两种形态要求与 tool-description-todowrite.md 中"任务描述必须有两种形式"的约定一致：

• subject（content）：祈使句，描述要做什么，例如"Run tests"
• activeForm：现在进行时，在执行期间展示，例如"Running tests"

四、状态工作流（Status Workflow）

任务状态按以下顺序单向推进：

pending → in_progress → completed

• pending：任务已创建但尚未开始
• in_progress：正在执行中（同一时间只应有一个任务处于该状态）
• completed：任务已成功完成
• deleted：用于永久移除任务，不属于常规推进路径

从 tool-description-todowrite.md 的任务管理规则可以印证状态纪律：

• 任意时刻恰好只有一个任务处于in_progress（不能多也不能少）
• 完成当前任务后再开始新任务
• 实时更新任务状态，完成一个标记一个，不要批量补记
• 不再相关的任务应从列表中移除

五、完成判定的硬性红线

原文档强调：只有当你完整完成了任务时，才可将任务标记为 completed。遇到以下情况严禁标记完成：

• 测试仍在失败
• 实现是部分完成的
• 遇到了未解决的错误
• 未能找到所需的文件或依赖

正确处理方式为：遇到错误、阻塞或无法完成时，保持任务为in_progress；受阻时新建一个任务描述需要解决的问题。这条规则在 tool-description-todowrite.md 中同样存在，属于跨工具共享的核心纪律。

六、Staleness 防过期原则

更新任务前，务必先用TaskGet读取该任务的最新状态。

这条规则用于防止"过期覆盖"：任务可能在多轮会话或多名协作者之间被修改，直接更新而不先读取，可能覆盖他人刚刚写入的状态、owner 或依赖信息。推荐的更新前序为：

1. TaskGet读取任务完整详情（subject、description、status、blocks、blockedBy）
2. 结合 tool-description-task-get.md 的提示，确认blockedBy列表为空后再开始工作
3. 确认无异议后再用 TaskUpdate 写入变更

七、实战调用示例

原文档给出了五类典型调用。以下 JSON 为TaskUpdate工具的输入参数示例：

1. 开始工作时标记为进行中

{"taskId": "1", "status": "in_progress"}

2. 完成工作后标记为已完成

{"taskId": "1", "status": "completed"}

3. 删除任务

{"taskId": "1", "status": "deleted"}

4. 认领任务（设置负责人）

{"taskId": "1", "owner": "my-name"}

5. 建立任务依赖

{"taskId": "2", "addBlockedBy": ["1"]}

八、依赖编排与 Teammate 协作工作流

addBlocks与addBlockedBy两个字段使任务列表具备了 DAG 式的依赖编排能力，这在多 Agent（teammate）协作场景中尤为重要。

TaskList 的 Teammate 工作流扩展 给出了完整的协作循环：

1. 完成当前任务后，调用 TaskList 寻找可认领的工作
2. 寻找状态为pending、无 owner、且blockedBy为空的任务
3. 存在多个可认领任务时，优先按 ID 顺序（最小 ID 优先）选择，因为较早的任务通常为后续任务铺垫上下文
4. 使用 TaskUpdate 认领任务（将owner设为你的名字），或等待 leader 分配
5. 若被阻塞，聚焦于解除阻塞的任务或通知团队负责人

从 tool-description-tasklist.md 可知，带blockedBy的任务在依赖未解决前不可被认领，因此正确的依赖编排顺序是先创建任务、再用 TaskUpdate 建立依赖：

• 创建任务使用TaskCreate，参考 tool-description-taskcreate.md 的提示——创建后使用 TaskUpdate 设置依赖（blocks/blockedBy），并先检查 TaskList 避免创建重复任务
• 依赖建立后，TaskGet 返回的blocks与blockedBy字段即可用于确认任务就绪状态

九、系统级提醒与任务列表卫生

仓库中的 system-reminder-task-tools-reminder.md 是任务工具的系统级提醒：当任务工具长时间未被使用时，Claude 会被提示——考虑用TaskCreate添加新任务、用TaskUpdate更新任务状态（开始时置in_progress，完成时置completed），同时考虑清理已过期的任务列表。这说明 TaskUpdate 不仅是状态写入器，还承担着任务列表卫生维护（清理 stale 任务、删除误创建任务）的职责。

结合 tool-description-taskcreate.md 的适用场景判断，TaskUpdate 的高频使用时机包括：

• 复杂多步任务（3 个及以上独立步骤）
• Plan 模式下的工作跟踪
• 收到新指令后立即将需求固化为任务，并在开工前标记in_progress
• 完成任务后标记completed并补充实现过程中发现的新后续任务

十、小结：TaskUpdate 的正确使用姿势

TaskUpdate 虽小，却是任务列表生命周期的"总开关"：状态推进、细节修正、负责人变更、依赖建立与列表清理全部经由它完成。正确遵循"先读后写""完成才标完""遇阻留 in_progress""依赖先行"四条纪律，即可在单 Agent 与多 Agent 协作场景中维持一份准确、有序、可追踪的任务列表，让用户对请求的整体进展一目了然。

• 文档
• 提示工程
• 人工智能