参考资料

• OpenAI Codex 文档
• AGENTS.md 规范

Codex（02） - 如何写好 Codex 提示词

读完后，你应能完成以下任务：

• 绘制“Codex（02） - 如何写好 Codex 提示词 / 概念解释”的关键对象与数据流，解释“不是每次都要写满 6 块。”，并用源码位置、日志或 Trace 标注证据。
• 为“Codex（02） - 如何写好 Codex 提示词 / 使用示例”设计正常与异常输入，验证“这个提示词把“业务目标”和“工程边界”都写清楚了。”，输出首个偏差位置与回归测试结果。
• 实现“Codex（02） - 如何写好 Codex 提示词 / 示例 1：解释代码”的最小代码或配置，检验“这个提示词清楚地告诉 Codex：只解释，不改代码。”，输出命令、结果与 Diff，并说明不适用边界。

提示词不是魔法咒语，而是给 Codex 的任务单。写得好，它就能少猜、多做、少返工；写得差，它就会在错误方向上很努力。

从前端视角看，提示词有点像组件 props：你传进去的数据越清楚，组件渲染结果越稳定。Codex 的“props”就是目标、上下文、约束和验收标准。

一、概念解释

一个适合 Codex 的提示词通常有 6 块：

背景：为什么做这件事
目标：要完成什么
范围：允许看哪里、改哪里
约束：不能做什么、必须遵守什么
输出：最终要给你什么
验收：如何证明完成了

不是每次都要写满 6 块。小任务可以短，大任务要完整。

二、使用示例

2.1 示例 1：解释代码

请阅读 src/hooks/useRequest.ts，解释它的职责、核心流程和潜在风险。

输出要求：
- 先用 5 句话以内概括
- 再按“输入、状态、请求流程、错误处理”拆解
- 不要修改文件

这个提示词清楚地告诉 Codex：只解释，不改代码。

2.2 示例 2：修改功能

请给订单列表增加“按状态筛选”的功能。

范围：
- 页面：src/pages/orders
- 请求层：src/api/orders.ts
- 测试：已有测试文件优先复用

约束：
- 不引入新 UI 库
- 不改变现有订单接口字段名
- 保持移动端可用

验收：
- 筛选全部/待支付/已完成/已取消都能工作
- 补充必要测试
- 跑 npm test -- orders

这个提示词把“业务目标”和“工程边界”都写清楚了。

2.3 示例 3：先方案后执行

我想把 utils/date.ts 里的日期格式化逻辑整理一下。

请先做两件事：
1. 阅读当前调用点，说明哪些格式正在被使用。
2. 给出一个最小改动方案。

在我确认前不要修改文件。

当你不确定改动风险时，可以让 Codex 先分析，不急着写。

三、常见错误

3.1 错误 1：把心理预期藏起来

你心里想的是“别大改”，但提示词只写：

帮我优化一下这个模块。

Codex 可能会重构结构、改命名、移动文件。更好的说法：

请在不改变对外 API 和文件结构的前提下，提升这个模块的可读性。优先改局部重复和命名，不做大规模重构。

3.2 错误 2：没有说明输出格式

如果你要的是表格、PR 描述、代码审查清单、学习笔记，要直接写明格式。否则 Codex 会按它认为合适的方式输出。

3.3 错误 3：验收标准太虚

确保没问题。

这句话不可执行。更好的验收标准是：

运行 npm run lint 和 npm test。如果命令失败，请说明失败原因和你已经排查到的位置。

四、最佳实践

4.1 用“角色”限定视角

请以代码审查者的视角检查这个 PR，优先找 bug、边界条件和缺失测试。

角色不是为了装饰，而是让 Codex 采用合适的判断标准。

4.2 用“范围”降低误伤

只允许修改 src/components/SearchBox.tsx 和它的测试文件。

范围越清楚，越不容易出现无关改动。

4.3 用“禁止项”保留团队约束

不要引入 lodash，不要修改接口返回结构，不要改全局样式。

这类信息越早说越好。

4.4 大任务拆成多轮

推荐顺序：

1. 让 Codex 阅读并总结现状。
2. 让 Codex 给方案。
3. 确认方案后再改。
4. 让 Codex 自测并总结变更。

五、可复用提示词模板

请完成：[一句话目标]

背景：
- [为什么要做]

范围：
- [允许修改的目录/文件]

约束：
- [不能做什么]
- [必须遵守什么]

验收：
- [要运行的命令]
- [要产出的结果]

输出：
- 简要说明你改了什么
- 如果有风险，请列出来

六、本章小结

好提示词的本质是降低不确定性。你不需要写得很长，但要让 Codex 明确知道：要去哪、能走哪条路、不能碰什么、走到哪里算完成。

七、动手实践：02 prompt workflow

这个 demo 帮你练习“同一个需求，不同提示词会得到完全不同的结果”。

7.1 目录内容

• bad-prompt.md：模糊提示词。
• good-prompt.md：结构化提示词。
• login-form.tsx：示例代码。

7.2 使用方式

先试坏提示词：

codex exec --sandbox read-only --ask-for-approval never - < bad-prompt.md

再试好提示词：

codex exec --sandbox read-only --ask-for-approval never - < good-prompt.md

对比两次输出，观察结构化提示词带来的差异。

7.3 练习目标

• 体会目标、范围、约束、验收对结果的影响。
• 学会在提示词里明确“不要修改文件”或“可以修改文件”。

7.4 配套实践材料

以下材料已并入正文，便于阅读时直接对照和练习。

bad-prompt.md

帮我优化一下登录表单。

good-prompt.md

请阅读 `login-form.tsx`，只做分析，不修改文件。

目标：
- 找出这个登录表单在校验、可访问性、可维护性上的问题。

范围：
- 只分析 `login-form.tsx`。

输出：
- 先用 3 句话概括主要问题。
- 再按“校验 / 可访问性 / 可维护性”列出发现。
- 最后给一个最小修改方案。

约束：
- 不引入新的表单库。
- 不改变现有组件对外 props。

八、总结

• 使用示例：这个提示词把“业务目标”和“工程边界”都写清楚了。
• 常见错误：如果你要的是表格、PR 描述、代码审查清单、学习笔记，要直接写明格式。
• 示例 3：先方案后执行：当你不确定改动风险时，可以让 Codex 先分析，不急着写。
• 用“角色”限定视角：角色不是为了装饰，而是让 Codex 采用合适的判断标准。