任务执行与验证闭环

前面你已经知道如何把任务交给 Codex。这一章解决另一个更重要的问题：怎么判断它真的完成了，而不是看起来完成了。

一个稳定的 Codex 任务通常包含六步：

说明目标 -> 让它建图 -> 小步执行 -> 检查 diff -> 运行验证 -> 记录结果

第一步：写清任务

不要只写“帮我改一下”。更好的任务说明通常包含：

• 目标：你希望最终得到什么。
• 背景：相关文件、页面、报错、截图或业务规则在哪里。
• 范围：这次允许改哪里，不允许改哪里。
• 验证：完成后应该跑什么命令，或检查什么结果。
• 交付：希望它最后怎么汇报。

可以这样写：

请只读分析当前项目的文档结构，不要修改文件。
请指出首页、学习路线和侧边栏之间不一致的地方。
输出：问题列表、涉及文件、建议调整顺序。

如果要允许修改，再明确写：

请更新 docs/start/06-first-task.md 中的下一步链接。
只修改这个文件。
完成后说明改了哪里，不需要运行构建。

第二步：先让 Codex 建图

遇到稍复杂的任务，先让 Codex 只读分析。这样能减少误改。

适合先建图的情况：

• 你不确定相关文件在哪里。
• 任务涉及多个目录。
• 你要重构导航、链接或文档结构。
• 你担心 Codex 改动范围过大。

可以要求它输出：

• 当前结构。
• 关键文件。
• 风险点。
• 建议步骤。
• 需要你确认的决策。

第三步：小步执行

让 Codex 一次只处理一个明确阶段。比如：

1. 先移动文件。
2. 再更新导航。
3. 再修内部链接。
4. 最后跑检查。

小步执行的好处是你能随时看 diff。如果方向不对，也更容易回退。

第四步：检查 diff

Codex 改完后，不要只看总结。要检查 diff。

重点看：

• 有没有改到不相关文件。
• 有没有删掉仍然有价值的内容。
• 链接是否指向新路径。
• 标题层级是否正常。
• 配置文件是否只做了必要改动。
• 文档正文是否超出本轮允许范围。

如果 diff 太大，可以让 Codex 先按文件解释：

请按文件说明这次 diff 的目的。
指出哪些是移动文件，哪些是链接更新，哪些是正文修改。

第五步：运行验证

验证方式取决于任务类型。

任务类型	常见验证
文档链接	搜索旧路径、检查相对链接
前端页面	运行构建、打开页面截图
代码修改	跑单元测试、类型检查、lint
配置修改	查询当前状态、启动一次最小任务
发布任务	检查访问地址、日志、状态码

如果验证失败，不要马上扩大修改范围。先判断失败属于哪类：

• 任务本身造成的错误。
• 环境依赖问题。
• 旧项目已有问题。
• 外部服务或网络问题。

只有第一类才应该继续修本轮改动。

第六步：失败后怎么继续

失败时可以这样处理：

1. 保留当前错误输出。
2. 让 Codex 解释错误来自哪里。
3. 要求它区分“本次改动导致”和“环境已有问题”。
4. 只修与本次目标直接相关的问题。
5. 修完后重新跑最小验证。

可以这样问：

构建失败了。请判断这是本次改动导致，还是环境依赖问题。
不要修改文件，先给出证据和下一步建议。

完成标准

一个任务可以算完成，通常要满足：

• 目标文件已经按要求修改。
• 没有越界改动。
• 关键链接、命令或页面已经验证。
• 如果验证失败，失败原因已经记录清楚。
• 最终总结能说明改动、验证和剩余风险。

Codex 的结果仍然需要人 review。它负责加速执行和整理证据，你负责最终判断是否接受。

下一步

下一步：用手机端 Codex 跟进桌面任务。