一文搞懂 Agent TODO：AI 是如何把复杂任务一步步做完的？

一文搞懂 Agent TODO：AI 是如何把复杂任务一步步做完的？

一、问题从哪里来？

假设你让一个 Coding Agent 帮你开发 JWT 用户认证系统。

它需要分析项目、设计数据库、编写接口、实现 Token 验证，最后运行测试。整个任务可能涉及十几个步骤。

一开始，Agent 执行得很顺利。但进行到一半，你突然发现：它跳过了其中一个步骤，却直接告诉你任务已经完成。

为什么会这样？

因为 Agent 在执行长任务时，需要不断处理代码、工具返回结果、错误日志等信息。随着上下文不断增长，早期的任务要求可能被忽略，导致步骤遗漏或重复执行。

这和人类工作很相似。飞行员起飞前需要检查清单，程序员开发项目也会使用 TODO List。

Agent 同样需要一份任务清单，这就是 TODO 机制存在的意义。

二、什么是 TODO 机制？

TODO 机制本质上是一套帮助 Agent 拆解任务、记录进度、管理执行状态 的机制。

例如，开发 JWT 认证系统时，可以将任务拆解为：

• 分析项目结构和依赖
• 设计用户数据结构
• 实现登录和 Token 签发
• 实现 Token 验证
• 编写测试并验证功能

在实际系统中，每个任务通常具有三种状态：

状态	含义
pending	等待执行
in_progress	正在执行
completed	已经完成

Agent 每完成一个步骤，就更新对应的任务状态，再根据清单决定下一步应该做什么。

这样做主要有三个好处：

1. 防止遗漏： 提醒 Agent 哪些任务已经完成，哪些还没有执行。
2. 进度可视化： 用户可以清楚地看到任务执行到了哪里。
3. 支持任务编排： 方便管理复杂任务的执行顺序、依赖关系和协作过程。

需要注意，TODO 并不能保证 Agent 一定不会犯错，它只是让任务执行过程更加有序、可追踪。

三、TODO 机制是如何实现的？

以 Claude Code 为例，我们可以了解两种具有代表性的任务管理方案：TodoWrite 和 Task。

1. TodoWrite：简单的任务清单

TodoWrite 是 Claude Code 早期使用的任务管理工具。

可以把它理解为一张便利贴：Agent 把需要完成的事情列出来，每做完一项，就更新对应状态。

它具有几个特点：

• 面向单次会话： 主要用于当前会话内的任务追踪。
• 扁平化结构： 任务以列表形式组织，不支持显式的任务依赖关系。
• 全量更新： 更新状态时，需要提交完整的任务清单。

例如，修复一个 Bug：

1. 定位问题。
2. 修改代码。
3. 运行测试。
4. 检查修改结果。

这种任务没有复杂的依赖关系，也不需要多个 Agent 协作，使用简单的 Checklist 就足够了。

但如果任务需要跨越多个会话，或者涉及多个 Agent 并行工作，简单的任务清单就不太方便了。

2. Task：更完整的任务管理系统

为了解决这些问题，Claude Code 在后续版本中引入了 Task 系统。

相比 TodoWrite，Task 不再只是简单地记录待办事项，而是提供了一套结构化的任务管理能力。

它主要包含四个工具：

工具	作用
TaskCreate	创建任务
TaskGet	获取任务详情
TaskUpdate	更新任务状态、依赖等
TaskList	查看任务列表

Task 的主要优势体现在三个方面。

① 持久化存储

任务数据可以保存在本地磁盘中，而不只是依赖当前对话上下文。

因此，即使上下文被压缩，任务记录也可以保留。通过配置共享任务列表标识，还可以在不同会话之间继续使用同一份清单。

② 任务依赖管理

假设开发一个认证系统，需要执行以下任务：

• 任务 A：设计数据库结构。
• 任务 B：实现登录接口，依赖 A。
• 任务 C：实现 Token 验证，依赖 B。
• 任务 D：执行集成测试，依赖 B、C。

Task 可以记录这些依赖关系。

当任务 A 尚未完成时，任务 B 就处于阻塞状态。只有前置任务完成后，后续任务才能解除阻塞。

这样能够帮助 Agent 判断任务是否具备执行条件。

③ 多 Agent 协作

多个 Agent 可以通过共享任务列表协调工作。

例如：

• Agent A：负责后端接口。
• Agent B：负责前端页面。
• Agent C：负责集成测试。

不同 Agent 可以查看任务状态、认领任务并更新进度，从而减少重复工作。

不过，任务列表负责记录和协调状态，并不直接解决代码冲突、资源竞争等并发问题。

四、TodoWrite 和 Task 有什么区别？

我们用一张表来总结：

对比维度	TodoWrite	Task
核心定位	简单检查清单	结构化任务管理
任务组织	扁平列表	独立任务与依赖关系
状态更新	全量更新	单任务更新
持久化	主要面向当前会话	本地持久化
多会话协作	不支持共享任务列表	支持
适用场景	简单、短期任务	复杂、长期任务

可以这样理解：

TodoWrite 像便利贴，Task 更像轻量级项目管理工具。

两者都能帮助 Agent 追踪任务，但 Task 在此基础上增加了持久化、依赖管理和多会话协作能力。

五、什么时候使用 TodoWrite，什么时候使用 Task？

了解两种机制的区别后，一个实际问题是：开发 Agent 时，应该选择哪一种？

主要考虑三个因素：任务复杂度、是否需要持久化、是否涉及多 Agent 协作。

1. TodoWrite：适合简单、短期任务

如果任务可以在一次会话中完成，没有复杂的依赖关系，也不需要多个 Agent 协作，那么简单的 Checklist 通常就足够了。

例如：

• 修复一个 Bug，按照定位、修改、测试的顺序执行。
• 批量处理文件，确保每个文件都被处理。
• 执行一个包含多个步骤的自动化脚本。

这类任务的主要需求是防止步骤遗漏，而不是复杂的任务调度。

因此，TodoWrite 更适合单 Agent、短流程的任务追踪。

2. Task：适合复杂、长期任务

如果任务具备以下特征，就更适合使用 Task：

• 跨会话执行： 今天完成一部分，明天继续。
• 存在任务依赖： 必须完成 A，才能执行 B。
• 多个 Agent 协作： 不同 Agent 需要共享任务状态。
• 任务数量较多： 需要独立更新和管理任务。

例如，开发一个完整的用户认证系统，需要完成数据库设计、后端接口、前端页面和集成测试。

这些任务之间存在依赖，还可能由多个 Agent 并行执行。

此时，Task 的持久化、依赖管理和共享能力就能发挥作用。

3. 能否组合使用？

从架构设计角度来看，可以采用一种两级任务管理的思路：

• 项目级： 使用 Task 管理主要任务及其依赖关系。
• 执行级： 在具体任务内部，使用简单的 Checklist 追踪操作步骤。

例如，Task 中有一个任务叫"实现登录接口"。

执行这个任务时，Agent 可以进一步拆解为：

1. 创建接口。
2. 实现密码验证。
3. 生成 JWT。
4. 编写单元测试。

这样既能管理项目整体进度，也能防止具体执行过程遗漏步骤。

需要说明的是，这是一种通用的 Agent 架构设计思路，并不意味着 Claude Code 当前版本一定可以同时调用 TodoWrite 和 Task 两套工具。

总结：简单任务使用 Checklist，复杂任务使用结构化 Task。是否需要跨会话、依赖管理和多 Agent 协作，是最重要的判断依据。

六、TODO 与上下文工程有什么关系？

如果你已经学习过 Context Engineering（上下文工程），会发现 TODO 与它有着密切的联系。

上下文工程的核心目标是：让模型在每次推理时，都能获得真正需要的信息。

而 TODO 恰好可以提供一种简洁、结构化的任务状态。

假设一个 Agent 已经执行了 30 个步骤。

没有 TODO 时，模型可能需要从冗长的对话历史中寻找任务进度。

有了 TODO 后，Agent 只需要查看任务清单，就可以快速了解：

• 当前目标是什么？
• 已经完成哪些任务？
• 下一步应该做什么？

如果清单还被持久化到外部存储中，就可以在上下文压缩或会话恢复时重新加载。

因此，TODO 可以理解为 Agent 的一种外部任务状态管理机制，它与 Context Engineering、Agent Memory 都存在联系，但不等同于完整的记忆系统。

七、总结

TODO 机制看似简单，却是 Agent 执行复杂任务时非常实用的基础设施。

它解决的主要不是模型的推理能力问题，而是任务执行过程中的状态管理与流程控制问题。

本文介绍了两种典型实现：

• TodoWrite： 适合简单任务，通过 Checklist 帮助 Agent 追踪执行步骤。
• Task： 适合复杂任务，在清单的基础上支持持久化、依赖管理和多 Agent 协作。

在实际工程中，我们应该根据任务复杂度选择合适的管理方式，而不是为每个简单任务引入复杂的编排系统。

一个可靠的 Agent，不仅要知道如何完成任务，还要清楚自己已经做了什么、正在做什么，以及接下来应该做什么。

版本说明： TodoWrite 和 Task 是 Claude Code 不同阶段的任务管理方案。目前 Task 系列工具优先于 TodoWrite，但较新模型不一定默认启用专用任务工具。实际使用时应以对应版本和配置为准。