Codex Goals 使用指南（要点整理）

一句话结论

Goal 是 Codex 里的“可暂停/可恢复的持续目标”，用来让多回合任务始终围绕可验收的完成条件推进，而不是每回合都要你重复“继续/再试一次/再跑一轮测试”。

什么时候该用 Goal

适合：有明确“终点”，但路径不确定、需要反复验证的任务，例如：

• 性能优化（需要反复跑 benchmark、对比指标）
• flaky test 排查（复现→最小化→修复→回归）
• 依赖迁移、分阶段重构（每步都要可验证）
• bug hunt（需要复现、修、再验证）
• 研究类任务（需要最终可交付产物 + 证据链）

不适合：一次性就能完成的“小改动/单次编辑”。

Goal 的“完成合同”要素

写 Goal 时至少包含三件事：

1. 可度量的结果：什么算完成（例如 p95 < 120ms）
2. 验证面：用什么证据检查（tests、benchmark、最终产物、日志/报告）
3. 约束条件：哪些不能破坏（正确性测试不能回退、行为不变、兼容性等）

示例：

• /goal Reduce p95 latency below 120 ms without regressing correctness tests

生命周期命令（/goal）

• /goal：查看当前 Goal
• /goal pause：暂停
• /goal resume：恢复
• /goal clear：清除当前 Goal

Quickstart（版本/安装）

文档要点：Goals 从 Codex 0.128.0 起可用；先安装/升级后用 codex --version 确认版本。

• npm：npm install -g @openai/codex@latest → codex --version
• Homebrew：brew update → brew upgrade --cask codex → codex --version

我自己的用法模板（可直接改）

• /goal <你要达成的可验收结果> + <验证方式> + <不许退化的约束>

例：

• /goal Make test suite green and keep runtime within +5% by running pytest -q
• /goal Cut bundle size by 15% measured by build stats without breaking e2e tests

官方“强 Goal”结构（6 要素）

强 Goal 通常包含 6 件事（把“完成合同”写清楚）：

1. Outcome：完成时应该满足什么
2. Verification surface：用什么证据验证（test/benchmark/report/artifact/命令输出/材料来源）
3. Constraints：哪些不能退化（正确性、行为、不跳过测试等）
4. Boundaries：允许触达的文件/工具/数据/仓库边界
5. Iteration policy：每轮怎么选下一步、怎么记录证据
6. Blocked stop condition：什么情况下必须停下并报告阻塞与所需输入

官方写法模板（可直接复制）

/goal <desired end state> verified by <specific evidence> while preserving <constraints>. Use <allowed inputs, tools, or boundaries>. Between iterations, <how to choose the next best action>. If blocked or no valid paths remain, <what to report and what input would unblock>.

例子（官方）

• /goal Reduce p95 checkout latency below 120 ms on the checkout benchmark while keeping the correctness suite green
• /goal Reduce p95 checkout latency below 120 ms, verified by the checkout benchmark, while keeping the correctness suite green. Use only the checkout service, benchmark fixtures, and related tests. Between iterations, record what changed, what the benchmark showed, and the next best experiment to try. If the benchmark cannot run or no valid paths remain, stop with the attempted paths, the evidence gathered, the blocker, and the next input needed.
• /goal Produce the strongest evidence-backed reproduction of the paper using the available materials and local resources. Attempt the headline results where feasible, verify outputs where possible, and end with a report that separates confirmed findings, approximate reconstructions, blocked claims, and remaining uncertainty.

来源

• 原文标题：Using Goals in Codex（Raj Pathak, Stefano Fabbri）
• 获取方式：由对话中粘贴的官方文档片段整理（未做外部校验）