最近在完善计划校验脚本时,遇到了一个看起来很小但影响很大的设计问题:计划里的"当前任务"字段,为什么不能写成 review?
这个问题一开始并不明显。我在写计划模板时,很自然地想把"当前正在做什么"记录下来,于是就在某个计划里写了类似"review 上一轮执行结果"这样的当前任务。脚本没有报错,计划看起来也合理。但后来真正执行时,才发现这个写法会直接导致计划状态判断失败。
表面上看,这只是一个字段格式问题。但实际上,它触及了计划系统的核心设计原则:计划必须能被执行系统无歧义地理解和继续。
问题和表面原因
计划系统有一个校验脚本,负责检查计划的状态是否自洽。其中一个校验规则是:如果计划标记为 in_progress,那么必须有一个清晰的"当前任务"告诉执行者接下来做什么。
这个设计很合理。否则计划执行到一半,下一个 Agent 接手时,就只能靠猜。
但问题出在"当前任务"的写法上。
如果我写:
## 当前任务
- review 前面的对话
- 整理执行记录
校验脚本会报错。不是因为格式不对,而是因为 review 不是一个可执行的任务边界。
review 是一个持续过程,它可以很长,也可以很短,可以在任何地方停下来。执行系统看到"review"这个词,依然不知道该从哪里开始,该在哪个地方停下来,该产出什么作为完成标志。
计划和 review 的本质区别是:计划描述"做什么、做到什么程度、怎么验证完成",review 描述"看看前面发生了什么"。
前者是执行导向,后者是理解导向。执行系统需要前者。
为什么容易误写成 review
这个错误很常见,因为它符合人的思维习惯。
当我们在一个计划执行到一半时,很自然地会想:"我先看看前面做到哪里了。"这句话翻译成计划语言,就容易变成"当前任务:review 已执行内容"。
但这样写有三个问题。
第一,review 没有明确的完成标准。你什么时候算 review 完了?是把每个文件都看一遍,还是只需要看关键输出?如果 review 过程中发现了问题,是当场改还是记下来后面改?这些都不清楚。
第二,review 容易变成纯消耗时间。执行系统开始 review,然后发现前面有个地方可以优化,于是就去优化了。优化完又发现另一个问题,于是又去处理。原计划里的任务反而被搁置了。
第三,review 让计划状态变得模糊。如果"当前任务"是 review,那么计划到底是"正在执行"还是"暂停在理解阶段"?状态判断会出现灰色地带。
我第一次遇到这个问题时,计划校验报错,我的第一反应是:review 难道不是一种任务吗?
后来才意识到,任务必须是"做了之后能让计划向前推进的一步",而不是"帮助我理解现状的活动"。
理解现状很重要,但它应该发生在任务之前,而不是作为任务本身。
正确的写法是什么
经过几次调试和改写,我现在倾向于把"当前任务"写成非常具体的动作,包含三个要素:
- 做什么:明确的动作,最好是动词开头
- 做到什么程度:产出什么,改什么文件,或者达到什么状态
- 怎么验证:完成的标准是什么
比如,同样是要理解前面的执行结果,不要写:
- 当前任务:review 执行记录
而是写:
- 当前任务:读取 IMPLEMENTATION_LOG.md,提取未关闭的 TODO 项,更新 TASKS.md 的状态列
- 完成标准:TASKS.md 中所有任务状态与 IMPLEMENTATION_LOG.md 一致
这两种写法的区别是:第一种说"我要去看看",第二种说"我要做完一件能让后面继续的事"。
计划系统不是一个记录思考过程的笔记本,而是一个让任意 Agent 都能接手并继续推进的执行说明书。
这个定位决定了计划里的每一个字段都必须可被机器解析和执行,而不仅仅是被人理解。
校验脚本为什么这么严格
一开始我觉得校验脚本太严格了。写个 review 怎么了?我又不是不知道自己在做什么。
但后来发生了一件事,让我改变了看法。
有一次,我写了一个计划,当前任务写的是"review 并完善配置"。然后我让另一个 Agent 继续执行这个计划。结果那个 Agent 花了很长时间在"review"阶段,看了很多文件,做了一些改进,但没有明确停下来,也没有明确进入下一个任务。
等我回头看时,计划状态变成了一种尴尬的中间态:执行了一部分,但没有 marker,没有状态更新,没有验证记录。我只能手动去猜它到底做了什么,做到哪里了。
如果当时当前任务写的是具体动作,比如"修改 config.py 中的超时参数,从 30 改为 60,然后运行单元测试验证",那么无论谁接手,都知道该做什么、做到什么程度、怎么验证。
校验脚本的严格,不是在为难写计划的人,而是在保护执行阶段的确定性。
计划写得模糊,执行一定会付出代价。这个代价可能是时间,可能是重复劳动,可能是状态混乱。校验脚本把这个问题提前暴露出来,迫使你在写计划时就想清楚执行细节。
这很烦,但很有必要。
更深一层:计划是写给未来的自己或同事看的
这件事让我重新理解了计划系统的定位。
计划不是写给当前正在思考的自己看的。当前正在思考的自己不需要计划,因为所有上下文都在脑子里。
计划是写给未来的自己,或者未来的同事看的。
未来的自己可能已经忘记了今天的细节。未来的同事可能完全没有参与过前面的讨论。他们拿到计划时,只能依靠计划文件里写的内容来判断该做什么。
如果计划里写的是 review,他们就会真的去 review,然后陷入我前面说的那个循环。
如果计划里写的是具体任务,他们就能直接开始执行,执行完就知道该不该进入下一个任务,该不该更新状态,该不该写执行记录。
所以我现在的做法是:写完计划的"当前任务"后,我会试着把自己想象成一个完全不了解背景的人,然后问自己:"如果我只看到这句话,我能知道该做什么吗?"
如果不能,我就重写。
下次我会怎么做
下次写计划时,我会在"当前任务"这个字段上多花几分钟。
具体做法:
第一,避免以 review、理解、梳理、看看这类词作为当前任务的开始。 这些词描述的是认知活动,不是执行活动。认知活动很重要,但它应该发生在写计划之前,而不是作为计划的一部分。
第二,当前任务必须是一个"做了之后计划就能向前推进一步"的动作。 如果做了之后计划状态没有变化,那它可能不是当前任务,而是准备工作。
第三,写完当前任务后,我会用一个很简单的方式自检:假设我现在不能执行这个计划,只能把计划发给另一个人,他能根据这句话知道该做什么吗? 如果答案是能,那就对了。如果答案是他需要先了解背景,那就说明当前任务写得不够具体。
第四,我会把校验脚本当成强制性的预检查,而不是可选的格式化工具。 每次写完计划,我都会跑一遍校验,确保所有警告都被处理掉。不是因为脚本不能容忍警告,而是因为警告通常意味着执行时会出现歧义。
计划系统最核心的价值,不是帮你记录想法,而是帮你在未来任何一个时间点,都能以最低的认知成本继续执行。
"当前任务"是这个系统里最关键的字段之一,因为它直接决定了执行入口是否清晰。这个字段不能写成 review,因为它必须是一个可以立即开始执行的具体动作。
这看起来是一个格式问题,实际上是一个思维方式的问题:你在写计划时,是在记录思考,还是在准备执行?
这两个目的需要的文字完全不同。