Working Memory via TodoWrite

在复杂的多步骤任务中，AI Agent会无法追踪以下内容：

• 哪些任务处于待处理、进行中或已完成状态
• 哪些任务因依赖关系而被阻塞
• 需要执行的验证步骤
• 上下文切换后的后续操作

这会导致工作冗余、任务遗漏以及用户困惑。

使用TodoWrite（或等价的状态外化工具）在整个会话过程中维护显性工作记忆。它能让Agent和用户都清晰掌握会话状态。

需要跟踪的内容：

1. 任务状态：待处理（pending）、进行中（in_progress）、已完成（completed）
2. 阻塞关系：明确任务间的阻塞依赖
3. 验证步骤：所需开展的测试或检查项
4. 下一步动作：后续需执行的操作

基于数据的使用模式：

| 项目 | TodoWrite使用次数 | 会话质量 | |---------|---------------|-----------------| | nibzard-web | 52 | 高（8条正面反馈，2条修正） | | awesome-agentic-patterns | 60 | 中（1条正面反馈，5条修正） | | marginshot | 36 | 未捕获到反馈 | | 2025-intro-swe | 0 | 工作简单，无需使用 |

核心洞察：

• TodoWrite的使用与更顺畅的会话体验相关联
• 它可为Agent和用户提供共享的工作记忆支撑
• 对复杂多步骤任务至关重要
• 对于简单直接的工作则必要性较低

stateDiagram-v2
    [*] --> 待处理：任务已识别
    待处理 --> 进行中：已启动
    进行中 --> 已完成：已结束
    进行中 --> 阻塞：等待依赖项
    阻塞 --> 进行中：依赖项已解决
    已完成 --> [*]

    note right of 待处理
        通过TodoWrite创建
        主题需清晰明确
    end note

    note right of 进行中
        更新状态以
        跟踪进展
    end note

    note right of 阻塞
        记录阻塞
        关系详情
    end note

适用场景：

• 处理复杂的多步骤任务
• 需要跟踪受阻任务与依赖关系
• 希望在多操作间维持会话状态
• 存在多个并行工作流

实现方法：

1. 主动创建任务：识别到工作内容时，创建TodoWrite条目
2. 实时更新状态：启动任务时标记为in_progress
3. 记录依赖关系：使用blocks/blockedBy关联关系
4. 完成后标记已完成：仅当任务真正完成时，再标记为已完成
5. 保持描述清晰：包含足够上下文（context），以便日后参考

示例工作流：

1. 用户：“添加OAuth登录功能并修复搜索bug”
2. Agent创建2个TodoWrite任务条目
3. Agent将OAuth任务标记为in_progress，开始工作
4. Agent意识到OAuth任务需要修改数据库schema
5. Agent将OAuth任务设为受阻状态，创建schema修改任务
6. Agent完成schema修改，解除OAuth任务的受阻状态
7. Agent完成OAuth任务，转向搜索bug修复工作
8. Agent完成搜索bug修复，标记所有任务为已完成

反模式规避：

• 避免跨上下文窗口切换时的上下文丢失
• 避免重复工作（同一任务执行两次）
• 避免任务遗漏（如用户询问“那X任务呢？”）
• 避免会话状态不明确

优点：

• 为Agent和用户提供明确的会话状态
• 依赖项跟踪可避免工作阻塞
• 进度可见性能增强用户信心
• 在Context窗口切换后仍可正常生效
• 减少用户提出的“那X的情况呢？”类问题

缺点：

• 处理简单任务时存在额外开销
• 需要遵循规范进行维护
• 过度使用会导致内容杂乱无章
• 针对快速一次性任务，可能显得繁琐刻板

不适用场景：

• 简单的单步骤任务
• 可在数秒内完成的任务
• 用户仅需快速获取答案的场景