验收标准：让 Codex 和你都对"完成"有共识
为什么验收标准是最被低估的提示词部分？
大多数人在写提示词时，80% 的精力花在"要做什么"上，几乎不花时间定义"做完是什么样"。结果就是——Codex 做了一堆东西，你花了半小时审查，发现方向跑偏了。
| 维度 | 没有验收标准 | 有验收标准 |
|---|---|---|
| Codex 判断完成的依据 | "看起来差不多了" | 具体的命令输出、行为表现 |
| 你需要审查的工作量 | 全量审查每一行改动 | 重点审查验收标准之外是否有多余改动 |
| 返工概率 | 高——Codex 可能理解错了"好" | 低——Codex 可以自检 |
| Goal mode 效果 | 无法使用 | 验收标准直接变成 Goal 的成功条件 |
关键洞察：验收标准让 Codex 从"做完了"变成"做对了"。 没有验收标准，Codex 只能赌它理解的和你想的一致。
三种验收标准类型
| 类型 | 适用场景 | 写法要点 | Codex 自检能力 |
|---|---|---|---|
| 命令验证型 | 测试、lint、build、类型检查 | 写出具体的命令和期望输出 | ✅ 完全自检 |
| 行为验证型 | 功能行为、交互、边界条件 | 描述可观测的行为和条件 | 🔶 部分自检 + 人工确认 |
| 人工审查型 | 视觉设计、架构决策、产品判断 | 描述 Codex 需要提供的依据 | ❌ Codex 提供依据，人工判断 |
命令验证型
Codex 可以直接运行命令来判断是否完成。这是最高效的验收标准类型。
验证：
- `pnpm test -- --filter=auth` 全部通过
- `pnpm typecheck` 无错误
- `pnpm lint` 无新增 warning
优先使用命令验证。 如果任务可以用命令验证，就不要用行为描述。命令输出是二值的（通过/失败），没有歧义。
行为验证型
描述 Codex 改完之后，在什么条件下应该观察到什么行为。
验证：
- 用户在设置页切换通知开关后，页面立即反映新状态，无需刷新
- 开关状态在刷新页面后保持（持久化到 localStorage）
- 网络请求失败时，开关回滚到切换前的状态，并显示 toast 提示
Codex 可以分析代码逻辑来判断是否满足行为描述，但最终确认通常需要人工在浏览器中验证。
人工审查型
涉及主观判断或需要人类感知的验收标准。
验证：
- 在 375px / 768px / 1440px 三个断点截图，与设计稿对比（需人工确认）
- 代码注释风格与现有代码一致（需人工抽查）
- API 错误消息对用户友好，不暴露技术细节（需产品确认）
对于这类标准，提示词中应该告诉 Codex 提供什么依据来辅助你的判断，比如截图、diff、对比表。
验收标准的层次结构
一个复杂任务的验收标准可以分层，帮助 Codex 区分优先级：
| 层次 | 含义 | 失败时的行为 |
|---|---|---|
| 必须通过（Blocker） | 不通过就不能算完成 | Codex 应该继续修复，不能停下来 |
| 建议检查（Recommended） | 应该通过，除非有合理理由 | Codex 尝试修复，但可以和用户确认是否接受 |
| 可选验证（Optional） | 锦上添花 | Codex 在有余力时执行 |
完整示例：
验证：
【必须通过】
- `pnpm test` 全部通过
- 新增的 NotificationPreferences 组件有完整的类型定义
- 表单提交后发送正确的 API 请求
【建议检查】
- 在移动端（375px）布局不出现横向滚动
- 开关切换有过渡动画，不突兀
【可选】
- 补一个 E2E 测试覆盖完整的开关切换流程
从模糊到清晰的改写练习
| 模糊描述 ❌ | 清晰验收标准 ✅ |
|---|---|
| "代码要写好" | pnpm test 全部通过 + 新增测试覆盖边界 X |
| "页面要好看" | 在 375px / 768px / 1440px 三个断点截图，无布局溢出 |
| "性能要好" | LCP < 2.5s，CLS < 0.1（用 web-vitals 测量） |
| "重构一下这个模块" | 现有 12 个测试全部通过 + 模块行数从 800 降到 500 以下 + 公共 API 不变 |
| "写个文档" | 新手读完能在 5 分钟内完成首次运行，无步骤缺失 |
改写原则：如果 Codex 无法执行或观测，就不算验收标准。 "写好"、"好看"、"好用"都是主观感受，不是验收标准。
验收标准与 Goal mode 的配合
Goal mode 的成功条件本质上就是验收标准。参见 Codex 提示词 | 线程与上下文 中 Goal mode 部分的说明。
最佳实践——把验收标准直接写入 Goal：
/goal 将用户设置页的通知偏好从全局开关改为按类型独立配置。
完成标准：
1. NotificationPreferences 组件支持 email / push / inApp 三种通知的独立开关
2. `pnpm test -- --filter=settings` 全部通过
3. 375px / 768px / 1440px 三个断点无布局问题
4. 开关状态持久化，刷新页面后保持
Goal 本身就是最大的验收标准。写 Goal 时，先想清楚"我怎么判断这个目标达成了"，然后把判断条件写进去。Codex 会用这些条件来指导自己的执行路径。
反模式与常见错误
| 反模式 | 问题 | 改进 |
|---|---|---|
| 不可执行的验证 | "代码质量要高"——Codex 不知道"高"是什么 | 改成可量化指标或可执行命令 |
| 过于宽泛 | "所有测试通过"——但如果根本没有测试呢？ | 先让 Codex 写测试，再要求通过 |
| 只有人工能判断 | "确保设计美观"——Codex 无法判断 | 改成"截图 + 与设计稿对比"，Codex 提供截图 |
| 验证与目标不一致 | 目标说"提升性能"，验证却只检查"测试通过" | 验证必须直接对应目标的可观测结果 |
如果 Codex 无法验证，它就只能赌。 与其给一个 Codex 无法自检的验收标准，不如把它拆成两步：第一步让 Codex 产出判断依据（截图、数据、diff），第二步你自己看依据做判断。
验证清单
- 每条验收标准都是可执行或可观测的
- 必须通过的标准放在最前面
- 验收标准直接对应任务目标（不是无关的检查项）
- 至少有一条命令验证型标准（如果项目有测试/lint）
- Goal mode 的成功条件包含了关键验收标准
FAQ
Q：验收标准写在提示词的哪个位置？
放在任务描述的最后部分，单独用"验证"或"完成标准"标题标记。Codex 会在执行完成后自动对照检查。如果是 Goal mode，验收标准直接写在 Goal 文本里。
Q：验收标准要写多少条？
通常 3-5 条核心标准就够了。太少（1 条）容易遗漏关键检查，太多（10+）会让 Codex 的自检流程变慢。把最重要的放在前面。
Q：Codex 说自己通过了所有验收标准，但实际没有怎么办？
这说明验收标准写得不够精确——Codex 按字面理解"通过了"，但你的真实意图没被覆盖。改进方法：把模糊的行为描述改成具体的命令输出，或在验收标准中增加"反例"（什么情况下不算通过）。
平台能力、套餐限制以 OpenAI Codex 官方文档为准；本文写于 2026-06-24。
选读建议：验收标准写好了，单轮任务就可以稳定交付。如果你的任务需要多轮迭代——→ 多轮协作技巧。如果想直接看模板在真实场景中的完整用法——→ 提示词实战案例库。