Codex 高质量提示词：让任务清晰、可执行、可验证#

Codex 提示词不需要堆砌角色设定。高质量任务通常只要回答四个问题：要实现什么、相关上下文在哪里、必须遵守什么、怎样算完成。信息越具体，Codex 越容易做出与你的代码库一致的改动。

一个实用结构#

可以用下面的顺序组织任务：

目标：修复结算页重复提交订单的问题。
上下文：重点检查 src/checkout 和现有 order service；先阅读相关测试。
约束：沿用现有状态管理，不新增依赖，不修改支付回调接口。
验证：补充重复点击测试，运行结算模块测试和类型检查。
交付：总结根因、改动文件、测试结果和仍未验证的风险。

这比“修复订单 bug”多不了多少文字，却明确了调查范围、禁止事项和验收证据。

先调查，再实施#

面对陌生代码或高风险问题，可以拆成两个阶段。第一阶段只读：

阅读上传模块和相关测试，解释大文件上传失败的调用链、最可能的三个原因和验证方法。不要修改文件。

确认分析后再进入实现：

按第二个原因修复。只修改上传客户端和对应测试，保持公共 API 不变。运行相关测试并报告结果。

这种分阶段方式能在错误方向产生大量改动前纠正理解，也方便你对技术方案做判断。

给出边界，而不是规定每一步#

有效约束通常是行为和范围，例如“不新增运行时依赖”“保持数据库 schema 不变”“只修改这个模块”。除非实现路径有强制要求，不必把每个函数名和每行代码都提前指定，否则 Codex 无法利用仓库中更合适的现有模式。

可以明确告诉它：

• 必须复用哪些组件、服务或错误类型。
• 哪些目录、生成文件和公共接口不能改。
• 是否允许安装依赖、访问网络或执行迁移。
• 兼容的运行时版本和浏览器范围。
• 输出应包含代码、文档还是仅分析报告。

把验证写进任务#

“完成实现”不是可验证标准。更好的标准是：

• 新增的测试覆盖成功和失败分支。
• 运行指定测试、lint、类型检查或构建命令。
• 页面在给定桌面和移动端宽度下没有溢出。
• API 保持原响应结构，新增字段有向后兼容默认值。
• 对无法运行的检查明确说明原因。

如果项目没有测试，也可以要求 Codex 提供最小复现命令、手动检查步骤或构建产物证据。

常用任务模板#

修复缺陷#

复现并修复 [现象]。先定位根因，再添加能复现问题的测试。
保持 [接口/行为] 不变，不修改 [目录]。运行 [测试命令]，最后说明根因和验证结果。

代码审查#

审查当前分支相对 main 的改动。优先找行为错误、数据风险、并发问题和缺失测试。
按严重程度列出问题，给出文件和行号；不要为了风格偏好提出重构。

实现功能#

在 [模块] 增加 [能力]。先阅读 [参考实现] 并复用现有模式。
约束：[限制]。验收：[测试和可观察结果]。完成前运行 [命令]。

长任务及时校准#

任务进行中，可以要求 Codex 在关键节点停下总结：它找到了什么、准备修改哪些文件、有什么不确定性。需求发生变化时应直接说明新要求是否替代旧要求，不要让互相冲突的指令同时留在上下文里。

跨项目长期有效的规则更适合写进 AGENTS.md，单次任务的特殊要求继续放在提示词中。两者分工清楚，提示词会更短，也不容易遗漏团队约定。