TodoWriteTool：待办清单

它不是普通 checklist，而是会话内任务外显

TodoWriteTool 是 Claude Code 经典的轻量任务管理工具。
它的作用不是替代正式任务系统，而是让模型在当前会话里把工作拆成一串可见的 todo。

你可以把它理解成：

  • TodoWriteTool：轻量、会话内、快速追踪
  • TaskCreateTool 系列：结构化、正式任务系统

关键源码

tools/TodoWriteTool/TodoWriteTool.ts：

1
2
3
const inputSchema = z.strictObject({
  todos: TodoListSchema().describe('The updated todo list'),
})

而真正的状态写回是：

1
2
3
4
5
6
7
context.setAppState(prev => ({
  ...prev,
  todos: {
    ...prev.todos,
    [todoKey]: newTodos,
  },
}))

这说明它本质上是一个 AppState 写入工具 。

调用链

实现重点

它有两个很有意思的设计：

  1. 所有 todo 都完成时，会直接把列表清空
  2. 如果结束的是一个 3 项以上的复杂任务，而且没有验证步骤，会提醒生成 verification nudge

源码里这段很关键：

1
2
3
4
5
6
7
if (
  allDone &&
  todos.length >= 3 &&
  !todos.some(t => /verif/i.test(t.content))
) {
  verificationNudgeNeeded = true
}

这说明它并不只是“写清单”，还会在任务收尾时推动更严谨的验证。

一次典型使用路径

  1. 用户给一个中等复杂任务
  2. 模型先写 3-5 个 todo
  3. 每做完一项就更新状态
  4. 最后一项关闭时，如果没有验证，会被提醒补验证

它和相邻工具的关系

小结

TodoWriteTool 的价值是：

用最低成本把模型当前计划显式化，并把“做完就清单消失、复杂任务别忘验证”这种流程约束接进会话状态。