024、任务分解方法论：用 TodoWrite 把大任务拆成可追踪、可验证的步骤

024、任务分解方法论：用 TodoWrite 把大任务拆成可追踪、可验证的步骤

上周五凌晨两点，我被一个生产事故电话吵醒。一个数据管道任务跑了六个小时，最后一步写入数据库时挂了——原因是某个中间步骤的临时文件被清理了。排查日志发现，整个任务被写成了一个巨大的 Python 脚本，2000 行代码，try-except 套了三层，中间没有任何 checkpoint。最要命的是，没人知道它到底执行到哪一步了。

这种“黑盒式”的大任务，是 DevOps 和 AI 工程化里最常见的坑。你写的时候觉得“逻辑很清晰”，跑起来就变成“听天由命”。Claude Code 的 TodoWrite 工具，就是专门用来解决这个问题的——它不是让你写更长的 prompt，而是帮你把任务拆成可追踪、可验证的步骤。

从一次失败的 prompt 说起

先看一个反面教材。我让 Claude Code 处理一个日志分析任务：

帮我分析这批 Nginx 日志，找出 5xx 错误最多的 IP，然后生成报告。

Claude Code 吭哧吭哧跑完，给我一个 JSON 文件。我打开一看，数据对不上——它把 4xx 也算进去了。我改 prompt 重跑，这次它把时间范围搞错了。第三次，它直接超时了。

问题在哪？我把一个需要多步骤验证的任务，当成一个“黑盒”丢给了 AI。Claude Code 不是神仙，它不知道你心里想的“分析”具体指什么——是统计、过滤、聚合还是可视化？每一步的边界条件是什么？中间结果要不要校验？

TodoWrite 的正确打开方式

TodoWrite 的核心思想很简单：把大任务拆成原子步骤，每一步都有明确的输入、输出和验证条件。但很多人用错了——他们只是把任务描述拆成几个句子，比如“第一步：读取文件；第二步：过滤数据；第三步：生成报告”。这跟没拆一样。

真正的拆法，是让每一步都能独立运行、独立验证、独立回滚。

看一个我实际用过的例子。我需要处理一批电商订单数据，清洗、去重、计算指标、写入数据库。传统做法是写一个 pipeline 脚本，但用 TodoWrite 拆解后是这样的：

步骤1: 读取原始订单文件，校验格式 - 输入: /data/orders/raw/*.csv - 输出: /data/orders/validated/orders_valid.csv - 验证: 检查每行字段数是否为12，时间戳格式是否合法 - 回滚: 删除输出目录 步骤2: 去重（基于订单ID和下单时间） - 输入: 步骤1的输出 - 输出: /data/orders/deduped/orders_deduped.csv - 验证: 去重后记录数 <= 原始记录数，且无重复订单ID - 回滚: 删除输出目录，保留步骤1结果 步骤3: 计算指标（GMV、客单价、复购率） - 输入: 步骤2的输出 - 输出: /data/orders/metrics/metrics.json - 验证: GMV > 0，客单价在合理范围内（50-5000元） - 回滚: 删除输出文件 步骤4: 写入数据库 - 输入: 步骤3的输出 - 输出: 数据库表 orders_metrics - 验证: 写入行数 == 指标数量，无主键冲突 - 回滚: DELETE FROM orders_metrics WHERE batch_id = 'xxx'

注意看，每一步都有明确的“验证”和“回滚”逻辑。这不是冗余——这是生产环境的保命符。

踩过的坑：别把验证写成摆设

我第一次用 TodoWrite 时，验证条件写得太宽松了。比如“检查文件是否存在”——这算哪门子验证？文件存在不代表内容正确。后来我改成“检查文件行数是否大于0，且每行字段数符合预期”，这才真正起作用。

另一个坑是回滚策略。很多人只写“删除输出”，但没考虑依赖关系。比如步骤2失败了，你删了步骤2的输出，但步骤1的输出还在——下次重跑时，步骤1会跳过（因为输出已存在），直接跑步骤2。这会导致数据不一致。正确的做法是：每一步的输入必须来自上一步的验证通过标记，而不是仅仅依赖文件存在。

我现在的做法是，每一步完成后写一个.done标记文件，里面包含这一步的校验和。下次重跑时，先检查.done文件是否存在且校验和匹配，否则重新执行这一步。

实战：用 TodoWrite 重构一个 AI 推理任务

最近我在做一个文本分类模型的批量推理任务。原始 prompt 是这样的：

对这批用户评论进行情感分类，输出正面、负面、中性

结果 Claude Code 把“这个产品还行”分成了正面，把“一般般吧”分成了中性——但业务方要求“还行”算中性，“一般般”算负面。这种边界情况，黑盒推理根本处理不了。

用 TodoWrite 重构后：

步骤1: 加载模型和标签映射 - 验证: 模型文件存在，标签映射包含所有预期类别 - 这里踩过坑：模型文件路径写死了，换环境就炸。改成从环境变量读取 步骤2: 读取待分类文本，按批次分组（每批100条） - 验证: 总条数 > 0，每批条数 == 100（最后一批除外） - 别这样写：一次性加载所有文本到内存，10万条直接OOM 步骤3: 对每批文本进行推理 - 输入: 批次文件 - 输出: 推理结果（带置信度分数） - 验证: 每条结果都有分类标签和置信度，置信度在0-1之间 - 这里踩过坑：模型推理时GPU显存溢出，没有捕获异常。加了try-except后，失败批次自动重试 步骤4: 后处理：根据业务规则修正边界情况 - 规则: "还行" -> 中性, "一般般" -> 负面, "不错" -> 正面 - 验证: 修正后的分类分布与原始分布差异不超过10%（防止过度修正） 步骤5: 生成最终报告，写入数据库 - 验证: 写入条数 == 输入条数，无空值

每一步都可以独立调试。比如步骤3的推理结果不对，我只需要重新跑步骤3，不需要从头开始。步骤4的业务规则调整了，也只需要重新跑步骤4。

个人经验：TodoWrite 的黄金法则

用了大半年 TodoWrite，总结几条血泪教训：

1. 每一步的粒度，以“能否在5分钟内验证”为准。如果这一步跑完需要10分钟才能验证结果，说明粒度太粗了。拆到每一步验证不超过1分钟。

2. 验证条件要写“可编程的断言”，而不是“人工检查”。比如“检查数据分布是否合理”这种话，AI 不知道怎么验证。改成“检查数值字段的均值是否在历史均值的±20%范围内”。

3. 回滚策略要写“幂等的”。意思是重跑多次结果一样。比如“删除输出文件”是幂等的，“追加写入”不是。别让重跑变成灾难。

4. 给每一步加一个“超时时间”。Claude Code 有时候会卡住，尤其是调用外部 API 时。设置超时后，超时步骤自动标记为失败，不会阻塞整个任务。

5. 最后一条，也是最重要的：TodoWrite 不是银弹。它解决的是“任务可追踪、可验证”的问题，不是“任务逻辑正确”的问题。你依然需要理解业务逻辑，设计合理的验证条件。工具只是放大你的能力，不能替代你的判断。

现在每次写 prompt，我都会先问自己：这个任务能不能拆成5-10个独立步骤？每一步的验证条件是什么？如果这一步失败了，怎么回滚？如果答案都是“是”，我才开始写。否则，先回去想清楚再动手。

那个凌晨两点的电话，我再也没接到过。