AI 学习指南
课程章节
本文目录
核心用法5

Codex Prompt 编写指南:目标、上下文、约束与验证

学习如何把模糊开发需求转化为 Codex 可执行、可验证、可审查的工程任务。

入门 20 分钟 16 2026-07-14 更新

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。

输出:
- 修改摘要;
- 文件清单;
- 命令与结果;
- 未验证项;
- 风险。

官方参考

资料核对日期:2026-07-14。

继续学习

$ start project✓ context loaded✓ task complete

claude-code

入门

Claude Code 从入门到实战

基于 Anthropic 官方文档,从安装、项目上下文和权限配置,到调试、测试与交付的完整入门课程。

78 分钟开始学习
$ start project✓ context loaded✓ task complete

cursor

开发

Cursor AI 开发指南

深入介绍 Cursor 的智能补全、Agent、规则配置和代码库理解能力。

36 分钟开始学习