Codex 实践系列 Vol.05：长任务里的事实、边界和验收

摘要：用真实项目看看，给 Codex 立哪些规矩才真正有用。

前几期，我们更多是在告诉 Codex“要做什么”。至于哪些设计不能改、哪些事实不用重新调查、遇到信息缺口时该停在哪里、做到什么程度才算完成，这些规则一直作为实践的前置条件存在。

但我们很少单独展开聊一件事：在 Codex 动手之前，该怎么和它约定规矩？

这次实践，小七会拿一个真实的内部工具做实验，用一篇文章看看：提前写下来的这些规则，究竟能在多大程度上约束 Codex 的工作。

先把事实和边界写下来

这个数据自动统计的项目本身不算小。它需要从多个内容渠道来获取数据信息，还要处理不同格式的数据，再经过匹配、校验和整理，最终生成可以进入现有工作流的结果。

当中，有不少规则都来自前期的实测。比如哪些数据源是可以自动获取的，哪些数据源会碰到登录或人机验证问题；不同内容平台导出的数据文件中的字段怎么对应；表格中哪些列是属于固定的公式，不需要 Codex 额外寻找数据来源；哪些表格中的列不能碰；同一内容的不同渠道来源的内容标题发生变化以后，程序应该怎么匹配。

这些结论如果只存在脑子里，每开启一次 Codex 任务，就得重新解释一遍。

所以项目里先放了两份文件：

• SPEC.md 记录确认过的事实和约束。
• TASKS.md 再把项目拆成具体任务，并为每个任务写下依赖和验收条件。

图注：脱敏的 SPEC 和 TASK 部分内容的截图

我给 Codex 的第一条指令也从读文档开始：

完整阅读 SPEC.md 和 TASKS.md，先不要修改代码。

读完后告诉我：
1. 你对项目的理解；
2. 第一个任务准备怎么实现；
3. 文档中还有哪些歧义或信息缺口。

我确认后再开始。

同时再强调几条硬性边界：

• 已经验证过的技术结论按文档执行，不重新调研；
• 既定的数据读写方式不能自行替换；
• 遇到人机验证就停止自动采集，切换到降级方案；
• 公式列和停用列不能被采集数据覆盖；
• 缺少必要材料或凭据时，先说明阻塞原因；
• 验收条件里写了真实结果的，就必须拿真实样例跑。

这一步的目的只有一个：让 Codex 在动手之前，先知道哪些事情可以自己决定，哪些事情没有自由发挥空间。

先读规矩，再开始编码

第一轮里，Codex 没有写代码。它读完两份文档后，先列出了一批需要确认的问题。

其中有几处确实是文档自己的漏洞。比如关于公式列，一处写着“禁止写入”，另一处又要求最终生成的数据块必须包含公式。

Codex 把两个要求放在一起后，给出的解释是：采集得到的数值不能覆盖公式列；生成最终数据块时，则需要按照目标位置重新生成公式文本。

这个理解符合原来的设计。主要是说明文档里没有把两个层次说清楚。

另外一处是任务依赖。某个前置任务要求记录执行日志，但负责存储日志的模块排在后面。如果完全按照任务编号执行，中间会遇到一个尚未实现的依赖。

它还发现了一些参数没有定义完整，以及表格结构里看起来不连续的位置。代码一行还没写，文档先被检查了一轮。

图注：Codex 给的第一轮反馈 以前让 Codex 做一个小修改，需求本身比较短，理解偏差很快就能看到。到了长任务里，错误可能先藏在需求、约束和任务依赖之间。

所以“先读完再动手”这条规矩，本身就变成了一次实现前检查。

可验收的结果

除了边界，我还在任务表里给不少任务写了验收条件。尽量避免只写：功能可以正常运行，而是写成这样：

给定这份真实输入，
应该得到这个确定的结果。

比如解析一份真实样例后应该有多少条记录，某个字段最后应该读到什么值，几组标题之间应该匹配成什么结果。某个平台的导出文件中，「展现量」和「阅读量」字段刚好挨在一起，第一条数据分别是 121,063 和 1,031。程序就算取错了列，其实也照样能跑，甚至看起来还挺正常。

所以验收条件里我会把结果写死：第一条记录的阅读量应该是 1,031。 跑一下真实样例，是不是拿错字段马上就能看出来。

标题匹配也差不多。9 条内容去匹配另一个平台的 122 条数据，正确结果是 8 条匹配成功，1 条匹配不上。那一条本来就没有同步过去，所以没匹配上才是对的。

如果这里只写“匹配率越高越好”，反而容易出问题。为了把数字做得更漂亮，最后那一条也可能被硬凑出一个结果。

最小完整流程

一开始的版本，项目拆得很细，拟定的任务表是逐个模块推进。后面发现如果每完成一个底层模块就停下来确认，需要经过很多轮才能看到完整结果。

于是，中间调整了一次做法：先跑通 读取现有数据 → 获取外部数据 → 匹配内容 → 生成最终结果 这条主链路，界面、更多数据源和依赖额外材料的部分暂时放到后面。

主链路很快就跑通了。数据可以获取，内容能够匹配，最终结果也顺利生成，单看终端输出没有明显异常。

图注：Codex 第一轮的输出结果

但把生成结果和真实数据放在一起核对后，几个隐藏在模块之间的问题很快暴露出来。比如同一条内容在某个来源中出现了多份合法记录，而且对应的数据不同。程序可以选择其中一条，却没有足够依据判断哪一条才应该进入最终结果。遇到这种冲突，比较恰当的处理方式是保留异常并进入人工复核。

还有隐蔽的分页问题。第一版采集只读取了列表第一页，而第一页本身就包含不少数据，所以整个流程不会报错，看上去也足够完整。可这个项目实际要回填的是前一个统计周期的数据，只抓最新一页，恰好会漏掉真正需要处理的那一批内容。补上分页以后，匹配覆盖才恢复正常。

此外，“未匹配”这个状态也需要进一步拆分：有些记录只是因为目标行还没建立，有些来自重复数据，剩下的才是真正的匹配失败。全部塞进同一个状态里，虽然格式正确，却无法告诉人下一步应该怎么处理。

这几个问题都很难靠单独检查某个函数发现。因为整个流程中，采集模块可以正常返回数据，匹配模块也能给出结果，输出模块同样能生成正确格式；只有让真实数据从入口一路跑到最终结果，再和现有数据核对，模块之间隐藏的问题才会暴露出来。

规则之外

这次把整条流程跑了一遍之后，我也重新看了一遍前面写下的那些规则。

有些要求在项目开始前就能确定，比如不能覆盖公式、遇到人机验证就停止、缺少必要信息时回来询问。这些属于一开始就要写清楚的边界。

但还有一些问题，只有真的跑起来以后才会出现。比如同一条内容出现两份数据时该怎么处理，采集列表需要翻到第几页，“未匹配”到底是目标记录还没建立、数据重复，还是确实没有找到对应内容。这些情况很难在开始写需求时全部想到。

所以长任务里的规则也会随着项目推进不断补充。发现重复数据，就加上“冲突记录交给人工确认”；发现分页漏掉了上一周的数据，就把需要覆盖的时间范围写进采集要求；发现“未匹配”这个状态太模糊，再把它拆成几种更具体的情况。

更适合这类项目的做法，是先把确定好的事实和不能越过的边界写清楚，再用一次次真实运行的结果，把新的情况补回规则里。这样项目在往前做，Codex 能遵循的规则也会越来越完整。

验收 Codex 的“完成”

项目推进到后面，还遇到过一个很典型的问题。当后面我让 Codex 连着处理多个任务时，最后它给出的报告显示，这批工作已经完成。

但重新打开仓库检查后，发现只完成了 3 个，剩下 7 个模块只有空的 __init__.py，测试里也留着没有通过的项目。其中有些任务确实卡在客观条件上。比如识图功能还缺真实截图和模型 API Key；测试里还有一项依赖 LibreOffice，而本机没有安装。这些都可以解释为什么对应任务没有完成，但 Codex 最后仍然把整批任务报告成了“完成”。

虽然资料缺失，是我的问题。但 Codex 把这些不同状态都归成了“完成”，这是交付质量的问题。所以，后面 Codex 再处理长任务时，我会额外检查三件事：代码有没有真正写下来，测试有没有实际跑过，最后产出的结果能不能拿真实数据核对。

如果缺少必要材料，更清楚的反馈应该是：目前做到哪一步，哪些检查通过了，卡在哪里，接下来还需要补什么。而 Codex 给的执行报告能帮助了解任务进度，但到底任务进展如何，还是得看具体的代码和测试结果。

有用的规则

这次实践之后，我更倾向于把交给 Codex 的规则分成三类。

第一类是事实。已经实测确认的结论，就写进项目里，避免 Codex 每次执行时重新判断一遍。

第二类是边界。哪些设计不能自行修改，哪些动作不能做，遇到什么情况需要停下来交给人处理，都应该提前说清楚。

第三类是验收。每个阶段做到什么程度才算完成，最好留下一个人可以独立核对的结果。这样 Codex 汇报“完成”之后，还能用真实结果再检查一次。

至于某个函数具体怎么写、目录怎么组织、内部实现先从哪一步开始，可以给 Codex 留出更多决策空间。长任务里，规则写得越细，不一定越可靠。

最重要的事情是让 Codex 弄清楚三件事：哪些事实不需要重新猜，哪些边界不能越过，以及最后用什么结果证明任务做对了。