codex-goals

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenAI Codex Goals Best Practices

OpenAI Codex Goals最佳实践

Reference for writing and managing Codex Goals — the persistent objective feature introduced in Codex 0.128.0. "Best practices" here means the patterns and anti-patterns that determine whether a Goal completes against the right evidence vs. silently against the wrong surface. Contains 31 rules across 8 categories, ordered by how much they affect whether a Goal completes correctly. Derived from the official OpenAI cookbook article "Using Goals in Codex".

本指南是关于编写与管理Codex Goals的参考资料——Codex 0.128.0版本引入的持久目标功能。这里的“最佳实践”指的是决定Goal是否基于正确证据完成，而非悄无声息地在错误场景下完成的模式与反模式。指南包含8大类共31条规则，按对Goal正确完成的影响程度排序，内容源自OpenAI官方烹饪书文章《Using Goals in Codex》（https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex）。

When to Apply

适用场景

Reference these guidelines when:

Deciding whether a task warrants a
```
/goal
```
or a normal prompt
Drafting or strengthening a
```
/goal
```
invocation
Reviewing a Goal someone else wrote before activating it
Debugging a Goal that completed against the wrong verification surface
Setting up a research Goal where exact proof may not be available
Managing Goal lifecycle (pause, resume, clear) across thread sessions
Writing the iteration policy or blocked stop condition for a long-running Goal
Diagnosing a Goal that hit its budget without completing

在以下场景中参考本指南：

判断某一任务适合使用
```
/goal
```
还是普通提示词
起草或优化
```
/goal
```
调用指令
在激活他人编写的Goal前进行审查
调试未按正确验证场景完成的Goal
设置可能无法获取精确证明的研究类Goal
在会话线程中管理Goal生命周期（暂停、恢复、清除）
为长期运行的Goal编写迭代政策或阻塞停止条件
诊断已达预算但未完成的Goal

Rule Categories by Priority

按优先级划分的规则类别


fit-
outcome-
verify-
bound-
life-
evidence-
craft-
research-

Priority	Category	Impact (worst rule)	Prefix
1	Goal Fit Decisions	CRITICAL	`fit-`
2	Outcome Definition	CRITICAL / HIGH	`outcome-`
3	Verification Surface	CRITICAL / HIGH	`verify-`
4	Boundaries & Iteration	HIGH	`bound-`
5	Lifecycle Commands	HIGH	`life-`
6	Evidence-Based Completion	HIGH	`evidence-`
7	Crafting Strong Goals	MEDIUM	`craft-`
8	Research Goals & Anti-Patterns	MEDIUM	`research-`

Individual rule impacts are listed inline in the per-rule frontmatter.


fit-
outcome-
verify-
bound-
life-
evidence-
craft-
research-

优先级	类别	影响程度（最糟规则）	前缀
1	Goal适配决策	关键	`fit-`
2	结果定义	关键/高	`outcome-`
3	验证场景	关键/高	`verify-`
4	边界与迭代	高	`bound-`
5	生命周期命令	高	`life-`
6	基于证据的完成	高	`evidence-`
7	构建优质Goal	中	`craft-`
8	研究类Goal与反模式	中	`research-`

每条规则的具体影响程度会在规则前置内容中列出。

Quick Reference

快速参考

1. Goal Fit Decisions (CRITICAL)

1. Goal适配决策（关键）

```
fit-when-to-use
```
— Use a Goal When the Finish Line Is Clear but the Path Is Uncertain
```
fit-three-required-properties
```
— Require Three Properties Before Setting a Goal — Durable Objective, Evidence Finish Line, Multi-Turn Path
```
fit-prompt-vs-goal
```
— Choose a Prompt for Single-Turn Work, a Goal for Outcome-Driven Continuation
```
fit-skip-for-vague-targets
```
— Skip a Goal When the Finish Line Is Vague

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

2. Outcome Definition (CRITICAL)

2. 结果定义（关键）

```
outcome-measurable-end-state
```
— State the Outcome as a Measurable End State, Not an Activity
```
outcome-quantify-thresholds
```
— Pin Thresholds with Numbers, Not Relative Comparatives
```
outcome-narrow-but-discoverable
```
— Make the Outcome Narrow Enough to Audit, Broad Enough to Allow Discovery
```
outcome-name-the-artifact
```
— For Generated Artifacts, Name the Artifact and Its Validity Conditions

```
outcome-measurable-end-state
```
— 将结果表述为可衡量的最终状态，而非活动过程
```
outcome-quantify-thresholds
```
— 用数字明确阈值，而非相对比较词
```
outcome-narrow-but-discoverable
```
— 结果范围需窄到可审计，同时宽到允许探索
```
outcome-name-the-artifact
```
— 对于生成的产物，明确产物名称及其有效性条件

3. Verification Surface (CRITICAL)

3. 验证场景（关键）

```
verify-name-the-surface
```
— Always Name the Verification Surface Inside the Goal
```
verify-include-constraints
```
— Include Constraints That Must Not Regress Alongside the Primary Metric
```
verify-multiple-checks-when-needed
```
— Use Multiple Verification Surfaces When a Single Check Is Insufficient
```
verify-surface-must-be-runnable
```
— The Verification Surface Must Be Something Codex Can Actually Run or Inspect

```
verify-name-the-surface
```
— 务必在Goal内指定验证场景
```
verify-include-constraints
```
— 除主要指标外，需包含不得倒退的约束条件
```
verify-multiple-checks-when-needed
```
— 当单一检查不足时，使用多个验证场景
```
verify-surface-must-be-runnable
```
— 验证场景必须是Codex实际可运行或检查的内容

4. Boundaries & Iteration (HIGH)

4. 边界与迭代（高）

```
bound-tools-and-files
```
— Bound the Files, Tools, and Repositories Codex May Use
```
bound-iteration-policy
```
— Define an Iteration Policy — How Codex Chooses the Next Experiment Between Turns
```
bound-blocked-stop-condition
```
— Define a Blocked Stop Condition — What to Report When No Defensible Path Remains
```
bound-respect-budget
```
— Treat the Budget Limit as Halt-and-Summarize, Not Extend

```
bound-tools-and-files
```
— 限制Codex可使用的文件、工具与仓库
```
bound-iteration-policy
```
— 定义迭代政策——Codex在轮次间如何选择下一个实验方向
```
bound-blocked-stop-condition
```
— 定义阻塞停止条件——当无可行路径时需报告的内容
```
bound-respect-budget
```
— 将预算上限视为停止并总结的信号，而非延长预算

5. Lifecycle Commands (HIGH)

5. 生命周期命令（高）

```
life-set-with-slash-goal
```
— Set a Goal with
```
/goal <text>
```
— Available from Codex 0.128.0
```
life-pause-during-detours
```
— Pause the Goal Before Unrelated Detours, Resume When Returning
```
life-clear-stale-goals
```
— Clear Stale Goals on Resumed Threads
```
life-inspect-with-slash-goal
```
— Use Bare
```
/goal
```
to Inspect Current Objective and State Before Continuation

```
life-set-with-slash-goal
```
— 使用
```
/goal <文本>
```
设置Goal——Codex 0.128.0版本起可用
```
life-pause-during-detours
```
— 在进行无关分支任务前暂停Goal，返回时恢复
```
life-clear-stale-goals
```
— 在恢复的线程中清除过期Goal
```
life-inspect-with-slash-goal
```
— 在继续任务前，使用纯
```
/goal
```
命令查看当前目标与状态

6. Evidence-Based Completion (HIGH)

6. 基于证据的完成（高）

```
evidence-audit-before-completion
```
— Audit the Objective Against Concrete Evidence Before Marking a Goal Complete
```
evidence-budget-is-not-completion
```
— Reaching the Budget Limit Is Not the Same as Completing the Objective
```
evidence-honest-blockers
```
— Surface Blockers Explicitly — Never Substitute a Proxy for the Asked Claim

```
evidence-audit-before-completion
```
— 在标记Goal完成前，对照具体证据审核目标
```
evidence-budget-is-not-completion
```
— 达到预算上限不等于完成目标
```
evidence-honest-blockers
```
— 明确指出阻塞因素——绝不能用替代指标代替要求的结果

7. Crafting Strong Goals (MEDIUM)

7. 构建优质Goal（中）

```
craft-six-components
```
— Define Six Components in Every Strong Goal — Outcome, Verification, Constraints, Boundaries, Iteration Policy, Blocked Stop
```
craft-template-pattern
```
— Use the Canonical "verified by … while preserving … Use … Between iterations … If blocked …" Pattern
```
craft-let-codex-draft-it
```
— Ask Codex to Draft the Goal from a Plain-Language Description, Then Tighten
```
craft-strengthen-weak-goals
```
— Strengthen a Weak Goal by Naming the End State, Verification Surface, and Constraints

```
craft-six-components
```
— 每个优质Goal需定义六个组件：结果、验证、约束、边界、迭代政策、阻塞停止条件
```
craft-template-pattern
```
— 使用标准模式：“经……验证，同时保留……使用……在迭代之间……若阻塞……”
```
craft-let-codex-draft-it
```
— 先让Codex根据自然语言描述起草Goal，再进行优化
```
craft-strengthen-weak-goals
```
— 通过明确最终状态、验证场景与约束条件来优化劣质Goal

8. Research Goals & Anti-Patterns (MEDIUM)

8. 研究类Goal与反模式（中）

```
research-define-evidence-standard-first
```
— For Research Goals, Define the Evidence Standard Before Investigation Begins
```
research-build-claim-inventory
```
— Decompose Research Goals into a Claim Inventory Mapped to Evidence Channels
```
research-preserve-epistemic-ledger
```
— Final Report Must Preserve Epistemic Levels Per Claim — Use a Structured Ledger Entry
```
research-anti-patterns
```
— Avoid the Three Common Goal Anti-Patterns — Keep-Going Wishes, Hidden Uncertainty, Overclaim on Proxy

```
research-define-evidence-standard-first
```
— 对于研究类Goal，在开始调查前先定义证据标准
```
research-build-claim-inventory
```
— 将研究类Goal分解为映射到证据渠道的声明清单
```
research-preserve-epistemic-ledger
```
— 最终报告需按声明保留认知层级——使用结构化记录条目
```
research-anti-patterns
```
— 避免三种常见的Goal反模式：“持续执行”式愿望、隐藏不确定性、过度依赖替代指标

How to Use

使用方法

Read individual reference files for detailed explanations and worked examples comparing weak vs strong Goal text:

Section definitions — Category structure and impact levels
Rule template — Template for adding new rules

Each rule file contains:

A 2-4 sentence explanation of WHY the rule matters
An "Incorrect" example of a weak Goal or anti-pattern
A "Correct" example showing how to strengthen it
Reference back to the cookbook section it derives from

阅读单个参考文件获取详细说明，以及对比劣质与优质Goal文本的示例：

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

每个规则文件包含：

2-4句关于规则重要性的解释
一个“错误示例”展示劣质Goal或反模式
一个“正确示例”展示如何优化
指向其来源的烹饪书章节链接

Reference Files

参考文件

File	Description
AGENTS.md	Compiled TOC built by `build-agents-md.js`
references/_sections.md	Category definitions and impact ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information
gotchas.md	Failure points discovered through use

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