codex-goals

OpenAI Codex Goals 最佳实践

编写和管理 Codex Goals 的参考指南——Goals 是 Codex 0.128.0 引入的持久目标功能。此处的“最佳实践”指决定 Goal 能否依据正确证据完成，而不是在错误的验证面上悄然完成的模式和反模式。共包含 8 个类别中的 31 条规则，按其对 Goal 能否正确完成的影响程度排序。内容源自 OpenAI 官方 cookbook 文章 "Using Goals in Codex"。

适用场景

在以下情况下，请参考这些指南：

• 判断某项任务是否适合使用 /goal，还是普通提示词
• 起草或完善 /goal 调用
• 激活他人编写的 Goal 前对其进行审核
• 排查 Goal 针对错误验证面完成的问题
• 设置无法获得确切证明的研究 Goal
• 跨线程会话管理 Goal 生命周期（暂停、恢复、清除）
• 为长时间运行的 Goal 编写迭代策略或阻塞时的停止条件
• 诊断 Goal 达到预算上限但尚未完成的问题

按优先级划分的规则类别

优先级	类别	影响（最严重规则）	前缀
1	Goal 适用性判断	CRITICAL	fit-
2	结果定义	CRITICAL / HIGH	outcome-
3	验证面	CRITICAL / HIGH	verify-
4	边界与迭代	HIGH	bound-
5	生命周期命令	HIGH	life-
6	基于证据的完成判定	HIGH	evidence-
7	编写有力的 Goal	MEDIUM	craft-
8	研究 Goal 与反模式	MEDIUM	research-

各条规则的影响程度列在每条规则的 frontmatter 中。

快速参考

1. Goal 适用性判断（CRITICAL）

• fit-when-to-use — 终点明确但路径不确定时使用 Goal
• fit-three-required-properties — 设置 Goal 前要求具备三个属性：持久目标、证据终点和多轮路径
• fit-prompt-vs-goal — 单轮任务使用提示词，结果驱动的持续任务使用 Goal
• fit-skip-for-vague-targets — 终点模糊时不要使用 Goal

2. 结果定义（CRITICAL）

• outcome-measurable-end-state — 将结果表述为可衡量的最终状态，而非活动
• outcome-quantify-thresholds — 用数字明确阈值，不要使用相对比较
• outcome-narrow-but-discoverable — 让结果范围足够窄以便审核，同时足够宽以允许探索
• outcome-name-the-artifact — 生成产物时，明确产物名称及其有效性条件

3. 验证面（CRITICAL）

• verify-name-the-surface — 始终在 Goal 中明确指定验证面
• verify-include-constraints — 除主要指标外，还要列出不得退化的约束
• verify-multiple-checks-when-needed — 单项检查不足时，使用多个验证面
• verify-surface-must-be-runnable — 验证面必须是 Codex 实际能够运行或检查的对象

4. 边界与迭代（HIGH）

• bound-tools-and-files — 限定 Codex 可使用的文件、工具和代码仓库
• bound-iteration-policy — 定义迭代策略——Codex 如何在不同轮次之间选择下一个实验
• bound-blocked-stop-condition — 定义受阻停止条件——没有可行路径时应报告什么
• bound-respect-budget — 将预算上限视为停止并总结，而不是延长预算

5. 生命周期命令（HIGH）

• life-set-with-slash-goal — 使用 /goal <text> 设置目标——Codex 0.128.0 起可用
• life-pause-during-detours — 转向无关任务前暂停目标，返回时恢复
• life-clear-stale-goals — 恢复线程时清除过时目标
• life-inspect-with-slash-goal — 使用不带参数的 /goal，在继续之前检查当前目标和状态

6. 基于证据的完成判定（HIGH）

• evidence-audit-before-completion — 将目标与具体证据进行核对，再标记为已完成
• evidence-budget-is-not-completion — 达到预算上限并不等于完成目标
• evidence-honest-blockers — 明确说明阻碍因素——绝不要用替代指标冒充所要求的结论

7. 制定有力的目标（MEDIUM）

• craft-six-components — 在每个有力的目标中定义六个要素——结果、验证方式、约束、边界、迭代策略和受阻停止条件
• craft-template-pattern — 使用规范模式：“通过……验证，同时保留……。使用……。在迭代之间……。如果受阻……”
• craft-let-codex-draft-it — 请 Codex 根据自然语言描述起草目标，然后再加以完善
• craft-strengthen-weak-goals — 明确终态、验证范围和约束，增强薄弱的目标

8. 研究目标与反模式（MEDIUM）

• research-define-evidence-standard-first — 对于研究目标，应在开始调查前定义证据标准
• research-build-claim-inventory — 将研究目标拆解为主张清单，并映射到证据渠道
• research-preserve-epistemic-ledger — 最终报告必须保留各项主张的认知层级——使用结构化台账条目
• research-anti-patterns — 避免三种常见的目标反模式——一味坚持、隐藏不确定性、依据替代指标过度声称

如何使用

阅读各个参考文件，查看详细说明和对比薄弱与有力目标文本的示例：

• 章节定义 — 类别结构和影响级别
• 规则模板 — 添加新规则的模板

每个规则文件都包含：

• 2–4 句说明，解释该规则为何重要
• 一个薄弱目标或反模式的“不正确”示例
• 一个展示如何加强目标的“正确”示例
• 指向其所依据的手册章节的引用

参考文件

文件	描述
AGENTS.md	由 build-agents-md.js 构建的汇总目录
references/_sections.md	分类定义和影响排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息
gotchas.md	使用过程中发现的易错点