codex-goals

OpenAI Codex Goals Best Practices

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".

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

Rule Categories by Priority

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.

Quick Reference

1. Goal Fit Decisions (CRITICAL)

• 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

2. Outcome Definition (CRITICAL)

• 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

3. Verification Surface (CRITICAL)

• 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

4. Boundaries & Iteration (HIGH)

• 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

5. Lifecycle Commands (HIGH)

• 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

6. Evidence-Based Completion (HIGH)

• 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

7. Crafting Strong Goals (MEDIUM)

• 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

8. Research Goals & Anti-Patterns (MEDIUM)

• 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

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

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