任务描述四要素：Goal、Context、Constraints、Done-when
TL;DR
给 Codex 的任务描述，不应该停在“帮我改一下”。一个可执行的工程 brief 至少包含四个要素：Goal 说明要达到的最终状态，Context 说明理解任务需要从哪里开始，Constraints 说明不能碰的边界和必须遵守的规则，Done-when 说明怎样验收完成。
四要素不是提示词套路，而是工程协作的最低信息量。人类同事接到任务时也需要目标、背景、边界和验收标准。Codex 只是更需要这些信息，因为它会读文件、改文件、跑命令，并可能在模糊目标下主动扩大范围。
本文中的四要素是团队工作流建议，不是 OpenAI 官方定义的固定命令。它和官方 Codex 文档中的 prompting、workflows、AGENTS.md、审批和安全机制配合使用：AGENTS.md 写长期规则，任务 brief 写本次目标；沙箱和审批限制执行边界；Done-when 把结果拉回可验证状态。
读者定位
本文面向已经让 Codex 写过代码，但经常遇到范围漂移、过度重构、测试缺失、最终摘要不可验收的开发者和技术负责人。你可能已经有 AGENTS.md，也知道应该跑测试，但每次任务仍然需要反复纠偏。四要素的目标，是把纠偏前移到任务入口。
如果你负责团队规范，可以把四要素写进 issue 模板、PR 修复模板、Codex Cloud 任务模板、CLI 任务手册或 AGENTS.md 的任务描述示例中。
问题：Codex 不缺动作，缺的是可执行任务边界
很多低质量任务只有动作，没有结果：
优化用户模块。
修一下认证。
补一下测试。
整理一下代码。
这些句子的问题不是短，而是没有工程判断。Codex 不知道优化的目标是性能、可读性、依赖关系还是错误处理；不知道认证问题是登录失败、刷新失败、权限绕过还是 token 过期；不知道测试要覆盖 bug、边界还是现有行为；不知道整理代码允许多大范围。
缺少 Goal 时，Codex 会自己定义成功。缺少 Context 时，它会花大量时间扫无关文件，或从错误入口开始。缺少 Constraints 时，它可能引入依赖、改公共接口、重构共享模块。缺少 Done-when 时，它可能在“看起来合理”时停下，而不是在测试通过、风险说明完整时停下。
对人类同事来说，模糊任务会引发追问；对 Codex 来说，模糊任务还会引发无谓执行。执行能力越强，任务边界越要清楚。
心智模型：把 prompt 改成工单
任务 brief 可以看成一张工单。它不需要长，但要回答四个问题。
Goal：最终状态是什么
Goal 应该描述用户可观察或工程可验证的结果，而不是只描述动作。
差的 Goal：
重构导出模块。
好的 Goal：
让订单导出在查询结果为空时返回只有表头的 CSV，HTTP 状态保持 200。
前者给了动作，后者给了行为。Codex 可以围绕行为找入口、写测试、判断是否完成。
Context：从哪里开始理解
Context 不是把所有资料都贴进去，而是给出正确入口。它可以包含文件路径、错误日志、复现步骤、相关 issue、已有测试、业务规则、环境限制。
好的 Context 会减少扫描成本，也会减少误读。例如：
从 src/orders/export.ts、src/orders/exporter.ts 和 tests/orders/export.test.ts 开始。
线上错误日志包含 "Cannot read properties of undefined (reading 'map')"。
如果你不知道入口，也可以把任务写成 Ask：
先不要修改代码。请找出订单导出逻辑的入口文件、测试文件和最可能相关的调用链。
Constraints：不能做什么
Constraints 是工程责任的边界。对 Codex 来说，“能做”不等于“应该做”。要明确哪些文件不能碰，哪些接口不能改，哪些依赖不能加，哪些命令不能运行，哪些模块必须先计划。
常见 Constraints：
- 不改公开 API。
- 不改数据库 schema。
- 不引入新生产依赖。
- 不修改
.env*、secrets、部署脚本。 - 只改指定目录。
- 发现需要改权限、账单或迁移时先停下。
- 不运行网络命令，除非先请求审批并说明目的。
Constraints 不是为了束缚模型，而是为了让 diff 可 review。
Done-when：怎样判断完成
Done-when 把任务从“生成结果”拉回“验收结果”。它可以包含测试命令、lint、typecheck、构建、截图、基准数据、文档更新、最终汇报格式。
好的 Done-when：
新增或更新覆盖空结果的测试。
运行 pnpm test -- tests/orders/export.test.ts。
最后汇报修改文件、命令结果、未运行检查和剩余风险。
如果环境可能跑不了命令，也要写清：
如果测试无法运行，请说明缺少的依赖或环境，并给出人工验证步骤。
详细机制：四要素如何和 Codex 官方能力配合
四要素本身不是 Codex 参数，但它和 Codex 的官方机制天然配合。
AGENTS.md 写长期 Context 和 Constraints。比如包管理器、测试命令、安全边界、汇报要求。任务 brief 不应该重复所有长期规则，引用并补充本次任务差异即可。
沙箱和审批实现硬 Constraints。Prompt 写“不要写出工作区”有用，但真正阻止越界的是 sandbox 和 approval。官方安全文档中的 workspace-write + on-request 就是典型基线：工作区内可执行，越界或联网要审批。
CLI、App、Web / Cloud 影响 Context。CLI 能看到本地工作区，Cloud 依赖远程环境配置。任务 brief 里应说明入口相关信息：本机未提交文件是否可用，云端是否有 setup 命令，PR 是否是交付物。
Done-when 影响最终摘要。Codex 完成任务时应该报告改了什么、跑了什么、失败了什么、风险是什么。若 brief 没要求，它可能只给一句“已完成”。团队需要把 Done-when 写成习惯。
Ask / Plan / Execute 决定四要素的完整度。只读 Ask 可以弱化 Constraints，但要明确不改文件；高风险 Execute 必须写完整 Constraints 和 Done-when；Plan 任务要把 Done-when 写成“先给计划，等待确认”。
真实工作流案例：把模糊任务改成可执行 brief
案例一：修 bug
模糊写法：
帮我修复导出 CSV 的 bug。
可执行写法：
Goal:
修复订单导出接口在没有订单时返回 500 的问题。期望返回带表头的空 CSV，状态码 200。
Context:
从 src/orders/export.ts 和 tests/orders/export.test.ts 开始。
错误日志包含 "Cannot read properties of undefined (reading 'map')"。
Constraints:
不要改数据库 schema。
不要改变 CSV 字段顺序。
不要引入新依赖。
Done-when:
新增或更新覆盖空结果的回归测试。
运行 pnpm test -- tests/orders/export.test.ts。
汇报修改文件、测试结果和剩余风险。
案例二：代码理解
模糊写法：
看一下 auth 怎么实现的。
可执行写法：
Goal:
解释当前认证流程，包括登录入口、session 创建、token 刷新、权限校验和登出路径。
Context:
从 src/auth、src/session 和 tests/auth 开始。必要时追踪调用方。
Constraints:
不要修改文件，不要运行写文件命令。
Done-when:
输出关键文件列表、调用链、现有测试覆盖、风险点和需要人工确认的问题。
案例三：补测试
模糊写法：
给用户模块补测试。
可执行写法：
Goal:
为用户资料更新逻辑补充回归测试，重点覆盖空昵称、重复邮箱、无权限修改三类场景。
Context:
从 src/users/profile.ts 和 tests/users/profile.test.ts 开始，沿用现有测试风格。
Constraints:
优先只改测试文件。若发现生产代码 bug，先停下说明，不要直接修。
Done-when:
列出新增测试场景。
运行 pnpm test -- tests/users/profile.test.ts。
说明这些测试覆盖了哪些风险，哪些风险仍未覆盖。
操作清单：写 brief 前问自己
- Goal 是否描述最终行为，而不是只有“优化、整理、修复”这类动作？
- Context 是否给了入口文件、错误日志、测试文件或复现步骤？
- Constraints 是否写清不能改的接口、依赖、目录、命令和权限？
- Done-when 是否包含具体命令、测试、人工检查点或最终汇报格式？
- 是否需要先 Ask 或 Plan，而不是直接 Execute？
- 是否把长期规则放在
AGENTS.md，把本次差异放在 prompt？ - 是否说明当前任务是否允许 Codex 修改文件？
- 是否说明如果验证命令跑不了，应该怎样汇报？
权衡与风险
四要素会增加输入成本。对 typo、链接修正、单行文档更新，完整模板可能过重。经验规则是：失败代价越高，brief 越完整；权限越大，Constraints 越具体；任务越模糊，先 Ask 或 Plan。
四要素也不能保证 Codex 一次成功。它只是减少错误方向上的努力。遗留系统、缺测试、跨服务依赖、不稳定 CI、隐含业务规则仍然需要人类判断。
过度约束会让 Codex 无法解决真实问题。比如任务只允许改一个文件，但根因在另一个文件，Codex 会卡住。好的 Constraints 应该允许它发现越界需要，并停下说明，而不是假装不需要越界。
常见误区
误区一：Context 越多越好。大量会议纪要、长日志、无关链接会稀释重点。更好的 Context 是入口文件、复现步骤和关键约束。
误区二：Done-when 写成“完成即可”。这没有验收意义。至少写清要跑什么命令、输出什么摘要。
误区三：Constraints 只写代码范围，不写权限范围。Codex 可能运行命令、访问网络、改配置。任务约束要覆盖文件、命令、网络和外部系统。
误区四：Goal 写成技术动作，不写用户行为。比如“重构缓存逻辑”不如“让同一用户 5 分钟内重复请求命中缓存，并保持权限隔离”。
误区五：把所有规则都塞进本次 prompt。稳定规则应进入 AGENTS.md，否则每次都会漏。
团队落地：把四要素嵌进日常流程
四要素真正发挥作用，不靠每个开发者临时记住，而靠进入团队日常入口。可以把 Goal、Context、Constraints、Done-when 放进 issue 模板、PR 修复模板、故障修复模板、Cloud 任务模板和代码审查反馈模板。这样开发者派任务时自然补齐信息，Codex 也更容易产出一致结果。
第一种入口是 issue。很多 issue 只写现象，没有工程上下文。给 Codex 使用的 issue 至少要包含复现步骤、期望行为、实际行为、相关文件或模块、允许改动范围、验收命令。若 issue 写不出这些信息，就先让 Codex Ask，而不是直接修。Issue 模板可以加入“适合委托 Codex 吗”这一项，明确是否已有足够上下文。
第二种入口是 PR review。人类 reviewer 经常留言“这里补个测试”“这个逻辑能不能简化”。这类反馈对 Codex 来说也不够具体。更好的 review 评论是：“为 parseAmount 增加覆盖空字符串、三位小数、负数的测试；只改 amount.test.ts；运行 pnpm test -- amount.test.ts。”这种评论天然包含 Goal、Context、Constraints、Done-when，可以直接变成 Codex 修复任务。
第三种入口是故障修复。线上事故中，不要让 Codex 直接改生产路径。先用四要素写只读调查：Goal 是建立事实，Context 是日志、时间线、相关模块，Constraints 是不改文件不访问生产，Done-when 是输出假设和下一步。等人类确认根因后，再写执行 brief。故障期间越紧急，越不能省略边界。
第四种入口是技术债治理。比如“清理旧 API 调用”很容易变成大范围改动。四要素可以把它拆成批次：Goal 是迁移某个目录，Context 是新旧封装和测试，Constraints 是不改业务行为，不跨模块顺手重构，Done-when 是局部测试和调用点清单。每批任务可 review，失败也可回滚。
第五种入口是 Cloud 委托。云端任务更需要完整 brief，因为它没有你本地的即时澄清机会。Cloud 任务单应额外写 setup、分支、测试命令、环境限制和 PR 交付要求。不要把“看一下能不能修”扔给云端。可以先让本地 CLI 做 Ask 或 Plan，再把确认后的 Execute brief 交给 Cloud。
第六种入口是团队培训。新成员学习 Codex 时，不要先教一堆命令。先给他们看几组差 brief 和好 brief，让他们判断缺了哪个要素。然后让他们把真实 issue 改写成四要素任务。这个训练比背参数更有用，因为多数失败都发生在任务入口。
第七种入口是复盘。每次 Codex 任务失败后，按四要素复盘：Goal 是否歧义，Context 是否错误，Constraints 是否缺失，Done-when 是否不可执行。把失败归类后，团队会发现固定模式。例如测试没跑往往是 Done-when 缺失，改动过大往往是 Constraints 不清，找错文件往往是 Context 不足。
最后，四要素要保持轻量。不要把每个小任务都写成长文档。团队可以规定三档：低风险任务写一句 Goal 加 Done-when；中风险任务写完整四要素；高风险任务先写 Ask brief，再写 Plan brief，最后写 Execute brief。这样既有标准，又不会让流程压过开发。
反例分析：四要素缺一项会怎样失败
四要素的价值，在反例里最清楚。很多 Codex 失败任务不是完全没写 brief，而是缺了其中一项，导致模型在错误方向上认真执行。
缺 Goal 的反例是“优化导出模块”。Codex 可能减少重复代码、改字段生成方式、调整命名、补缓存，但 reviewer 不知道优化目标是什么。如果真正问题是空结果返回 500，这些改动都可能偏离目标。Goal 应该写结果：“空结果返回表头 CSV，状态码 200”。
缺 Context 的反例是“修复登录刷新后登出”。仓库里可能有前端路由、后端 session、cookie 中间件、权限校验、移动端登录。Codex 如果从错误入口开始，会浪费时间，甚至修错层。Context 不需要给完整答案，但要给入口、日志、复现步骤或相关测试。
缺 Constraints 的反例是“把接口迁移到新实现”。Codex 可能改公共返回结构、引入新依赖、修改客户端调用、重写测试快照。任务也许能通过局部测试，却破坏外部兼容。Constraints 要写“不改公开 API”“不引入依赖”“不改客户端协议”，让迁移保持在可审查范围。
缺 Done-when 的反例是“补测试”。Codex 写了几个测试，没说明覆盖风险，也没运行命令。看起来完成了，实际只覆盖 happy path。Done-when 应写“覆盖空值、权限失败、重复提交；运行某测试文件；汇报未覆盖风险”。这样才知道测试补到了哪里。
Goal 写错也会失败。比如目标写“让测试通过”，Codex 可能跳过断言、调整测试预期、mock 掉真实逻辑。真正目标应是用户行为或业务行为，测试只是验证手段。对 Codex 来说，目标措辞会影响它选择路径。
Context 过量也会失败。把几十页会议纪要、所有日志、多个链接都贴进去，会让关键信息淹没。更好的写法是先给最可能入口，再允许 Codex 必要时继续追踪。如果材料很多，可以让它先整理材料，不要直接执行。
Constraints 过窄也会失败。比如只允许改一个文件，但根因在另一个文件，Codex 可能做补丁式绕过。好的约束应允许它发现越界需要并停下说明：“若需要修改范围外文件，先报告原因，不要直接改。”这比把它逼进错误修复更可靠。
Done-when 不可运行也会失败。要求运行一个本地不存在的命令，Codex 会卡住或报告失败。团队应把真实命令放进 AGENTS.md，任务里引用局部命令。如果命令可能依赖环境，就写“如果无法运行，说明原因和人工验证步骤”。
通过这些反例可以看出，四要素不是为了让任务变长，而是为了防止 Codex 自行补全工程判断。你越清楚地写出目标、入口、边界和验收，Codex 越可能把执行能力用在正确位置。
Brief 评审清单
在把任务交给 Codex 前，可以用一份短清单评审 brief。这个动作花不了多久，却能避免很多返工。
先看 Goal。它是否描述了最终可观察状态？如果 Goal 只有“优化”“整理”“修复”“改进”，要继续追问结果是什么。能写成用户行为、接口行为、测试行为或文档状态，就不要停在动作词。
再看 Context。它是否给了入口？入口可以是文件、目录、错误日志、复现步骤、issue、测试文件、相关提交。若 Context 只写“相关模块”，Codex 很可能从错误地方开始。若你也不知道入口，就把任务改成 Ask。
再看 Constraints。它是否覆盖文件、接口、依赖、命令、网络、凭据和高风险模块？很多 brief 只写“不要改太多”，这没有可执行意义。要写“只改这些文件”“不改公开 API”“不引入依赖”“不访问网络”“发现需要改权限时先停下”。
再看 Done-when。它是否能被验证？“测试通过”不够，最好写具体命令。“完成后总结”也不够，最好写总结字段。若环境可能缺失，写清无法运行时怎样汇报。
然后看阶段。这个 brief 是 Ask、Plan 还是 Execute？如果目标模糊但 brief 允许修改文件，风险就高。如果目标清楚但权限只读，任务会卡住。阶段、目标和权限要一致。
再看规模。一个 brief 是否包含多个互不相关目标？比如“修 bug、重构、补文档、优化性能”。这类任务应拆分。Codex 不是不能做长任务，而是长任务要有阶段和停靠点。
最后看交付物。完成后你希望看到什么？本地 diff、PR、调查报告、计划、测试结果、性能数据、迁移说明？交付物不清，Codex 会按自己的理解收尾。
这份清单也可以给 Codex 自用。你可以先让它评审你的 brief，指出缺失字段，再执行任务。对于高风险任务，让 Codex 先批判任务描述，往往比直接让它写代码更省时间。
还有一个经验：brief 应该写给“不了解你脑内上下文的人”。如果某句话只有你自己明白，就需要补 Context；如果某个边界只有团队老人知道，就需要补 Constraints；如果完成标准只能靠你主观判断，就需要补 Done-when。Codex 不是不能推理，但让它猜团队隐含知识，是把工程风险交给概率。
在团队协作中，brief 也能降低人与人之间的误解。一个写得好的 Codex 任务，通常也适合作为人类同事的任务说明。反过来，如果一个任务连人类同事都难以执行，就不应该期待 Codex 一次做好。四要素不是 AI 专属技巧，而是把工程任务写清楚的通用方法。
如果你发现 brief 写完很长，先不要急着执行。长 brief 可能说明任务本身太大，应该拆成调查、计划、执行几个阶段。真正成熟的任务描述，不是把所有复杂性塞进一次 Execute，而是把复杂性拆到可验证的步骤里。
Brief 还应该写清“当前不能判断的事”。例如不确定根因、不确定测试命令、不确定某接口是否公开，都可以直接列为不确定点。让 Codex 先消除不确定点，比假装需求已经完整更稳。工程任务不是越确定越专业，能明确表达未知，才更接近真实协作。
对技术负责人来说，brief 质量也是需求质量的镜子。若团队长期写不出 Goal 和 Done-when，说明问题定义本身还没成熟，不应急着让 Codex 执行。
先把需求写到可交付，再交给代理执行，这比事后让代理解释失败原因更节省时间。
好的 brief 还有一个副作用：它会暴露需求本身的漏洞。写不出验收标准、写不出禁止事项、写不出上下文入口时，说明现在还不是执行时机，而是继续澄清问题的时机。
延伸阅读
GitHub 原文：05-task-brief-four-elements.md