一、先纠正一个误区：Prompt 不是“咒语”

很多人把 Prompt 当成玄学：好像只要套一个“神级提示词”，Codex 就会自动完美完成任务。

实际不是这样。

Codex 是一个能读文件、改文件、运行命令、持续执行任务的 coding agent。你给它的 Prompt，本质上是在给一个工程协作者布置任务。

所以 Prompt 的关键不是华丽，而是清楚：

你要它做什么？ 它应该看哪些上下文？ 哪些地方不能乱动？ 怎样才算完成？

OpenAI Codex 官方最佳实践也强调，新手写 Prompt 时，最好包含四类信息：Goal、Context、Constraints、Done when。翻译成中文就是：目标、上下文、约束、完成标准。

这篇文章所有模板都围绕这四个核心展开。

二、万能 Prompt 骨架

先给你一个通用模板。后面所有场景都可以从它变形。

请先阅读当前项目结构，然后完成下面的任务。 【目标】 我要你完成：{具体目标} 【上下文】 相关文件/目录：{文件路径、目录、模块名} 当前问题/背景：{一句话说明} 已有约定：{技术栈、代码风格、业务规则} 【约束】 1. 不要修改：{不能动的文件/模块} 2. 不要改变：{接口形状、数据结构、页面布局、对外行为} 3. 如果需要新增依赖，请先说明原因并等待确认。 4. 保持改动范围尽量小。 【执行方式】 1. 先分析相关文件。 2. 再给出计划。 3. 如果计划涉及较大改动，先停下来让我确认。 4. 确认后再实现。 【完成标准】 1. {测试通过 / 构建成功 / 页面可预览 / Bug 不再复现} 2. 最后说明修改了哪些文件。 3. 如果有风险或未验证项，请明确列出。

这个模板看起来长，但它解决了三个核心问题：

问题	模板怎么解决
Codex 理解错需求	用“目标 + 上下文”减少猜测
Codex 改太多	用“约束 + 最小改动”控制范围
结果不好验收	用“完成标准”定义交付结果

三、模板 1：让 Codex 读懂项目

新手不要一上来就让 Codex 改项目。面对陌生代码库，先让它解释。

适用场景：

• 刚接手一个项目
• 看不懂某个模块
• 想知道请求流程
• 想找出相关文件

Prompt 模板：

请先阅读当前项目结构，帮我理解这个项目。 重点关注： 1. 项目主要技术栈是什么？ 2. 入口文件在哪里？ 3. 主要目录分别负责什么？ 4. 如果我要修改首页/登录页/接口请求，应该看哪些文件？ 5. 有哪些新手容易误改的地方？ 要求： 只做分析，不要修改任何文件。 最后用“目录职责表 + 修改入口建议 + 风险提醒”的格式输出。

如果你已经知道具体文件，可以这样写：

请阅读 @src/router.ts @src/pages/Login.tsx @src/api/user.ts。 帮我解释登录流程： 1. 用户点击登录后，请求从哪里发出？ 2. token 保存在哪里？ 3. 登录成功后跳转逻辑在哪里？ 4. 如果我要新增验证码，应该改哪些文件？ 只分析，不改代码。

这个模板的重点是：先建立地图，再开始行动。

四、模板 2：新增功能，但不让它乱改

新增功能最容易失控。你一句“帮我加个功能”，Codex 可能会改路由、改样式、改依赖，甚至顺手重构一堆东西。

所以新增功能要写清楚范围。

Prompt 模板：

请为当前项目新增一个功能：{功能名称}。 【目标】 实现：{用户能看到或操作什么} 【范围】 只允许修改： 1. {文件或目录 1} 2. {文件或目录 2} 【约束】 1. 不要修改接口返回结构。 2. 不要改动登录、权限、支付相关逻辑。 3. 不要引入新依赖，除非你先说明原因并等待我确认。 4. 保持现有代码风格和组件写法。 【执行方式】 先阅读相关文件并给出计划。 计划里请列出： 1. 要修改哪些文件 2. 为什么要改 3. 如何验证 我确认计划后，你再开始实现。

适合复制的具体例子：

请为当前项目首页新增一个“学习路线”模块。 要求： 1. 展示 4 个步骤：安装 Codex、创建项目、写 Prompt、验收结果。 2. 保持当前页面的视觉风格。 3. 只修改首页相关文件和样式文件。 4. 不要改路由、登录、接口请求。 5. 不要引入新依赖。 请先阅读相关文件并给出计划，列出你准备修改的文件。 我确认后再开始实现。

这个写法会显著减少“顺手大改”的概率。

五、模板 3：修 Bug，重点是复现步骤

很多人修 Bug 时只会说：

这个报错修一下。

这对 Codex 来说信息太少。稳定的修 Bug Prompt，应该包含五件事：

信息	作用
Bug 现象	当前哪里不对
复现步骤	如何稳定看到问题
期望行为	修好后应该怎样
约束	哪些地方不能改
验证方式	修完怎么证明有效

Prompt 模板：

请帮我修复下面这个 Bug。 【Bug 现象】 {描述当前错误表现} 【复现步骤】 1. {第一步} 2. {第二步} 3. {第三步} 【期望行为】 {修复后应该是什么结果} 【约束】 1. 不要改变现有 API 形状。 2. 保持修复范围最小。 3. 如果发现需要较大重构，请先说明并等待确认。 4. 如果可行，请补一个回归测试。 【验证】 请先尝试复现问题，再定位原因。 修复后运行相关测试，并按复现步骤重新验证。 最后报告： 1. 根因是什么 2. 修改了哪些文件 3. 跑了哪些验证 4. 是否还有残留风险

具体例子：

请帮我修复设置页保存失败的问题。 【Bug 现象】 点击“保存”后页面提示保存成功，但刷新后昵称又恢复成旧值。 【复现步骤】 1. 运行 npm run dev 2. 打开 /settings 3. 修改昵称 4. 点击保存 5. 刷新页面 【期望行为】 刷新后仍显示新昵称。 【约束】 1. 不要改变后端 API 的请求和返回结构。 2. 不要改登录和权限逻辑。 3. 保持修复范围最小。 4. 如果能补测试，请补一个最小回归测试。 请先复现并定位原因，再给出修复计划。

注意：复现步骤越具体，Codex 越不容易“猜着修”。

六、模板 4：写测试

写测试时，不要只说“帮我加测试”。你应该告诉它测什么函数、覆盖哪些边界、参考哪个测试风格。

Prompt 模板：

请为 {函数名/组件名/模块名} 添加测试。 【上下文】 目标文件：{文件路径} 参考测试：{已有测试文件路径} 【测试范围】 请覆盖： 1. 正常输入 2. 空值/边界值 3. 异常输入 4. 关键业务规则 【约束】 1. 遵循项目现有测试框架和命名风格。 2. 不要为了测试修改生产代码，除非确实需要；如果需要，请先说明。 3. 不要引入新的测试库。 【完成标准】 1. 新增测试能运行。 2. 相关测试通过。 3. 最后说明测试覆盖了哪些场景。

具体例子：

请为 @src/utils/formatDate.ts 添加单元测试。 要求： 1. 参考 @src/utils/__tests__/formatCurrency.test.ts 的写法。 2. 覆盖正常日期、空字符串、非法日期、时区边界。 3. 不要修改 formatDate 的对外 API。 4. 添加测试后运行相关测试命令。 5. 最后说明覆盖了哪些 case。

写测试类任务非常适合新手练 Codex，因为验收方式清晰：测试要么过，要么不过。

七、模板 5：安全重构

重构是最容易“越改越大”的任务。

不要说：

帮我重构一下这个项目。

应该说：

只重构这个文件，保持行为不变。

Prompt 模板：

请对 {文件/模块} 做一次安全重构。 【目标】 提高代码可读性和可维护性，但保持外部行为完全不变。 【范围】 只允许修改： {文件路径} 【约束】 1. 不要改变导出的函数名、参数、返回结构。 2. 不要改变业务行为。 3. 不要引入新依赖。 4. 不要顺手重构无关文件。 5. 如果你认为需要扩大范围，请先说明原因并等待确认。 【执行方式】 1. 先解释当前代码的问题。 2. 给出重构计划。 3. 重构后运行现有测试。 4. 如果没有测试，请说明可手动验证的方式。 【完成标准】 代码更清晰，行为不变，相关检查通过。

具体例子：

请安全重构 @src/utils/dateRange.ts。 目标： 让代码更容易阅读，减少重复判断。 约束： 1. 不要改变任何导出函数的名称、参数和返回值。 2. 不要修改调用方。 3. 不要引入新依赖。 4. 保持行为完全一致。 请先列出当前代码的可读性问题和重构计划，我确认后再改。 完成后运行相关测试。

八、模板 6：文档和交付物

Codex 不只适合写代码，也适合生成 README、教程、验收清单、迁移说明。

Prompt 模板：

请为当前项目生成一份 {文档类型}。 【目标读者】 {新手开发者 / 项目维护者 / 产品同学 / 面试官} 【文档内容】 请包含： 1. 项目简介 2. 技术栈 3. 目录结构 4. 本地运行方式 5. 常见问题 6. 后续开发建议 【约束】 1. 不要编造不存在的功能。 2. 先读取项目文件，再写文档。 3. 命令必须以项目实际 package.json / 配置文件为准。 4. 如果无法确认，请标注“待确认”。 【完成标准】 生成 README.md，并说明信息来源。

这个模板里最重要的一句是：

不要编造不存在的功能。

写文档时，AI 很容易根据常见项目结构脑补内容。你要明确要求它从项目文件中取证。

九、让 Codex 少乱改：一定要写“先计划”

如果任务复杂、范围不明确，建议把这段放进 Prompt：

请先阅读相关文件并给出计划。 未经我确认，不要开始修改。 计划中请列出： 1. 你理解的目标 2. 准备修改的文件 3. 每个文件为什么要改 4. 可能的风险 5. 验证方式

然后你可以根据计划继续追问：

计划里的第 3 项范围太大，请缩小到只修改首页组件和样式文件。

或者：

不要改数据结构。请重新给一个不改变接口的方案。

这比事后发现它改了一堆文件再回滚，要舒服得多。

十、让 Codex 稳定交付：把验证写进 Prompt

Codex 的优势之一是它可以运行命令、读取输出、继续修正。

但前提是：你要告诉它怎么验证。

常见验证写法：

完成后请运行： 1. npm run lint 2. npm test 3. npm run build 如果命令失败，请先阅读错误信息，判断是否由本次改动引起。 如果是，请修复并重新运行。 如果不是，请明确说明失败原因和残留风险。

如果是前端页面：

完成后请启动本地预览。 检查页面是否能打开，移动端是否有明显溢出。 最后告诉我预览地址和验证结果。

如果是 Bug 修复：

修复后请重新执行复现步骤。 只有当 Bug 不再复现，才算完成。

这就是让 Codex 稳定交付的关键：不要只要求“做完”，要定义“怎样证明做完”。

十一、反例改写：这些模糊 Prompt 不要再用了

反例 1：帮我优化一下项目

更好的写法：

请先分析首页性能问题。 只检查图片体积、首屏资源和无用依赖。 先给出问题清单和优化计划，不要修改代码。

反例 2：这个报错修一下

更好的写法：

请修复下面的报错。 报错信息：{粘贴完整报错} 复现步骤：{一步步写清楚} 期望结果：{修好后应该怎样} 约束：不要改变 API 形状。 验证：修完后运行 npm test，并报告结果。

反例 3：帮我重构一下

更好的写法：

请只重构 @src/utils/date.ts。 目标是减少重复代码，提高可读性。 不要改变导出函数、参数和返回值。 不要修改调用方。 完成后运行相关测试。

反例 4：页面做得好看一点

更好的写法：

请把登录页调整成简洁商务风。 要求： 1. 保留现有输入字段和提交逻辑。 2. 不改接口请求。 3. 适配移动端。 4. 不引入新 UI 库。 5. 完成后提供修改文件清单。

十二、长任务怎么办？用 Plan / Goal / AGENTS.md

如果任务很长，比如迁移技术栈、改造多个模块、长期维护项目，只靠一条 Prompt 会很吃力。

这时可以用三种方式增强稳定性。

1. 先用 Plan

适合需求模糊、改动较大的任务。

请先进入规划模式。 你需要先采访我，问清楚需求、范围、验收标准。 在我确认计划前，不要修改文件。

2. 用 Goal 定义长期目标

适合多步骤任务。

目标：把当前项目的首页性能优化到首屏 1 秒内可交互。 完成标准： 1. 找出主要性能瓶颈。 2. 做最小必要修改。 3. 运行构建。 4. 给出优化前后的对比和残留风险。

3. 用 AGENTS.md 固化项目规则

如果你发现自己每次都要重复说：

• 不要改接口
• 不要引入依赖
• 提交前跑测试
• 保持某种代码风格

那就可以把这些规则写进 AGENTS.md。

适合写入 AGENTS.md 的内容：

# 项目规则 - 修改前先阅读相关文件。 - 默认不引入新依赖。 - 不要修改 API 返回结构，除非任务明确要求。 - 前端改动完成后运行 npm run build。 - 测试相关改动完成后运行 npm test。 - 最终回复必须包含：修改文件、验证命令、风险说明。

这相当于给 Codex 一份项目协作说明书。

十三、我的推荐使用顺序

如果你是新手，我建议按这个顺序练：

阶段	练习目标	推荐模板
第 1 步	让 Codex 读懂项目	项目解释模板
第 2 步	做一个小功能	新增功能模板
第 3 步	修一个可复现 Bug	Bug 修复模板
第 4 步	补测试	测试模板
第 5 步	小范围重构	安全重构模板
第 6 步	写 README	文档模板
第 7 步	固化规则	AGENTS.md

每一步都记住一个原则：

先小任务，再复杂任务。 先可验证，再追求自动化。 先看 Diff，再接受结果。

十四、总结

想让 Codex 少犯错、少乱改、稳定交付，不靠神奇提示词，而靠工程化表达。

你要把任务说成这样：

目标明确 上下文明确 约束明确 完成标准明确

真正好用的 Prompt，不是“请你扮演世界顶级程序员”，而是：

请修改这个文件，解决这个问题，不要动那些模块，完成后跑这些验证。

最后送你一句最实用的判断标准：

如果你自己都无法判断 Codex 怎样才算完成，那它大概率也会交付一个不好验收的结果。