前言¶
用 AI 编程助手改代码时，最常见的翻车方式不是模型“不会写”，而是目标本身写得太糊。一句「把结账接口弄快点」「看看这个 PR 评论」「继续排查一下」，听起来像任务，其实只是活动描述：没有可验证的完成态，没有证据，也没有范围边界。Agent 往往会先改一堆文件，再回头问你“这样算不算好了”。
OpenAI 在官方 Agent Skills 仓库里提供了一个精选 Skill：define-goal。它的职责很窄——只在开始干活之前，把模糊意图收成一条具体、可衡量、可验证的目标；需要时再通过目标工具把它登记下来。本文按官方 SKILL.md 与 Codex Goals 相关说明，介绍它是什么、怎么装、怎么用。
这是什么¶
define-goal 是 OpenAI 维护的 curated Skill，源码目录在：
https://github.com/openai/skills/tree/main/skills/.curated/define-goal
目录里主要有 SKILL.md（工作流与质量标准）、agents/openai.yaml（Codex 侧展示名与默认提示）、以及 Apache 2.0 的 LICENSE.txt。Skill 的 frontmatter 名称就是 define-goal，描述大意是：在用户要求创建目标、澄清成功标准，或把模糊意图变成可量化结果时，帮助定义具体、可衡量的目标；它只负责目标创建与打磨，不负责持久快照、决策日志或长周期执行产物。
和 Codex 的 Goals 能力是配套关系。Codex 从 0.128.0 起支持持久目标：用户可用 /goal 管理生命周期，模型侧则有 get_goal / create_goal 等工具。define-goal 把「先把目标写合格，再 create_goal」写成可复用流程，避免一上来就开一个糊目标。
说明：openai/skills 仓库 README 已标注该仓库 deprecated，并指向 OpenAI Plugins 作为当前 Codex skill/plugin 示例入口；但截至本文写作时，define-goal 仍可在上述 curated 路径直接查看与安装。Agent Skills 本身是通用的 SKILL.md 格式，Cursor、Claude Code、Codex CLI 等支持该标准的工具都能加载同一套说明；其中 get_goal / create_goal 属于 Codex Goals 工具面，其他环境主要复用「把目标写合格」这一段流程。
核心工作流¶
官方 SKILL.md 把流程拆成六步，顺序很清楚。
1、先确认是否真的需要定目标。
用户显式提到 $define-goal、要创建/设置目标、要用 goal 工具，或希望把意图收成清晰目标时，才走这套流程。如果用户只是在要普通实现（改个 bug、加个小功能），直接干活，不要强行插一层 goal creation。
2、用具体语言重述目标。
一条可用目标至少要说清：完成后什么会为真；涉及哪个产物、系统、仓库、环境或用户可见行为；如何验证完成；范围内是什么；歧义会影响结果时，范围外是什么；以及什么情况下应停下来问用户，而不是继续空转。
3、能量化就量化。
优先写代表真实成功的数字或二元条件，而不是装饰性精度。官方举的几类证据包括：
- 通过/失败类验证：具体测试、检查、CI job、eval、命令或验收标准
- 质量阈值：延迟、错误率、成本、准确率/召回/精确率、覆盖率、flaky 率、包体积、内存、可用性、完成率，或人工评审标准
- 产物约束：文件路径、受影响模块、允许的命令、输出格式、目标环境、截止时间、最大改动半径
- 证据计数：复现次数、连续成功 rerun、审过的样例数、迁移记录数、已处理评论数、已核实用例数
4、弱目标先修再设。
本地上下文足够时，把含糊目标改写成可衡量目标；缺的细节会改变结果或验证方式时，只问一个简短澄清问题。纯活动型表述——「推进一下」「继续查」「改善一下」「弄弄 X」——除非能 sharpen 成可验证结果，否则应拒绝当目标。
5、创建前先看当前目标状态。
先调用 get_goal。没有活跃目标且质量达标，再 create_goal；已有目标且仍匹配用户意图，继续用，不要重复创建；已有目标与新请求冲突，则询问用户：先完成当前目标、若已完成则标完成，还是另开一条 goal-backed 线程。
6、质量过关后再创建。
目标用一条简洁的 objective 字符串；验证证据写进目标本身；有约束就写进范围；仅当用户明确要求时才带 token budget。用户没有明确要求 goal-backed 工作时，不要因为任务有多步就擅自 create_goal。
目标质量标准：好目标与弱目标¶
创建前，objective 应能回答这五个问题：完成后什么具体事实为真？用什么证据证明？成功的量化或二元阈值是什么？哪些范围边界重要？什么情况该停下来问人？
官方给出的好例子类似下面这样——结果、改动半径、验证命令和重复次数都写在同一句话里：
Reduce checkout API p95 latency below 250 ms for the documented slow path by making the smallest safe server-side change, then verify with `npm run test:checkout` and the existing local latency benchmark showing p95 under 250 ms across 3 consecutive runs.
再比如处理 PR 评论：
Resolve the open review comments on PR 123 that request code changes, update only the affected auth files and tests, and verify with the targeted auth test command plus `gh pr view 123` showing no unresolved change-request threads.
弱目标则是「Make checkout faster.」「Keep investigating the PR comments.」——有动作，没有完成态。
对不同任务，官方还给了量化启发式：修 bug 时尽量「先复现、再修复」，最好有失败后变通过的验证器；写测试要写清命令与通过条件；做性能要写清指标、阈值、测法与跑几次；做质量要有可观察验收条（样例评审、lint/typecheck/test、或用户认可的产物）；做研究要写清研究要支撑什么决策、资料范围与证据标准；做运维要写清健康态、观测窗口、失败阈值与回滚/升级触发条件。
澄清问题时也要克制。只有「合理改写可能追错方向」时才问，问题要短，对准缺失的验证器或范围边界。官方建议的问法包括：成功用延迟、成本、准确率还是用户可见行为定义？在 local、staging 还是 production 验证？最少要看到什么证据才能标完成？用户给不出指标时，提出当前最诚实的二元验证器，请对方确认即可。
安装与启用¶
在 Codex 中安装¶
按 openai/skills 仓库 README，curated Skill 可用系统自带的 $skill-installer 按名称安装（默认对应 skills/.curated）：
$skill-installer define-goal
也可以直接指向 GitHub 目录 URL：
$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/define-goal
安装后需要重启 Codex，新 Skill 才会被加载。Codex 侧 UI 元数据在 agents/openai.yaml：展示名为 Define Goal，短描述为 Shape clear measurable goals，默认提示会引导先用 $define-goal 把意图收成可衡量目标再开工。
若要配合 Goals 能力，确认 Codex 版本至少为 0.128.0。用户侧常用 /goal、/goal pause、/goal resume、/goal clear；若 slash 列表里没有 /goal，可按官方说明启用 features.goals（例如在 config.toml 中配置，或执行 codex features enable goals）。
在 Cursor / Claude Code 等工具中使用¶
define-goal 遵循通用 Agent Skills 目录结构：一个文件夹 + SKILL.md。把官方目录拷到各工具会扫描的 skills 路径即可，例如：
- Cursor：项目内
.cursor/skills/define-goal/SKILL.md，或用户级~/.cursor/skills/define-goal/SKILL.md - Claude Code：
.claude/skills/define-goal/或~/.claude/skills/define-goal/ - Codex：除
$skill-installer外，也可放到其 skills 目录（具体以当前 Codex 文档为准）
文件夹名建议与 frontmatter 的 name: define-goal 一致。加载后，可用 $define-goal / 工具对应的 skill 调用方式触发，或直接说「帮我把这个意图定义成可衡量目标」。需要强调的是：没有 Codex Goals 工具时，Skill 仍可约束 Agent「先写清目标再动手」；真正调用 get_goal / create_goal 登记活跃目标，仍依赖宿主是否提供这些工具。
典型用法示例¶
场景一：你只有一句糊需求。
可以对 Codex / 支持该 Skill 的助手说：
用 $define-goal：我想把结账接口弄快点，先把目标定清楚，先不要改代码。
按工作流，Agent 应重述成带指标、验证命令与范围的 objective；缺关键阈值时只问一个短问题；质量达标且你明确要 goal-backed 工作时，再 get_goal → create_goal。
场景二：PR 评论很多，怕 Agent 改飞。
可以这样开场：
$define-goal
请把「处理 PR 123 里要求改代码的 review 评论」收成一条可验证目标，范围限制在 auth 相关文件和测试。
对照官方好例子，最终目标应同时包含：处理哪些评论、改哪些文件、用哪条测试命令、以及如何用 gh pr view 确认没有未解决的 change-request。
场景三：普通实现任务不要硬套。
如果你说的是「给这个函数加个空指针检查并补单测」，按 Skill 说明应直接实现，而不是先强制 create_goal。Goal 适合路径不确定、但完成线清晰的长程工作；一次性小改动用普通提示往往更合适。
适用场景与注意事项¶
适合：性能优化、flaky 排查、依赖迁移、需要先复现再修复的 bug、benchmark 驱动调参、以及必须交付可检查产物的研究/审计类任务——也就是「有清晰终点，但中间路径要边做边看」的工作。
不适合或需谨慎：用户只要普通多步实现、并未要求 goal-backed 时，不要擅自建目标；不要把「推进进度」类活动描述直接塞进 create_goal；本 Skill 明确不创建中间计划产物、持久快照、ledger、决策日志或 resume 文件——那些属于别的规划/执行机制。
另外，create_goal 的 objective 应是单条简洁字符串，验证与范围写在里面；token budget 仅在用户明确要求时附加。已有活跃目标时先处理冲突，避免重复目标把线程状态搅乱。
小结¶
define-goal 做的事很克制：在 Agent 动手前，把意图收成「结果 + 证据 + 阈值 + 范围 + 停问条件」。它和 Codex Goals（/goal、get_goal、create_goal）对齐，也把「先定目标再执行」固化成可移植的 SKILL.md 流程。
官方地址：https://github.com/openai/skills/tree/main/skills/.curated/define-goal
若关注 Codex 当前 skill/plugin 分发方式，也可同时查看 OpenAI 的 Plugins 仓库与 Using skills in Codex 文档；Goals 用法可参考 Using Goals in Codex。
