把“帮我优化一下”改写成可执行 brief

周报更漂亮了，真正的问题却不见了

你让 Codex「优化一下周报」。它重写标题、统一语气、压缩段落。老板最关心的延期风险和待决定事项，被顺手润色成了不痛不痒的一句话。

形容词越多，任务未必越清楚。

好 brief 的价值，是消灭那些足以改变结果的未知。 这节课会从一句模糊请求开始，一轮轮补上目标、材料、边界和完成证据，直到第三个人也能独立验收。

好 brief 不是更长，而是减少关键歧义

OpenAI 的 Codex 最佳实践给出四个默认部分：

1. Goal：要改变或建立什么；
2. Context：哪些文件、页面、报错、样例会改变判断；
3. Constraints：必须遵守的标准、架构、安全与不可改变项；
4. Done when：什么行为、测试或证据出现后才算完成。

本节会把练习册中的“帮我优化信息流”改成可执行任务。先不要看参考答案。

第一步：找出模糊请求中的四类空白

原请求：

帮我优化一下信息流，做得高级一点，顺便把体验问题修了。

逐句标注：

• “优化”没有说明是视觉、性能、信息排序还是数据正确性；
• “高级”没有参考对象或可观察属性；
• “体验问题”没有复现步骤；
• “顺便”没有范围边界；
• 没有说明哪些现有行为必须保留；
• 没有完成证据。

先写问题，不急着替需求方补答案。擅自猜测业务目标，会让一份看起来完整的 brief 更危险。

第二步：把 Goal 写成结果

弱 Goal：

优化信息流页面。

可执行 Goal：

让 /feed 在 390px 手机视口不再横向溢出，
并让加载失败时出现可重试错误状态；桌面侧栏和现有信息排序保持不变。

后者说明了页面、故障和保留项。它仍没有规定具体 CSS 或组件方案，让 Codex 可以先检查真实实现。

练习：把你自己的需求改写成一句“对象 + 可观察变化 + 必须保留”。

第三步：Context 只放会改变方案的证据

从练习册提供的材料中选择：

• 页面路由与复现步骤；
• 移动端截图中真正异常的区域；
• 桌面正确状态作为回归基线；
• 相关组件和样式入口；
• 项目自己的 AGENTS.md；
• 当前测试与运行命令。

不要把整个仓库描述复制进 prompt。Context 的判断标准是：删掉这条信息，会不会让方案、范围或验证发生变化？

可写为：

Context
- 问题路径：/feed；390×844 时向右多出约 24px。
- 桌面 1280×720 的固定侧栏是正确基线，必须保留。
- 先检查 app/components/workspace-shell.tsx、相关路由和 app.css。
- 按仓库 AGENTS.md 使用指定浏览器完成桌面与移动验收。

第四步：Constraints 保护真实风险

边界不要写成二十条偏好。只保护真正会造成返工或外部影响的内容：

Constraints
- 不改变信息排序、数据请求和桌面侧栏布局。
- 保留工作区里与本任务无关的用户改动。
- 不新增依赖。
- 不提交、不推送、不部署。

最后一条很重要：修改文件、创建 commit、push 和部署是不同授权，不应由“帮我修复”自动推出。

第五步：把 Done when 写成第三方可复查的事实

不合格：

- 页面看起来正常。
- 代码质量良好。

合格：

Done when
- 390×844：documentElement.scrollWidth 等于 clientWidth；
- 移动导航关闭时不占布局宽度，打开后宽 260px；
- 1280×720：侧栏滚动页面后仍固定并可内部滚动；
- 正常、加载、空和错误状态均可到达；
- 相关测试、typecheck 和 build 通过；
- 最终报告列出文件、命令、浏览器证据和未解决项。

每一项都能由另一位验收者复查，不依赖 Codex 自我评价。

第六步：让 Plan mode 攻击你的 brief

把四部分合并后输入：

/plan

[粘贴你的 Goal / Context / Constraints / Done when]

先只读检查真实实现。找出：
1. 与仓库现状冲突的要求；
2. 无法验证的完成条件；
3. 可能遗漏的状态或设备；
4. 需要我决定、不能由你猜测的事项。
在我确认前不要修改文件。

预期结果

Codex 应该把问题落到真实文件和状态。例如它可能发现页面使用不同路由、移动断点不是你以为的数值，或错误态当前无法人为触发。把这些发现回填 Context 或 Done when。

如果计划没有提出任何问题，检查它是否真的阅读了仓库；对于含糊任务，“毫无疑问”通常不是好信号。

第七步：用评分表做发布前审查

下载评分表，每项 0–2 分：

维度	0 分	1 分	2 分
Goal	抽象愿望	有对象但不可测	有对象、变化和保留项
Context	无证据	路径或截图零散	证据用途清楚
Constraints	无边界	偏好堆叠	保护真实风险
Done when	主观判断	部分可测	机械与人工证据齐全
授权	默认全包含	有模糊限制	外部动作逐项明确

低于 8 分，不要直接执行。参考答案展示的是一种合格版本，不是要求照抄。

失败修正

• brief 很长但计划仍泛：删掉背景故事，补真实文件和复现证据。
• Codex执着某个方案：检查 Goal 是否误写了实现细节。
• 验收只能靠截图：补可测量的结构、状态或命令证据。
• 执行中不断追问：把反复出现的业务规则写回 Context 或仓库指导。

用一次真实误解检验 brief

找出最近一次「结果不差，但不是你要的」任务。不要先责怪模型，标出是哪项关键未知被留给了它自行决定。

补完以后让 Codex 只复述理解，不执行。问题变少、计划能对应完成证据，这份 brief 才通过第一关。

完成检查

• Goal 说明对象、可观察变化和保留项
• Context 中每条材料都有用途
• Constraints 只保护真实风险和授权
• Done when 能由第三方复查
• Plan mode 的问题已用于修订 brief