Codex 高级用法：工程协作工作流 · 用证据完成工程交付
从计划到改动：让 Codex 在证据链中执行
从真实基线出发限定变更范围，在实施过程中记录目标、改动、局部检查、状态变化和偏差，使每一步都能回到计划与完成条件，而不是只留下“已经改完”的声明。
计划写得很完整，真正开始改文件时，Codex 仍然可能走偏。它可能按文件名猜实现位置，顺手修掉范围外的问题，做到一半忘了更新状态，最后只返回一句“已经完成”。代码或文章也许真的改了，但我们很难回答：为什么改这里，实际改了什么，哪一步检查过，偏差又留在哪里。
在小编看来，受控执行的关键是让每次动作都能指回目标、仓库事实和当前完成条件。 这不等于实时盯着每一行，而是从开工前的基线开始，保留一条足以解释改动的证据链。
上一篇解决了 Agent 之间怎样交接任务现场。本文接着让接收者进入真实写入，讨论基线检查、变更范围、实施记录、局部验证、状态更新和回退点。完整测试是否充分、独立审查能否放行，留给 04-02。
一、计划只是意图，开工要先读真实基线
交接消息可以告诉执行者目标和路径，磁盘才说明此刻能不能按原计划动手。两者之间可能隔着用户的新修改、其他 Agent 的写入或一次未完成操作。直接照计划执行，相当于拿旧地图开进新路况。
基线检查围绕当前步骤即可，不需要先扫描整个仓库：
- 目标文件是否存在，已有内容能否覆盖；
- 计划和状态文件记录的阶段是否与交接一致；
- 显式前置产物是否达到可用状态；
- 当前工作区是否已有同路径或相关事实来源的修改；
- 本次授权是否仍覆盖将要执行的动作。
发现冲突后先更新判断。目标文件已经存在，就要区分续写、局部修改和覆盖；前置状态不满足，就不能为了赶进度跳过依赖；其他修改碰到同一事实来源，则要先确认所有权。基线检查最终应给出一句能决定下一步的结论，并保留支撑它的路径或结果，无需搬运整段终端输出。
本文的写作现场提供了一组可以复查的例子。04-01 启动前，规划指定的正文文件尚不存在，topic.md 中 04-01 为 planned，显式前置 03-03 为 reviewed。用户授权按顺序继续写作，同时明确不启动质检、不配图。由这些事实可以推出本阶段允许创建正文并更新 04-01 状态，不能推出文章已经通过独立审查或可以发布。
二、先写变更范围，再开始修改
执行范围至少包含“要改什么”和“明确不改什么”。只列目标文件仍然不够，因为一个局部目标常常要求同步维护状态、引用或配置；反过来，“相关文件都处理一下”又会把影响面交给临场猜测。
对本文这次实施，最小充分范围是：
1允许修改：
2- articles/04-01-execute-codex-tasks-with-evidence.md
3- topic.md 中 04-01 的状态字段
4
5保持不变：
6- 其他文章正文和规划字段
7- reviews/ 下的独立审阅报告
8- 配图、发布和外部系统状态这个范围同时回答了跨文件一致性问题。只创建正文而不更新文章状态，计划会继续显示“尚未开始”；只改状态而没有正文，状态又失去对应产物。两处修改属于同一个阶段事实，应一起完成。其他相邻内容即使看起来可以顺手优化，也不属于当前目标。
代码任务也可以按同样方式判断。一个接口字段变化可能要求同步修改实现、类型定义和直接受影响的测试，这属于维持同一行为的一致性；趁机重构整个模块则需要新的依据和授权。最小充分修改追求闭合当前目标，文件数量只是结果。
三、实施记录要连接动作与理由
流水账会记录“打开文件、搜索文本、执行命令”，却解释不了工作为什么这样推进。有用的实施记录只保留会影响判断的节点：当时看到了什么证据，因此决定修改什么，修改后用哪项局部检查确认基本一致。
| 阶段 | 目标与完成条件 | 观察到的事实 | 执行动作 | 当前证据 |
|---|---|---|---|---|
| 基线 | 确认 04-01 可以开始写作 | 目标文件不存在；04-01 为 planned；03-03 为 reviewed | 将目标状态进入写作阶段 | topic.md 的对应条目与目标路径 |
| 实施 | 正文回答“如何在证据链中执行” | 规划要求覆盖基线、范围、记录、局部验证、状态与偏差 | 创建指定正文，不修改其他文章 | 本文文件及其 Frontmatter |
| 一致性 | 正文与计划状态相互对应 | 正文已创建，最终状态仍需在自审后确认 | 自审通过后同步改为 drafted | 本文状态与 topic.md 状态一致 |
| 局部检查 | 确认本次写入结构完整且未产生明显格式错误 | 待执行写后检查 | 检查 Frontmatter、标题、代码块、路径、状态和差异格式 | 写后补充实际结果，不预写成功 |
表格里没有“实现成功率”或虚构的耗时数据。它只串起当前任务能够观察和复查的对象。对于代码修改，证据可能换成定位调用链的搜索结果、变更差异、编译错误或针对性测试；选择哪一种，取决于这一步要排除什么风险。
实施中出现新发现时，不要偷偷改写原计划。先判断它属于哪一类：
- 仍在授权范围内，只影响实现细节：记录理由，继续最小修改；
- 会扩大文件、模块或外部影响面：暂停并回到确认门禁；
- 推翻了原前提：更新计划状态，说明旧步骤为何失效；
- 与当前目标无关：记录为后续事项，不顺手处理。
偏差记录保存了计划与真实仓库接触后的校正。它没有进入状态或说明时，下一位接手者看到的仍是已经过期的原计划。
四、局部验证负责当前动作，不替代最终验收
每次修改后都等到最后再检查，问题会混在一起。局部验证更像缩短反馈距离：刚改完状态，就核对正文与 topic.md 是否一致；刚写完 Markdown，就检查 Frontmatter、标题层级和代码块是否闭合；代码改动则先运行与当前模块直接相关的检查。
局部检查要和风险配对。修改 YAML 时，格式解析比“文件能打开”更有信息；调整函数签名后，搜索遗留调用点比通读一遍代码更直接；生成文件时，路径和实际文件存在性是最先要核对的事实。
但局部检查通过只支持有限结论。Markdown 代码块成对闭合，不能证明文章事实准确；单个模块测试通过，也不能证明跨模块行为没有回归。本文只要求为本次改动留下可交给下一阶段的证据，04-02 再讨论怎样组合静态检查、测试、构建和独立审查形成验收结论。
证据也不必全部塞进最终回复。值得保留的是能支撑判断或帮助复现失败的部分，例如：
- 修改前后的目标状态和对应文件；
- 实际变更范围，与授权范围是否一致；
- 关键定位依据和舍弃备选的理由；
- 局部检查名称、结果以及它能证明到哪一步；
- 未解决偏差、待验证事实和下一阶段入口。
重复搜索、没有改变判断的长输出和临时调试噪声可以省略。证据链只需留下足够索引，让别人能够重新核对关键结论。
五、状态更新要跟着事实走
状态会告诉后续角色现在可以做什么，也决定任务中断后从哪里恢复。它更新得太早，会让下游在产物不完整时开工；更新得太晚，则会造成重复执行。
在当前 JVS 写作流程中，04-01 从 planned 进入实际写入时改为 drafting。只有正文完整、第二遍自审和写后检查通过，正文 Frontmatter 与 topic.md 才能一起变成 drafted。article_master 没有权把它标成 reviewed，因为那需要独立质检结论。
回退点也应和状态对应。写作中断时保留 drafting，并记录已完成段落、未核事实和下一步；局部检查失败时，不把状态推进到 drafted；新发现超出授权时，保留已安全完成的修改，报告分叉和影响范围。是否撤销已有修改要看它们能否独立成立以及用户授权，不能为了让工作区“看起来干净”做破坏性回滚。
下面是本文在本轮执行结束时应留下的受控实现记录。结果栏会在实际检查后更新，不用预期代替输出。
1execution_record:
2 target: 04-01 从计划进入正文草稿
3 baseline:
4 article_file: 不存在
5 topic_status: planned
6 prerequisite_03_03: reviewed
7 authorized_changes:
8 - 创建 articles/04-01-execute-codex-tasks-with-evidence.md
9 - 仅更新 topic.md 中 04-01 的状态
10 actual_changes:
11 - 已创建目标正文
12 - 写入时将 04-01 切换为 drafting
13 - 自审与局部检查后将正文和 topic.md 同步为 drafted
14 local_checks:
15 frontmatter_and_status: 通过，文章编号、正文状态与 topic.md 条目一致
16 markdown_headings_and_fences: 通过，标题层级可解析，代码围栏为偶数
17 paths_and_whitespace: 通过，目标文件存在，未发现行尾空白
18 deviations:
19 - 无已知范围扩张
20 rollback_point: 局部检查失败时保留正文并维持 drafting，本轮未触发
21 not_proven:
22 - 文章事实与表达已通过独立质检
23 - 系列任务已经完成最终验收从计划进入改动，需要先读基线、限定范围，再让 Codex 动手。每个关键动作记录依据，用局部检查缩短反馈距离，让状态跟随真实产物，偏差则留在下一位接手者能看到的位置。执行阶段由此留下了一条可以继续验证、也可以在失败后定位和回退的证据链。