TodoWrite:AI 内部的待办清单

你给 ChatGPT 一个大任务(「实现一个完整的搜索功能」),它通常给你一段长长的回复——一气呵成,中间出错你也不知道。

你给 Claude Code 同样的任务,它会先停一下,然后:

📋 TodoWrite —— 已规划 5 个任务:
[ ] 1. 看现有搜索相关代码
[ ] 2. 设计后端 API
[ ] 3. 实现前端组件
[ ] 4. 写测试
[ ] 5. 跑一遍验证

然后它一项一项做,每完成一项就更新状态。

这就是 TodoWrite——AI 内部的待办清单。看似简单,是 Claude Code 干 30 分钟连续任务的核心机制之一。

1. 三种状态

每个 todo 有三态:

• pending(待开始)
• in_progress(正在做)— 同一时刻只允许 1 个
• completed(完成)

每次 Claude 调用 TodoWrite 工具,实际上是整体替换这个 list。它常做的更新:

• 任务 1 做完 → 改 [1] completed,顺手 [2] in_progress
• 中途发现需要插一步 → 在中间加一项 pending
• 跑挂了 → 把 in_progress 改回 pending 或 cancelled(更精细的有这个状态)

2. 为什么这是「连续任务」的关键

Claude 是 stateless 的——它每一轮对话都把整段历史重发。但每段历史那么长,它会忘事(尤其是细节)。

todo list 解决这个:

没有 todo	有 todo
第 8 轮可能忘了第 1 轮要做什么	当前 todo 状态显式写在上下文里
中途出错难以恢复	看 todo 哪一项失败,从那里接
你不知道它干到哪	你看着 todo 一项项打勾

类比:你接到一个 5 步的活,不写下来记脑子里,做到第 3 步会忘第 5 步是啥。写下来,做的时候打勾,中断了也能接着干。

3. 什么时候 Claude 会用 TodoWrite

它自己判断。常见触发:

• 用户给的任务有多个明确步骤(「实现 X、加测试、跑 build」)
• 任务预估超过 10 个工具调用
• 可能跨多个文件 / 多个领域(改前端 + 改后端 + 改文档)

简单任务它不会用 todo——「读一下 README 第一行」这种,直接 Read 完回答就行。

4. 新手怎么主动触发

如果你发现 Claude 没用 todo 但任务复杂,主动让它用:

> 这个任务比较长,先用 TodoWrite 拆一下再开干

它会:

1. 调 TodoWrite 写出 list
2. 给你看 list,等你确认或补充
3. 开始一项项做

这是新手最该学的提示词之一——强迫 Claude 先想清楚结构再动手。

5. 和子代理的协作

复杂任务里,经常这样:

主代理 todo:
  [✓] 1. 整理需求
  [⏳] 2. 派子代理扫现有代码
  [ ] 3. 设计方案
  [ ] 4. 实现
  ...

主代理派 scanner 子代理时,会把当前任务的部分上下文(包含 todo 的相关项)传过去。子代理跑完只把报告回来,主代理收到报告后:

• 改 [2] completed
• 给 [3] in_progress

todo list 变成了主-子代理之间的协作合同。

6. 主动 review 它的 todo

Claude 拆出来的 todo 不一定对。你可以随时改:

> 你拆得有点散。把 3 和 4 合一项,然后在最前面加一步「先检查 git 状态」。

它会重新调 TodoWrite,出新版本。这种人机协作改 plan 的工作流,比一次性给完整任务效果更好。

7. todo 在哪里看

在 Claude Code 终端里,todo 状态会显示在底部状态栏(如果开启了)或inline 在对话流里。

每次 TodoWrite 调用,你会看到:

📋 TodoWrite 更新:
[✓] 1. 看现有搜索相关代码
[⏳] 2. 设计后端 API ← 当前
[ ] 3. 实现前端组件
[ ] 4. 写测试
[ ] 5. 跑一遍验证

中途出错或被中断,你一眼就知道走到哪了。

8. 跟子代理 / hooks 的位置

容易混。一个对比:

机制	作用层	谁用
TodoWrite	任务结构层	Claude 自己用,跟踪进度
Subagent	任务执行层	Claude 派出去干子任务
Hook	拦截层	你写的脚本,在工具调用前/后跑

最复杂的实战:TodoWrite 拆出 6 步,其中 2 步派 subagent,subagent 里触发了 hook 拦截危险命令——三个机制同时用。

9. 一句话总结

TodoWrite = Claude 给自己写的待办清单,让它能「连续做 30 分钟活而不忘事」。

理解这一点,你就理解了为什么有些人手里的 Claude Code 看着像有规划能力——不是模型变聪明了,是 todo 这个机制让结构显式化了。

---

想看 todo 一项项打勾的过程?去 Claude 课 试「实现一个完整功能」场景。