Codex Prompt 编写指南:目标、上下文、约束与验证
Codex 提示词的重点不是“写得像咒语”,而是让工程任务具备足够信息。一个高质量任务通常包含:
目标 + 上下文 + 约束 + 验证 + 输出格式
1. 目标:明确最终行为
模糊目标:
优化登录页面。
可执行目标:
降低登录页面首次加载时的布局抖动,并把密码错误提示移动到密码输入框下方。
更完整:
目标:
1. 消除 Logo 加载后导致的布局位移;
2. 密码错误时在密码输入框下显示错误文本;
3. 保持现有 API 和路由不变。
目标应该描述用户能观察到的结果,而不是只描述“写什么代码”。
2. 上下文:告诉 Codex 从哪里开始
上下文可以是:
- 文件路径;
- 函数或类名;
- 错误日志;
- 复现步骤;
- 截图或设计图;
- Issue、PRD 或接口文档;
- 当前分支和基础分支。
示例:
相关位置:
- 页面:src/pages/login.tsx
- 表单组件:src/components/LoginForm.tsx
- API:src/api/auth.ts
- 测试:tests/login.spec.ts
如果不知道位置,可以要求 Codex先搜索:
先定位登录状态的写入和读取链路,列出相关文件和调用关系。确认后再提出修改方案。
IDE 扩展通常自动包含打开文件和选中代码;CLI 中更应该明确写出路径,或使用界面提供的文件引用功能。
3. 约束:明确不能破坏什么
常见约束:
- 不修改公共 API;
- 不改变数据库结构;
- 不新增生产依赖;
- 不修改生成文件;
- 不进行与任务无关的重构;
- 保持现有浏览器兼容范围;
- 保持旧配置文件可用;
- 只修改指定目录。
约束越具体,越能减少“顺便重构”和范围膨胀。
4. 验证:定义怎样算完成
错误写法:
修改后确保没有问题。
正确写法:
验证:
- 运行 pnpm lint;
- 运行 pnpm typecheck;
- 运行 pnpm test -- login;
- 手工说明成功登录、密码错误、网络失败三个分支;
- 如果任何命令无法运行,说明原因,不要声称任务完全通过。
当项目没有现成测试时,可以要求 Codex先找到最接近的验证方式,而不是虚构测试命令。
5. 输出格式:让结果容易审查
推荐固定结尾:
最后按以下格式输出:
1. 修改摘要;
2. 修改文件;
3. 实际执行的验证命令和结果;
4. 未验证项;
5. 风险和后续建议。
对于分析任务:
输出必须包含:
- 结论;
- 证据文件和行号;
- 影响范围;
- 推荐方案;
- 不推荐方案及原因。
6. Bug 修复 Prompt 模板
目标:
修复“保存成功提示出现,但刷新后数据未保存”的问题。
复现步骤:
1. 打开 /settings/profile;
2. 修改昵称;
3. 点击保存;
4. 页面显示成功;
5. 刷新后恢复旧值。
预期行为:
保存成功后,刷新页面仍显示新昵称。
限制:
- 不改变 API 响应结构;
- 保持修改最小;
- 不新增依赖;
- 尽量添加回归测试。
执行方式:
先复现问题,定位写入链路,再提出修复。修复后重新执行复现步骤,并运行 Lint 和最小相关测试。
7. 新功能 Prompt 模板
目标:
为订单列表增加“导出 CSV”功能。
范围:
- 在现有筛选栏右侧增加按钮;
- 导出当前筛选条件下的全部订单;
- 文件名格式为 orders-YYYY-MM-DD.csv;
- 空数据时禁用按钮。
相关位置:
- src/pages/orders/index.tsx
- src/api/orders.ts
- src/components/OrderFilters.tsx
限制:
- 复用现有 Button 和 Toast;
- 不改变列表 API;
- 不新增 CSV 依赖,优先使用简单序列化;
- 正确处理逗号、双引号和换行。
验证:
- 添加序列化单元测试;
- 添加按钮启用/禁用测试;
- 运行 lint、typecheck 和相关测试。
8. 重构 Prompt 模板
/plan
目标:
拆分 auth.ts 中的 Token 解析、Session 加载和权限判断职责。
要求:
- 不改变用户可见行为;
- 公共导出保持兼容;
- 现有调用方分阶段迁移;
- 每个里程碑都可独立测试和提交。
计划必须包含:
- 当前依赖关系;
- 目标模块结构;
- 每个里程碑修改文件;
- 测试和回滚方式;
- 潜在循环依赖风险。
先只输出计划,不修改代码。
9. UI 实现 Prompt 模板
使用附加截图实现设置页。
技术约束:
- Next.js App Router;
- TypeScript;
- 复用 components/ui 下现有组件;
- 不引入新 UI 库;
- 支持 375px 和 1440px;
- 保留键盘焦点和表单标签。
截图未表达的交互:
- 保存中按钮禁用;
- 保存成功显示 Toast;
- 失败显示字段或全局错误;
- 离开未保存页面时提示。
先分析现有页面风格和可复用组件,再修改代码。完成后启动开发服务器并说明查看路径。
只给截图而不写交互与技术约束,通常会得到“视觉接近但工程不一致”的实现。
10. 测试 Prompt 模板
为 calculatePrice 添加测试,先不要修改实现。
覆盖:
- 普通价格;
- 折扣为 0;
- 最大折扣;
- 小数舍入;
- 非法负数输入;
- 空优惠券;
- 税费与折扣顺序。
要求:
- 使用项目现有测试框架;
- 遵循同目录测试风格;
- 不为了让测试通过而改变生产代码;
- 运行最小测试并汇报结果。
11. 代码审查 Prompt 模板
/review
重点检查:
- 逻辑错误和边界条件;
- 并发或竞态;
- 身份认证与权限绕过;
- 数据兼容性;
- 缺失的回归测试。
只报告可以从 Diff 和代码上下文证明的问题。按严重级别排序,每条包含文件、位置、触发条件和建议修复。
12. 分阶段提示,而不是一次写完
大型任务推荐拆为:
第一步:理解
先分析订单导出相关的数据流、分页和筛选逻辑,不修改代码。
第二步:计划
基于分析给出最小实现计划,列出修改文件和测试方案。
第三步:实现
实现计划中的第一阶段,只完成导出序列化函数和测试。
第四步:集成
将导出能力接入列表页面,保持 API 不变。
第五步:验证和审查
运行相关检查,然后审查本次 Diff,修复确认存在的问题。
13. 如何要求 Codex提供证据
对于项目分析:
所有结论都要引用具体文件路径、函数名或命令输出。不能确认的内容标记为“未确认”。
对于 Bug:
先证明根因:给出触发路径、关键状态变化和为什么现有测试没有发现它。
对于性能:
不要只凭代码猜测。先找现有基准、日志或可执行的测量方法,再提出优化。
14. 不要把实现方案锁得太死
提示词应明确目标和限制,但不必总是指定每一行实现。例如:
必须用 useMemo 修复性能。
可能把 Codex引向错误方向。更好的写法:
定位重复渲染原因,使用项目现有模式修复。若建议使用 memoization,请说明测量依据和失效条件。
15. 一份通用终极模板
目标:
<用户可观察到的最终结果>
背景与复现:
<当前行为、错误、截图、日志或需求来源>
相关位置:
- <文件/目录/函数>
范围:
- <需要完成的内容>
限制:
- <不能修改的接口、依赖、目录、行为>
验证:
- <具体命令>
- <手工验收步骤>
执行顺序:
1. 先阅读并确认相关代码;
2. 必要时提出计划;
3. 实现最小改动;
4. 运行验证;
5. 审查 Diff。
输出:
- 修改摘要;
- 文件清单;
- 命令与结果;
- 未验证项;
- 风险。
官方参考
- https://learn.chatgpt.com/docs/prompting
- https://learn.chatgpt.com/guides/best-practices
- https://learn.chatgpt.com/docs/codex/ide
- https://learn.chatgpt.com/docs/code-review
资料核对日期:2026-07-14。