Prompting 中文精读：不是咒语，而是任务契约

那句「帮我优化一下」，往往是失控的起点

页面改完了。颜色换了，组件拆了，依赖多了两个。你真正想修的手机横向滚动还在。

Codex 并不是没有理解中文。它只是收到了一句没有终点、没有边界、也没有验收方式的话。面对空白，它只能自己补答案。

好 prompt 不是写得像咒语，而是让任务少一点自作主张。 我们会把这句含糊请求改成一份真实 brief，并在每一段后面追问：它阻止了哪一种跑偏？

官方 Prompting 页真正强调什么

OpenAI 的 Prompting 教程没有要求背“万能公式”，而是建议用自然语言说明会改变结果的信息。对一般任务，可检查四类信息：

• Goal：最终想得到什么；
• Context：模型不知道、但会改变结果的背景和材料；
• Output：交付形式、结构、受众和长度；
• Boundaries：不能改变的事实、预算、来源和外部动作。

Codex 最佳实践把工程任务进一步写成 Goal、Context、Constraints、Done when。两套结构并不冲突：Output 更强调成品形式，Done when 更强调如何证明完成。

为什么“写得很长”仍可能是坏 prompt

长度不等于信息密度。下面这段看似具体：

请你扮演资深前端专家，认真分析、深度思考，用最佳实践把页面做得现代、专业、好看，确保代码质量。

它没有指出页面、用户、现状、不可改变项和验证。角色形容词不能替代上下文；“现代、专业、好看”也没有可观察标准。

更可靠的 brief：

Goal
- 修复 /checkout 在 390px 宽度下的横向滚动。

Context
- 相关组件在 app/routes/checkout.tsx。
- ref/checkout-mobile.png 是目标参考。
- 桌面 1280px 布局已经通过，不应重做视觉系统。

Constraints
- 保留现有组件和文案。
- 不新增依赖。
- 只修改与溢出直接相关的文件。
- 发现现有未提交改动时先报告，不覆盖。

Done when
- 390×844 无横向滚动，表单和主要按钮可见。
- 1280×720 布局没有回归。
- 类型检查和现有测试通过。
- 给出两个视口截图、修改文件和未运行项。

Context 不是“把所有文件都塞进去”

有效上下文回答三个问题：

1. 事实在哪里：文件、URL、截图、数据表；
2. 哪些信息具有权威性：设计稿、测试、产品说明、旧行为；
3. 哪些未知会改变方案：受众、兼容范围、数据权限。

上下文太少会让 Codex猜；上下文太多会把无关噪声放进注意力。最好的做法通常是提供入口和选择规则，让它先检查，再报告它实际使用了什么。

Constraint 应该约束风险，不是替 agent 写算法

高价值约束包括：

• 不得改变的公共 API 或视觉系统；
• 可写文件和不可触碰目录；
• 不安装依赖、不联网、不发送、不部署；
• 必须兼容的运行环境；
• 遇到冲突或敏感数据时暂停。

低价值约束是把每一步实现细节提前写死。例如“必须用三个函数、每个函数二十行以内”可能阻止更合适的实现。除非它来自项目标准，否则先约束结果和风险。

Done when 必须能被第三方检查

把形容词换成证据：

含糊完成标准	可检查完成标准
页面更美观	指定视口无溢出；间距与参考图关键区域一致
代码质量高	类型检查、测试通过；无新增重复逻辑；review 无高优先级发现
数据准确	总数与独立基线一致；异常行单列；来源和口径可追溯
文档完整	安装、运行、验证、常见失败均可从目录到达

Done when 还要包含停止条件：全部证据满足则结束；同一阻塞重复、需要新授权或外部状态变化时暂停并说明。

Follow-up 不是重新开一个 prompt

官方教程强调用后续消息迭代。有效纠偏应该指出观察到的差异：

当前结果仍在 390px 出现 24px 横向滚动。
请先定位具体溢出元素并展示证据；保留桌面布局，不要扩大改动。
修复后重新测量两个视口，再汇报。

“再好一点”“继续优化”会重新打开范围。每轮跟进都应缩小差距，而不是增加抽象要求。

实操：重写你自己的失败 prompt

在练习册中逐项标注：

1. 原 prompt 中哪些句子只是态度或角色描述；
2. 缺少哪项会改变结果的上下文；
3. 哪项边界可防止真实风险；
4. 完成证据由谁、用什么方式检查；
5. 哪种情况应暂停询问。

重写后，先让 Codex复述理解和计划，不修改。比较它提出的问题是否更少、更关键，计划是否能对应到 Done when。

完整案例：从一句话到任务契约的四轮递进

Learn Prompting 页的强项不是给出一个“终极模板”，而是反复展示：只增加会改变结果的信息。下面用同一个问题观察四轮 brief 如何收敛。

第一轮：只有愿望

帮我优化这个后台页面。

Codex 不知道页面、受众、问题、允许改动范围和验收方式。它只能先猜“优化”是什么意思。

第二轮：加入结果和入口

优化 /admin/orders 的移动端可用性。相关入口在 app/routes/admin.orders.tsx。

现在有 Goal 和 Context，但仍可能重做桌面视觉、替换组件或只看代码不看真实页面。

第三轮：补上真正会改变方案的边界

目标：让 /admin/orders 在 390px 宽度下可以查看、筛选并打开订单。

上下文：
- 页面入口是 app/routes/admin.orders.tsx。
- ref/orders-mobile.png 是信息层级参考，不要求像素级复制。
- 桌面版已通过产品验收。

边界：
- 保留现有 Kumo 组件、文案和桌面布局。
- 不新增依赖，不改 API，不覆盖现有未提交文件。
- 先复现并定位溢出元素，再提出修改。

这时任务已经能安全开始调查，但“完成”仍可能由 agent 自己解释。

第四轮：让第三方能验收

完成条件：
- 390×844 下 document.scrollWidth 等于视口宽度。
- 筛选按钮、订单主字段和详情入口可由键盘到达。
- 1280×720 下表格列和侧栏位置不回归。
- 相关测试、类型检查和生产构建通过。
- 交付修改文件、两个视口结果、未验证项和未执行动作。

第四轮没有规定必须改哪一条 CSS，却把风险和证据写清楚了。这给 Codex 留下解决问题的空间，也给评审者留下拒绝错误结果的依据。

Context 账本：哪些材料该给，哪些不该给

在复杂任务里，把上下文分为四栏：

类型	例子	用法	常见错误
权威事实	API schema、产品决策、测试基线	决定“必须是什么”	把旧截图当当前规范
环境证据	报错、命令输出、DOM 测量	决定“现在发生什么”	只转述，不给原文
参考方向	竞品、设计图、示例文章	决定风格或选项	把参考误写成强制事实
未知问题	受众、兼容范围、发布权限	决定是否应暂停	让模型静默补齐

上下文不是附件数量竞赛。每份材料都应该能回答“它会改变哪项判断”。答不上来，就先不放进主任务。

Output 与 Done when 要同时存在

Output 说明交付形态，Done when 说明交付是否合格。以一份研究报告为例：

• Output：一页决策摘要、来源表、风险清单；
• Done when：每个数字可回到具体来源；事实与推断分开；冲突来源没有被静默合并；未确认项单列。

只写 Output，可能得到格式漂亮但事实错误的文件；只写 Done when，可能得到一堆检查记录而没有可用成品。

不同 Codex 场景怎样改变 prompt

解释代码库

重点给入口、关注的问题和解释层级，不要要求修改：

从 app/routes/orders.tsx 开始追踪一次订单查询。
说明每个模块的职责、校验发生在哪里、错误怎样返回。
列出你实际读取的文件，并标记仍未确认的外部依赖。
只读，不修改。

修复可复现 bug

重点给复现、反例和回归边界：

先按以下步骤复现“保存成功但刷新后丢失”。
保留 API shape；找到最小根因后加回归测试。
修复后重跑原复现和最近相关测试，不要只证明新测试通过。

更新文档

重点给事实来源和渲染检查：

更新认证故障排查章节。命令和配置键只能来自当前代码或官方文档。
检查所有链接，阅读渲染后的页面，并把高漂移信息标注校准日期。

三类任务的共同骨架相同，但 Context 和 Done when 不应复制粘贴。

Follow-up、Steer 与 Queue 的判断

后续消息有三种性质：

1. 纠偏当前方法：发现它正在重做桌面布局，立即 steer，指出观察、影响和应保留项；
2. 补充当前必需信息：刚找到真实报错或设计规范，steer 到当前运行；
3. 当前完成后的独立工作：例如“完成修复后再写发布说明”，queue 或另开任务。

一个好纠偏消息包含具体差距：

当前 diff 改了共享 Button，但问题只在订单表格。
请撤回共享组件改动，先用 DOM 尺寸证明溢出来源。
保留已经通过的移动端复现步骤，修复后重跑桌面回归。

不要用“继续”“再深入一点”代替差距描述。

故障诊所：prompt 失败不等于继续加字

现象	真正缺少的东西	修正方式
方案不断扩大	范围边界与停止条件	写清必须做、可选做、不要做
结果引用不存在的事实	权威来源与缺失处理	指定来源优先级，要求缺失时标记未知
Agent 按错误目录工作	环境入口	先报告 cwd、Git 状态和生效规则
测试通过但用户路径失败	行为验收	增加真实操作、视口和预期现象
每轮都推倒重来	Follow-up 太抽象	引用当前结果中的具体差距，只改一层

知识检查

问题一

“必须使用三个组件、每个文件不超过 100 行”属于好约束吗？

参考判断：只有当它来自真实架构规范时才是。否则它在没有证据的情况下预先规定实现，可能阻止更小、更合适的修复。

问题二

“请认真检查并确保没有问题”为什么不是 Done when？

参考判断：它没有检查对象、方法和可观察结果。应改为具体命令、用户动作、数据对账或 diff 审查。

问题三

什么时候应该停止继续补 prompt？

参考判断：当目标、权威上下文、关键边界和完成证据已经足够让任务安全推进时，先运行一轮，再根据真实差距 follow up。继续堆格式会增加噪声。

真正成熟的 prompt 不是看起来像规范，而是让执行者和验收者对结果、风险与停止点形成同一理解。若换一位同事仍能依据相同证据判断完成，它才成为可靠契约。

删掉形容词，留下可以检查的事实

回到你最近一次失败的提示词。把「专业」「高级」「最佳实践」先删掉，再补上文件、受众、不能改的东西和完成证据。

如果 Codex 能准确复述目标，提出的问题变少，而且每项检查都能对应 Done when，这份 brief 才真正开始工作。模板会换，任务契约的逻辑不会。

完成检查

• Goal 描述结果而不是空泛质量
• Context 提供权威入口和已知未知
• Output 或 Done when 明确成品与证据
• Boundaries 保护文件、事实、预算或外部动作
• 每项约束都对应真实风险
• Follow-up 指向可观察差距，没有重新打开范围