从“帮我优化一下”到稳定交付：Codex 任务设计、执行与验收闭环

很多人第一次使用 Codex 时，会下意识地把它当成一个“更聪明的代码补全工具”：

帮我优化一下登录逻辑。

这句话看起来没问题，但真正执行时，Codex 会立刻遇到一连串没有答案的问题：

“优化”是修 Bug、提性能，还是重构代码？
登录逻辑具体哪里有问题？
可以修改数据库和后端接口吗？
能不能引入新的依赖？
修改到什么程度才算完成？

如果这些信息没有写清楚，Codex 只能依靠代码上下文进行推测。结果往往是：它确实改了代码，却没有解决你真正关心的问题；或者为了完成一个小需求，顺手改动了一大片文件。

所以，影响 Codex 工作质量的，不只是模型能力，还有两件经常被忽略的事：开始前有没有做好任务设计，执行后有没有完成验证与验收。

任务写清楚，只是让 Codex 走上正确的路；检查改动、运行验证、处理失败和记录结果，才决定这项工作能不能真正交付。

好任务不是一句提示词，而是一份微型需求说明

所谓任务设计，就是在 Codex 开始工作前，明确告诉它：

最终要得到什么结果；
为什么要做这件事；
可以修改哪些地方；
哪些边界不能突破；
应该如何证明任务完成；
最后需要怎样汇报。

这六项分别对应：目标、背景、范围、约束、验证和交付。

要素	要回答的问题	示例
目标	最终要解决什么问题？	修复登录页刷新后状态丢失
背景	当前发生了什么？	用户登录后刷新页面会回到未登录状态
范围	允许检查和修改哪里？	只修改 `auth` 模块和相关测试
约束	哪些事情不能做？	不改数据库，不调整后端接口，不引入新依赖
验证	如何证明已经完成？	运行 `pnpm test auth`，覆盖刷新恢复场景
交付	最后需要汇报什么？	说明根因、改动、测试结果和剩余风险

它们不是什么复杂的“提示词技巧”，而是软件开发里原本就需要讲清楚的协作信息。区别只是：以前这些信息写给同事，现在也需要写给 Codex。

把一句模糊要求，改成一个可执行任务

假设你遇到的问题是：用户已经登录，但刷新页面后登录状态消失。

模糊的任务可能只有一句：

帮我优化登录逻辑。

更可靠的写法是：

请修复登录页刷新后状态丢失的问题。

背景：
- 用户登录后刷新页面，会回到未登录状态。
- 期望刷新后仍能恢复已登录状态。

范围：
- 优先检查 src/auth 和相关测试。
- 只修改与登录状态恢复直接相关的代码。

约束：
- 不修改数据库 schema。
- 不调整现有后端接口。
- 不引入新的依赖。

验证：
- 运行 pnpm test auth。
- 如果缺少测试，请补充“刷新后恢复登录状态”的场景。

交付：
- 说明问题根因。
- 列出修改的文件。
- 汇报测试结果和剩余风险。

这两个任务的字数差距并不大，但执行质量会完全不同。

第一种写法把判断题全部留给 Codex；第二种写法则建立了一条清晰的工作路径：先定位状态为何丢失，再在限定范围内修复，最后用测试证明结果。

六个要素分别解决什么问题

1. 目标：避免做了很多，却没有解决核心问题

目标应该描述结果，而不是只描述动作。

“优化登录逻辑”是动作；“修复刷新后登录状态丢失”才是结果。

目标越具体，Codex 越容易判断哪些改动有价值，哪些只是无关重构。

2. 背景：让代码和真实现象连接起来

仅靠阅读代码，Codex 未必知道用户遇到了什么。背景可以包含：

实际表现和期望表现；
报错信息；
复现步骤；
相关截图或日志；
最近发生过的改动。

背景不是越长越好，而是要提供足以解释“为什么这是一个问题”的信息。

3. 范围：控制影响面

范围用于回答“这次可以碰哪里”。

你可以限定目录、模块、文件，也可以先让 Codex 自己找影响面，再确认实施范围。对于遗留项目、支付系统和跨模块功能，范围尤其重要，它可以显著降低误改概率。

4. 约束：提前写清红线

很多返工并不是因为代码写错，而是因为解决方式不符合预期。

例如，你只想修一个前端状态问题，Codex 却建议新增数据库字段；你只想做小范围修复，它却引入了新的状态管理框架。

“不改数据库”“不增加依赖”“不改变公开 API”这类约束，可以让方案从一开始就在正确边界内。

5. 验证：把“看起来完成”变成“有证据完成”

没有验证标准，Codex 很容易把“代码已经修改”当成“任务已经完成”。

验证可以是一条测试命令，也可以是：

构建成功；
类型检查通过；
指定接口返回预期状态；
页面在桌面端和移动端正常显示；
搜索不到旧路径或废弃配置；
新增测试覆盖了原来的失败场景。

最好的验证方式，是能直接对应任务目标。

6. 交付：让结果可以被快速审查

任务完成后，不要只让 Codex 回复“已修复”。可以要求它说明：

根因是什么；
修改了哪些文件；
每项改动解决什么问题；
运行了哪些验证；
还有哪些没有验证或存在风险。

这样你不需要重新翻遍全部代码，也能快速判断结果是否值得接受。

大任务不要直接开改，先拆成三个阶段

任务越大，越不适合用一句话让 Codex 从分析直接冲到实现。

更稳妥的方式是拆成三个阶段。

第一阶段：只读分析

先不允许修改代码，让 Codex 找出：

相关入口和依赖；
可能受到影响的文件；
已有测试和缺失测试；
技术风险和不确定性。

第二阶段：确认方案

让 Codex 把工作拆成几个可独立验证的步骤，并说明每一步的修改范围和验证方法。

这时你仍然可以调整方向，而不需要回退已经写入的代码。

第三阶段：分步实施

每次只执行一个明确阶段，例如：

先补失败测试；
再修复核心逻辑；
然后处理边界情况；
最后运行完整验证。

每一步都能检查、能解释、能回退，大任务就不容易失控。

可以直接使用下面这段分析模板：

请先不要修改代码。

阅读 [模块或目录]，分析 [任务目标] 会影响哪些文件、接口和测试。

请输出：
1. 当前实现和可能的根因；
2. 影响范围；
3. 推荐实施步骤；
4. 每一步的验证方式；
5. 第一阶段最小改动建议。

要求 Codex 主动暴露不确定性

AI 很容易在信息不足时给出一个“听起来合理”的答案。对于版本升级、依赖迁移、安全配置和跨模块修改，这种推测尤其危险。

可以在任务末尾增加一句：

如果需要推测，请明确标注“推测”。
如果官方文档、代码和测试之间存在冲突，请先停下来说明冲突，不要自行选择一种解释继续修改。

这句话的价值在于，它把“不确定性”从隐藏状态变成了可以讨论的工作项。

从任务设计到验收：建立六步执行闭环

把任务交给 Codex 后，不能只等它回复一句“已经完成”。一个稳定的执行过程通常包含六步：

说明目标 → 只读建图 → 小步执行 → 检查 diff → 运行验证 → 记录结果

这六步形成了一个闭环：任务说明定义方向，建图和小步执行控制过程，diff 和验证提供证据，最终记录让结果能够被审查和复用。

第一步：用任务说明建立共同标准

前面提到的目标、背景、范围、约束、验证和交付，不只是为了让 Codex 理解需求，也是在提前定义验收标准。

如果任务目标是“修复刷新后登录状态丢失”，那么最终验收就应该回到这件事：刷新页面后，登录状态是否真的恢复，而不是只看某个文件是否发生了改动。

第二步：复杂任务先只读建图

当任务涉及多个目录、陌生项目、导航重构、依赖升级或安全敏感模块时，先让 Codex 只读分析。

建图阶段至少应该输出：

当前实现和关键入口；
可能受到影响的文件与接口；
已有测试和缺失测试；
风险点与不确定性；
推荐步骤以及需要你确认的决策。

如果连影响面都没有弄清楚，就直接开始改代码，后面检查的成本通常会更高。

第三步：把实现拆成可验证的小步骤

不要让 Codex 一次完成“重构模块、迁移数据、修改接口、更新页面和发布上线”。

更可靠的节奏是：

先建立能够复现问题的测试；
再完成最小修复；
然后处理边界场景；
最后运行完整检查。

每完成一步，都应该能看到明确的改动和验证结果。如果方向有问题，也只需要回退当前阶段。

第四步：不要只看总结，要检查 diff

Codex 的总结只能帮助你理解它声称做了什么，diff 才是它实际做了什么。

检查时重点关注：

有没有修改任务范围之外的文件；
有没有删除仍然有价值的逻辑或内容；
是否出现了不必要的依赖和抽象；
配置、接口和数据结构是否发生意外变化；
新增测试是否真的覆盖了原问题；
文档链接、文件路径和命名是否保持一致。

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

请按文件说明本次 diff 的目的。
区分核心修复、测试补充、配置调整和无关格式变化。
如果存在超出原任务范围的改动，请单独列出。

第五步：运行与目标匹配的验证

不同任务需要不同的证据。

任务类型	常见验证方式
文档和链接	搜索旧路径、检查相对链接、构建文档站
前端页面	构建、浏览器预览、桌面与移动端截图
代码修改	单元测试、类型检查、lint、相关集成测试
API 修改	请求成功与失败分支、状态码、响应结构
配置修改	读取生效配置、运行最小任务、检查回滚路径
发布任务	访问生产地址、检查日志、状态码与关键功能

验证不是运行的命令越多越好，而是要能回答：最初的问题是否被解决，同时有没有引入新的问题？

第六步：验证失败时先归因，再决定是否继续修改

构建或测试失败，并不一定说明本次修改有问题。失败通常可以分为四类：

本次改动造成的错误；
环境或依赖没有准备好；
项目原本就存在的问题；
外部服务、权限或网络异常。

只有确认是第一类问题，才应该继续修改当前代码。否则，Codex 可能为了“让命令变绿”而扩大改动范围，最终掩盖真正原因。

失败时可以这样要求：

验证失败了。请先不要修改文件。

请根据错误输出判断：
1. 是否由本次改动引起；
2. 有哪些直接证据；
3. 属于代码、环境、旧问题还是外部服务；
4. 下一步最小处理方式是什么。

处理失败的正确顺序是：保留错误输出、判断来源、只修相关问题，然后重新运行最小验证。

什么情况下才算真正完成

“代码写完了”不等于“任务完成了”。一项 Codex 任务至少应该满足：

目标问题已经解决；
修改没有超出约定范围；
diff 已经过人工检查；
相关测试、构建或页面已经验证；
失败项已经说明原因，而不是被忽略；
最终总结列出了改动、证据和剩余风险。

Codex 可以负责分析、执行和整理证据，但是否接受结果，仍然需要人做最终判断。

一份可以直接复制的完整任务模板

请完成：[一句话目标]

背景：
- [当前现象]
- [预期结果]
- [报错、日志或复现步骤]

范围：
- 优先检查：[目录、模块或文件]
- 允许修改：[明确范围]

约束：
- 不修改：[禁止修改的内容]
- 不引入：[禁止新增的依赖或架构]
- 保持兼容：[需要保留的接口或行为]

验证：
- 运行：[测试、构建或检查命令]
- 补充覆盖：[需要新增的测试场景]

执行方式：
- 如果任务涉及多个模块，请先只读分析，不要立即修改。
- 先输出影响范围、实施步骤和每一步的验证方式。
- 每次只完成一个可验证阶段。
- 修改后按文件检查 diff，并说明是否存在范围外改动。
- 如果验证失败，先判断失败来源，不要为了让命令通过而扩大修改范围。

交付：
- 说明根因；
- 列出改动文件和目的；
- 汇报验证结果；
- 标注未验证内容与剩余风险。

如果需要推测，请明确标注“推测”。
如果信息不足或不同来源存在冲突，请先说明，不要直接修改。

发送任务前和验收时，各检查一遍

发送任务前，可以快速问自己：

我有没有说清最终结果？
Codex 是否知道问题背景？
修改范围是否明确？
有没有不能突破的边界？
完成后应该运行什么验证？
我希望它最后怎样汇报？

Codex 回复完成后，再检查：

实际 diff 是否符合任务说明？
是否改到了无关文件？
验证命令是否真的运行成功？
验证是否覆盖最初的问题？
失败和未验证内容是否如实记录？
是否还有需要人工确认的风险？

前一组问题保证任务能够正确开始，后一组问题保证结果能够可靠结束。

写在最后

使用 Codex 的关键，并不是把一句话写得像咒语，而是把真实需求变成一个可以设计、执行、验证和审查的任务。

任务设计解决的是“往哪里走”，执行与验收闭环解决的是“怎么确认真的走到了”。缺少前者，Codex 容易理解错方向；缺少后者，你只能得到一个看起来完成、却缺乏证据的结果。

下一次遇到问题时，不妨先别急着说“帮我优化一下”。花一分钟补齐目标、背景、范围、约束、验证和交付，再沿着“建图、实施、检查、验证、记录”的路径完成闭环，往往比事后花半小时纠正方向更划算。