02 · 一次任务是怎么完成的

Codex 不是“发一句话然后等代码”的黑盒。一次可靠任务更像一条工程管线：定义目标、收集上下文、制定计划、执行修改、运行验证、交付审查。

如果你只说“做一个小游戏”，它需要猜框架、位置、边界、验收方式。如果你把目标、范围、禁止事项和验证方式写清楚，Codex 才能稳定推进。

任务管线

一次 Codex 任务可以拆成七步：

flowchart TB
    A["1. 接收任务<br/>理解用户目标"]
    B["2. 澄清边界<br/>确认范围和禁止事项"]
    C["3. 收集上下文<br/>读取文件、规则、报错"]
    D["4. 制定计划<br/>列出修改点和验证方式"]
    E["5. 执行修改<br/>改文件或调用工具"]
    F["6. 运行验证<br/>测试、类型检查、构建"]
    G{"验证通过?"}
    H["7. 交付审查<br/>说明 diff、证据、风险"]

    A --> B --> C --> D --> E --> F --> G
    G -->|通过| H
    G -->|失败| C

每一步都有对应风险：

• 接收任务：目标过宽，导致改动失控。
• 澄清边界：你和 Codex 对“完成”的理解不同。
• 收集上下文：读错文件或漏掉项目规则。
• 制定计划：计划跨度太大，不可审查。
• 执行修改：顺手重构或碰到无关文件。
• 运行验证：验证命令和目标不匹配。
• 交付审查：只报喜，不说明未验证和残余风险。

真正的质量控制，不是等 Codex 改完后再看，而是在每个节点提前设置约束。

为什么任务要先变小

新手最适合从小任务开始，因为小任务可以审查。

适合起步的任务：

• 一句话能说清目标。
• 改动范围不超过 1-3 个文件。
• 30 分钟内能验收。
• 有明确测试、截图、类型检查或人工验收标准。

不适合直接交给 Codex 的任务：

• “优化整个项目”。
• “重构所有页面”。
• “升级核心架构”。
• “把全站风格弄高级一点”。

大任务不是不能做，而是要拆成一组小任务，每个小任务都能独立验证。

三个必须写清楚的边界

任务 prompt 至少要包含三类边界。

mindmap
  root((任务边界))
    文件边界
      只改哪些目录
      哪些文件不能碰
    行为边界
      不新增依赖
      不做无关重构
      不改公共 API
    验证边界
      跑哪些命令
      什么算通过
      哪些无法验证要说明

文件边界控制改动范围。行为边界控制实现方式。验证边界控制交付标准。

缺文件边界，Codex 可能扩大修改面。缺行为边界，它可能顺手引入新依赖。缺验证边界，它可能只给“已完成”的文字结论。

计划阶段不是形式

很多人跳过计划，直接让 Codex 写代码。短任务可以这样做，但稍微复杂一点就容易失控。

一个合格计划应该说明：

• 要读哪些文件，为什么相关。
• 准备改哪些文件。
• 不会改哪些文件。
• 预期风险点是什么。
• 改完用什么方式验证。

计划不是为了让回答更长，而是给你一个提前拦截的机会。你可以在它动手前发现范围太大、方向不对、验证不够。

执行阶段要保护工作树

Codex 执行任务时必须尊重当前工作树。

执行前应确认：

• 目标文件是否已经有别人改动。
• 当前 dirty files 中哪些和本任务有关。
• 是否存在未提交生成物、日志、构建产物。
• 是否允许修改共享脚本、配置或索引文件。

如果有多个 agent 同时工作，任务边界要更窄。最稳的方式是每批只处理少量文件，验证后再进入下一批。

验证阶段要和目标对应

验证不是机械跑一个命令。它必须覆盖任务目标。

例子：

• 文档 MDX 改动：至少跑 MDX 类型生成或 types:check。
• 样式改动：需要桌面和移动端截图或视觉检查。
• 逻辑改动：需要相关单元测试、集成测试或可复现步骤。
• 配置改动：需要启动、lint、schema 或 dry-run。

如果验证命令失败，Codex 不能直接“忽略”。它应该说明失败原因、是否由本次改动引入、还缺什么环境或权限。

交付阶段要给证据

完成汇报至少包含：

• 改了哪些文件。
• 每个文件解决了什么问题。
• 跑了哪些验证。
• 哪些没有验证，为什么。
• 还剩哪些风险或后续候选。

这让你能快速判断任务是否真的完成，而不是只看到一段乐观描述。

可直接复用的任务模板

目标：
{具体要完成什么}

范围：
只改 {文件或目录}。
不要碰 {排除范围}。

执行顺序：
先只读分析并列计划；确认后再修改。

约束：
不新增依赖，不做无关重构，不覆盖现有未提交改动。

验证：
改完运行 {命令}。
如果失败，说明失败原因、是否与本次改动相关、替代验证是什么。

交付：
列出修改文件、验证结果、未验证项和残余风险。

Codex 的任务质量，来自目标、边界、上下文和反馈闭环。把这四件事写清楚，它就更像工程协作者，而不是随机代码生成器。