我打开本机计划系统的状态校验脚本,想弄清一个看起来很小的问题:事情做完,准备交给别人审查时,为什么不能把「当前任务」顺手写成 review?
按日常说话的习惯,这句话完全通顺。前面在做事,现在在审查,接手的人似乎也能看懂。但我沿着代码往下读,发现程序没有问「这个词像不像下一步」,它问的是:这个值在任务图里找得到吗?
这个差别让我停了一下。人看的是一句进度说明,程序拿到的却是一个需要定位的入口。我们以为只是把状态写得自然一点,实际可能改变了这个字段的用途。
一句话里藏着不同的问题
「现在在审查」可以回答整个计划走到了哪个阶段,却未必能回答当前具体要处理哪项工作。审查界面、审查文稿、审查验证证据,都可以叫审查。只留下 review,接手者还得重新寻找对象和范围。
本机的计划文件说明已经把这些信息分开:任务清单记录任务单元及其依赖、产物和验收要求,任务图保存机器可读的依赖关系,状态文件记录当前位置,审查文件保留发现、必要修复和结论。
举一个假设的交接场景:文稿已经写好,但引用核对还没有完成。此时写「审查中」,只能告诉接手者不要把它当成最终结果;如果当前任务指向「核对引用」这一项,对方才能继续找到待核对的材料、应当留下的记录,以及通过的条件。前者提供背景,后者提供行动入口。两者都需要,却不能互相代替。
这些文件名字并不重要,重要的是它们各自回答什么。如果我把阶段名称塞进当前任务,看似少写了一点内容,实际上把「正在什么阶段」和「正在处理什么」合并了。
当前任务应该让接手者找到工作对象,而不只是知道工作气氛。
我愿意用一个简单的办法区分:看到这项记录,能否沿着它找到具体要求?如果还需要猜「大概是去看看有没有问题」,它就更适合作为进度描述,不能独自承担交接入口。
校验器检查的是对应关系
当前代码先从任务图取得任务标识,再读取状态文件中的「当前任务」。只要这个值非空、不是特殊值 complete,又不在任务标识集合中,就会被列为问题。代码并没有单独禁止 review,它禁止的是指向不存在任务的值。
这里必须说准确。假如只把当前任务改成 review,却没有在任务结构里定义相应工作,它会失去对应关系。即使临时在任务图里添上同名项,也不能据此宣称整个计划已经合法,因为还有任务清单之间的对应检查,而现有清单解析使用固定的编号形式。
校验器还会比较清单与任务图的任务状态,检查两边是否缺项。当存在下一项依赖已满足的任务时,它也会检查当前任务是否与之相符。由此看,当前任务不是随手填的一句备注,它参与了一组跨文件约束。
一个字段能被人读懂,不代表它能被系统正确使用。
我更愿意把这种约束理解成接手时的共同语言。人可以说「已经差不多了」,保存下来的记录却需要说明,哪些工作已经结束,哪些工作仍然存在。否则,下次接手时,那句自然的话还得被重新解释一遍。
做完任务,不等于审查通过
继续读状态同步与任务推进的代码,能看到一个很有意思的组合:当任务选择逻辑返回 complete,写入状态文件的计划状态会是 review,而当前任务则是 complete。
这不是自相矛盾。任务选择逻辑在非空任务图中发现所有任务都已完成或跳过时,会返回这个特殊值。它表达的是这组任务已经走到了终点;进入 review 则表达计划仍处在审查阶段。
这也提醒我,不能把 complete 翻译成「所有事情都通过了」。它所在的字段有自己的范围。任务做完了,审查还可能提出问题;没有剩余执行项,也不自动意味着结果值得交付。
本机测试文件中,有案例专门检查完成判断需要实现记录和审查结论。另一个案例针对「未批准」的审查文字,防止它因为含有「批准」这个词就被误认。这里我读到的是测试意图,没有把阅读代码说成现场运行通过。
任务进度、计划阶段和审查结论,需要分别留下证据。
把它们分开以后,review 就有了合适的位置。它可以说明计划进入审查,也可以出现在具体审查任务的名称里;但不能因为人觉得这个词顺口,就替代原本用来定位任务的标识。
最省事的修改可能藏住缺口
最容易想到的捷径,是放宽校验:既然 review 很常用,把它加进例外就好了。这样眼前的提示可能消失,任务对象却仍然不明确。系统接受了这个值,不代表接手者知道该检查哪些产物。
另一种捷径,是直接把当前任务改成 complete。它恰好属于校验器允许的特殊值,容易给人一种「这样就对了」的感觉。但当前代码对这个值有豁免,不能仅凭这一项校验通过,就证明任务实际全部结束。
如果把审查安排成独立任务,我倾向于给它正常的任务编号,补齐审查对象、依赖和可验证的输出,再让当前任务指向它。这是根据现有结构提出的做法,不是声称本次已经改造过某个计划。如果审查由计划阶段统一承接,就保留阶段与任务的区分,继续记录审查结论。
关键取舍在这里:我不想为了填满一个字段,就临时发明一项没有内容的工作;也不想为了让校验安静,就提前宣布执行结束。应该先确认工作怎样组织,再决定这个位置该保存什么。
消除校验提示的前提,是修正它指出的事实,而不是只替换触发提示的词。
规则有用,也有它没覆盖的地方
读到这里,我也不能把现有实现描述成完美的状态系统。任务选择函数会寻找依赖满足的待处理任务;找不到时,同步脚本会用 blocked 作为回退值。但当前校验逻辑显式豁免的是 complete,如果 blocked 不在任务图中,它同样可能触发不存在任务的提示。
这说明写入方与校验方的边界还存在需要核对的地方。本文讨论的 review 问题有明确代码依据,却不能顺势推导出「其余状态都已经处理正确」。一条规则能拦住某类错误,不等于整套流程已经没有遗漏。
类似地,校验脚本把结果放在输出的 ok 和 issues 中,而主函数末尾返回的是 0。调用者如果只看命令是否正常结束,仍然可能漏掉校验发现的问题。运行成功与检查通过,在这里也需要分开理解。
这些细节让我重新意识到,写规则和使用规则是连续的责任。写入者要知道字段允许表达什么,检查者要覆盖相应状态,调用者还要真正读取检查结果。只把其中一层做得严肃,仍然可能留下误解。
我没有据此去扩展本次任务、修补计划系统。当前要完成的是把方法讲清楚:检查指向、检查状态之间的对应关系,也检查校验本身的覆盖范围。遇到缺口就如实记录,不把静态阅读包装成运行保证。
下次我会怎么做
下次接手一份需要跨会话继续的计划,我会先沿着当前任务找到任务清单和任务图,确认它指向真实工作,再看依赖是否满足、完成状态是否一致。找不到时,先追查记录怎样产生,不急着换一个看上去合理的词。
如果工作已经进入审查,我会明确审查由哪一层承接。作为独立任务,就保留可定位的编号与具体要求;作为计划阶段,就把阶段状态与执行终点分别记录,并检查审查结论是否真正形成。
我还会把解释性的句子留在合适的位置。「为什么停在这里」「接手时注意什么」可以写得自然、具体,甚至保留必要的犹豫;负责定位的字段则保持明确。这样既不要求人像机器一样说话,也不要求程序从一句感想中猜出执行顺序。对我来说,这是保存上下文与保存状态之间值得坚持的分工。
更新之后,我会读取校验结果里的问题列表,而不只看命令是否退出成功。若出现规则没有完整覆盖的情况,也会把不确定性说清楚,避免留下一个表面整齐、实际仍要猜测的交接点。
我不会因此给每件小事都建立复杂的计划包。当前计划说明也把普通单次任务与需要长期保存状态的工作分开。真正值得留下这些对应关系的,是那些下一次可能由不同会话、不同执行者继续的工作。
这件事让我更在意一个朴素的问题:当我不在现场解释时,留下的文字还能不能帮助别人准确行动?「当前任务」只有几个字,但它承担的正是这种责任。把它写清楚,下一次开始工作时,才少一次对昨天的猜测。