Codex goal模式完整指南：场景配置与实操模板

Codex 的 /goal 功能，最近因为官方修复了订阅用量 bug，才真正开始好用起来。订阅掉得慢了，用起来也可以稍微放开手脚了。

其实，官网对 /goal 的定位非常清晰：

当任务需要 Codex 跨回合持续工作，以达到可验证的停止条件时，请使用 /goal。

并不是所有命令都适合用 /goal。符合的场景主要有三类：长时间运行的编码任务，且具有明确的成功条件与验证循环（比如代码迁移、大型重构、部署重试循环、实验、副项目）；需要反复跑测试或构建的项目；或者团队正在开展有明确成功标准的长期实验。一句话概括：它希望你指定一个最终目标，然后通过具体可验证的方式来确认结果有效，同时保证限制条件不被破坏。

举个例子，如果你想让 Codex 把 React 应用的登录页修好，可以这样用：

## 给定清晰的边界目标
/goal 把这个 React 应用的登录页改成可用状态，修复当前报错，并确保 npm run build 通过。

## 写明验收标准
完成标准：
- 登录表单能提交
- 错误提示正常显示
- 移动端布局不溢出
- npm run lint 和 npm run build 都通过

## 给定条件边界
不要改后端接口；只改 src/app/login 相关文件。

## 给定优先级
优先保证功能可用，其次再美化 UI。

这是你知道目标的情况下。那如果你不知道要做什么呢？/goal 也能应对开放式探索——比如你丢个“克隆百度”，它也会努力往那个方向推进。当然，例子有点极端，但思路是对的。

如果你在 Codex 输入 /goal 看不到斜杠命令，记得在 config.toml 里启用 features.goals：

[features]
goals = true

/goal 的用法比较简单，目前支持三个子命令：

/goal pause   ## 暂停执行目标
/goal resume  ## 恢复暂停目标
/goal clear   ## 清除执行目标

要让它高效工作，需要建立一份工作契约：指定目标和停止条件；告诉它先读哪些文件、文档、issue、日志或计划；定义哪些命令或产物可以证明进展；要求它分 checkpoint 工作，并保留简短进度记录。运行时用 /goal 查看状态，遇到阻塞或方向改变，用 pause、resume、clear 控制它。

一个很现实的建议：不要一个 /goal 命令一路走到黑。之前有人试过执行一个 75 小时的任务，但收益和时间损耗并不成正比。更好的做法是给 Codex 一份紧凑的进度报告，定期更新当前 checkpoint、已验证内容、剩余工作和是否被阻塞。如果状态报告变得含糊，不要一直加零散指令，而是收紧 goal——明确下一个 checkpoint、用哪个命令证明完成、什么情况应该暂停。

/goal 最适合搭配的东西：PRD 与 spec

从实践来看，/goal 最适合搭配一份 PRD 或者 spec。因为它解决的是持续执行的问题，但前提是——它必须知道自己到底在持续执行什么。

如果你只丢一句“根据 PRD 把这个功能做完”，那风险很大。PRD 往往写的是产品意图和用户体验，里面会有大量类似“用户可以更方便”“页面尽量清晰”“后续可以支持某能力”的描述。这些话对人很好理解，但对 Codex 来说，如果没有验收标准，很容易跑偏。

所以，不要直接让 /goal 依照 PRD 开干。更好的做法是让 PRD 和 spec 结合，先输出一份执行蓝图：

/goal 根据 docs/PRD.md 和 docs/SPEC.md 实现 [功能名]。
开始前先阅读这两个文档，并整理出：
1. 必须实现的需求
2. 明确不做的非目标
3. 需要验证的验收标准
4. 可能存在歧义或冲突的地方
5. 建议的 checkpoint 执行顺序
如果 PRD 和 SPEC 有冲突，先暂停并说明，不要自行决定。
每完成一个 checkpoint 后运行对应测试。
只有当所有验收标准满足、构建通过、关键流程验证完成时才停止。

重点是先把大作文拆成 checklist，再开始执行。PRD 和 spec 的分工最好明确：PRD 负责告诉 Codex 为什么做、用户是谁、核心流程是什么、体验上不能偏离什么；spec 负责告诉 Codex 接口怎么设计、数据怎么流转、边界条件有哪些、哪些测试必须通过。/goal 负责把这两份文档变成可持续推进的执行循环。一句话总结：PRD 决定方向，spec 决定边界，/goal 负责推进和验证。

常见的陷阱是：PRD 写得很完整，直接让 /goal 去实现，结果它会把一些 TODO 也当成当前版本需求来做。比如 PRD 里写了一句“后续可以考虑支持多租户配置”，它可能真的就开始设计多租户的数据结构。不算错，但显然不是当前阶段该做的事。所以在 goal 里加一句非常重要的话：

PRD 中间出现的「后续」「未来」「可以考虑」「可扩展」内容，默认都视为非目标，除非 SPEC 或完成标准明确要求实现。

这个小限制非常有用，能显著减少过度发挥。如果手上只有 PRD 没有 spec，建议先让 Codex 生成一份轻量 spec：

阅读 docs/PRD.md，先不要写代码。请把它整理成一份 implementation spec，包含：
- 当前版本必须实现的功能
- 不做的非目标
- 数据结构和状态流转
- UI 页面和关键交互
- 验收标准
- 测试建议
- 需要我确认的问题

等这份 spec 确认之后，再开 /goal。这样会比边读 PRD 边写代码稳定很多。

一个完整模板，以及拆分的艺术

如果已有 PRD 和 spec，使用以下模板较为稳妥：

/goal 按照 docs/PRD.md 和 docs/SPEC.md 完成 [功能名] 的第一版实现。

执行规则：
- PRD 是产品目标和用户流程的来源
- SPEC 是技术实现和接口契约的来源
- 如果两者冲突，以 SPEC 为准，但必须在进度报告中说明
- PRD 中的未来规划默认不实现
- 不要修改与本功能无关的模块

工作方式：
- 先整理需求 checklist 和 checkpoint
- 每个 checkpoint 完成后运行相关测试
- 如果涉及页面，使用浏览器验证主要流程
- 如果构建或测试失败，优先修复失败项

完成标准：
- PRD 中当前版本核心流程全部可用
- SPEC 中定义的接口、状态、边界条件全部满足
- npm run test 通过
- npm run build 通过
- 关键页面或流程完成实际验证

停止条件：
- 所有完成标准满足后停止
- 遇到产品判断、文档冲突或需要扩大范围时暂停并说明

这个模板把能改什么、做到什么程度、什么时候停、遇到冲突怎么办都提前说清楚了。普通对话里，Codex 是你问一轮它做一步；而 /goal 更像是你给它一张施工图，再告诉它验收方式，它自己按阶段往前推。

有一个非常现实的建议：不要让一个 /goal 承包整个巨大 PRD。 如果 PRD 里包含用户系统、支付系统、后台管理、消息通知、数据看板，最好不要写“根据 PRD 完成整个系统”。那样容易变成超长时间任务，后面状态越来越难判断。更好的方式是把 PRD 拆成多个 goal：

• /goal 按 PRD 和 SPEC 完成登录注册模块，完成后通过认证相关测试和页面验证。
• /goal 按 PRD 和 SPEC 完成订单创建流程，暂不处理支付回调。
• /goal 按 PRD 和 SPEC 完成支付回调和订单状态流转，确保相关测试通过。

这样每一个 goal 都有清晰边界，也方便随时 pause、resume、clear。

判断标准其实很简单：如果一个任务可以用一句话说完，十分钟内能完成，没必要开 /goal。如果一个任务需要反复读文档、改代码、跑测试、看页面、修失败项，非常适合 /goal。如果还有 PRD 和 spec，那就更合适了——这时候 /goal 不是在帮你猜需求，而是在帮你执行已经定义好的需求。这才是它真正好用的地方。