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或 ShiftTab 让它输出执行计划确认后再执行。推荐流程先分析让它只读分析项目不修改文件。再计划输出变更文件、步骤、风险和验证方式。后执行确认计划后再改代码。最后验证跑测试、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. 修 Bugtext编辑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。