Codex 提示词优化教程：用四要素把模糊需求变成可执行任务

写 Codex 提示词，核心不是堆"请认真思考""你是一个专家"这类客套话，而是把任务写成可执行、可验证、可回滚的工程指令。好的提示词应该像一份精简的 GitHub Issue：目标清楚、范围锁死、约束明确、验收可跑。

一、先掌握四要素：Goal / Context / Constraints / Done when

每次让 Codex 干活前，先检查提示词是否覆盖这四件事。

表格

下载为表格

导出为图片

要素	作用	写法要点
Goal 目标	告诉 Codex 要得到什么结果	用结果描述，而不是描述过程
Context 上下文	让它知道改哪里、参考什么	用 @文件、目录、错误日志、现有实现
Constraints 约束	防止它乱改、乱加依赖	明确不改什么、不破坏什么
Done when 完成条件	判断任务是否真正完成	测试、lint、类型检查、接口返回格式

示例：

text

编辑

1Goal: 为支付回调接口增加幂等重试逻辑
2Context: 修改 services/webhooks/*，参考 api/auth.ts 的中间件写法
3Constraints: 不改变现有响应结构；不新增第三方依赖；保持数据库事务边界
4Done when: npm test webhook 通过；npm run typecheck 通过；diff 中无多余文件

二、范围要锁死：用 @文件、路径和"不改什么"

Codex 是代码代理，不是读心工具。范围越模糊，越容易改错文件。

差的写法：

text

编辑

1帮我修一下登录相关的 bug。

好的写法：

text

编辑

1只看 @src/pages/login.tsx 和 @src/hooks/useAuth.ts
2修复登录态时序 bug，不要改其他文件。

约束里最好显式写出"不改什么"，例如：

• 不改 API 响应字段
• 不改数据库表结构
• 不新增全局状态
• 不修改已有测试用例的断言
• 不引入未授权的第三方库

三、复杂任务先计划，不要一上来生成代码

涉及多文件、跨模块、重构、性能优化或需求不明确时，不要直接让它改代码。可以先用 /plan 或 Shift+Tab 让它输出执行计划，确认后再执行。

推荐流程：

1. 先分析：让它只读分析项目，不修改文件。
2. 再计划：输出变更文件、步骤、风险和验证方式。
3. 后执行：确认计划后再改代码。
4. 最后验证：跑测试、lint、类型检查，并审查 diff。

如果需求本身模糊，可以让 Codex 先提问澄清，而不是直接猜。

四、调试提示词：给复现步骤、错误日志和期望行为

修 bug 时，不要只说"这里报错了"。应该提供：

• 触发条件
• 复现步骤
• 完整错误堆栈
• 实际行为
• 期望行为
• 相关文件路径

示例：

text

编辑

1背景：用户会话过期后调用 POST /api/login
2现象：返回 500，日志显示 TypeError: Cannot read properties of undefined
3复现步骤：
41. 清除本地 token
52. 刷新页面
63. 重新提交登录表单
7期望：返回 401 或重新登录成功，不抛 500
8相关文件：@src/api/login.ts @src/middleware/auth.ts

同一个问题修正超过两次，建议开新会话，避免上下文污染。

五、用 AGENTS.md 固化规则，减少重复提示

高频规则不要每次写在提示词里，应放进项目根目录的 AGENTS.md。

建议包含：

• 技术栈与目录结构
• 启动、构建、测试、lint 命令
• 代码风格、命名规范、注释规范
• 禁止项，例如禁止 any、禁止全局变量
• PR 提交前的检查步骤
• 验收标准

但 AGENTS.md 不宜过长，建议控制在 100 行以内，硬上限 300 行；能从代码推断的内容不要写进去。

六、几个可直接复用的模板

1. 通用开发任务

text

编辑

1目标：{一句话结果}
2相关文件：@{文件/目录}
3约束：不改变现有 API 响应格式；不新增未授权依赖；保持现有测试通过
4完成标准：运行 {测试/lint/类型检查命令} 全部通过；diff 中只包含预期文件
5输出：先列出变更文件，再给出代码变更，最后说明风险点

2. 修 Bug

text

编辑

1背景：{出现问题的场景}
2现象：{实际发生了什么}
3复现步骤：{1, 2, 3}
4期望行为：{应该发生什么}
5相关文件：@{文件}
6约束：不要改动无关模块
7完成标准：复现步骤不再触发错误；相关测试通过

3. 重构任务

text

编辑

1目标：重构 {模块}，提升可读性和可维护性
2范围：@{目录}
3约束：不改变外部行为；不修改公共 API；保持测试全部通过
4计划：先输出重构方案，包括拆分文件、函数职责和迁移步骤
5完成标准：重构后测试、lint、类型检查通过，diff 无逻辑变更

4. 写测试

text

编辑

1目标：为 {函数/模块} 补充单元测试
2参考：@{现有测试文件}
3约束：遵循现有测试风格；不修改被测函数逻辑
4完成标准：新增测试覆盖正常路径、边界情况和错误路径；npm test 通过

七、常见坑

• 不要写"帮我优化一下""修一下这个 bug"这种空泛指令。
• 不要让它全仓库乱找，优先用 @文件 锁定范围。
• 不要一次塞入过多任务，拆成小步更容易审查。
• 不要只看代码是否生成，必须跑测试、lint 和类型检查。
• 不要过度依赖对话记忆，关键规则写进 AGENTS.md。