Codex Prompt 骨架：目标、上下文、约束和验收标准

这是 Codex 系列的第 5 篇。

上一篇我把重点放在“先让 Codex 读懂项目”。因为很多 Prompt 失败，并不是句子写得不够漂亮，而是 Codex 进入任务时缺少项目地图：它不知道目录怎么组织、哪些文件真的相关、什么命令能验证、哪里不能碰。

这一篇继续往下走：当项目地图已经有了，怎样把它变成一条能执行、能验证、能复盘的 Codex Prompt？

我会把它拆成四块：

Goal：目标
Context：上下文
Constraints：约束
Done when：验收标准

这不是我发明的玄学框架。OpenAI Codex 官方最佳实践里也把这四类信息作为一个好任务 Prompt 的默认结构：你要改什么、哪些上下文重要、需要遵守什么限制、怎样算完成。我的理解是：这四块不是为了让 Prompt 看起来专业，而是为了把“我脑子里的预期”变成 Codex 可以检查的任务契约。

整理日期：2026-07-05。本文涉及 Codex Prompt、上下文、计划优先、AGENTS.md 和 Skill 的内容，主要参考 OpenAI Codex 官方文档、CodexGuide、bozhouDev/codex-orange-book，再结合这个博客项目的实际使用经验整理。

这篇解决什么问题

读完这篇，你应该能带走四样东西：

产物	用来解决什么
四段式 Prompt 骨架	把模糊需求拆成 Codex 能执行的任务
常见任务模板库	修 bug、加功能、代码 review、写文章、资料调研都能直接改
反例改写方法	看到“帮我优化一下”时，知道要补什么
30-60 分钟练习	用自己的项目跑一遍，从 Prompt 到验收闭环

这一篇不会追求“万能 Prompt”。我现在越来越不相信万能 Prompt。真正有用的是一套小而稳定的写法：每次任务不同，但你都知道要交代目标、上下文、约束和验收。

怎么使用这篇

这篇比较长，不建议一次性把所有模板都背下来。更适合把它当成一本小手册：

你现在的状态	建议先看哪里
不知道 Prompt 为什么失控	先看 1-5 节，理解四块骨架
正在修 bug 或加功能	直接跳到 7-8 节复制模板
想让 Codex 做 review	看第 9 节，区分合并前 review 和学习型 review
想写文章或做资料调研	看第 10-12 节，把输出先变成 research note 或发布检查
想长期复用	看第 14 节，判断该放 Prompt、AGENTS.md 还是 Skill

这一篇只解决“单次任务怎么说清楚”。下一篇会专门讲 AGENTS.md，也就是哪些规则不该每次写进 Prompt，而应该变成项目长期说明。把这两个边界分清楚，后面用 Codex 会轻很多。

1. 好 Prompt 不是写得长，而是能落地

很多人刚开始用 Codex，会自然把它当成一个更强的聊天机器人，于是 Prompt 也写成聊天式的：

帮我优化一下博客后台，感觉分类选择有点问题。

这句话有用吗？有一点。Codex 大概率会去看后台代码，也可能找到分类下拉框的状态问题。

但它有几个隐含空白：

空白	Codex 需要自己猜什么
“优化”是什么意思	是修 bug、改样式、提性能，还是重构交互
“后台”在哪里	是源码后台、线上后台、CMS，还是数据库管理界面
“分类选择有点问题”是什么问题	没选项、选不上、保存失败、刷新丢失，还是显示错误
可以改哪些文件	前端组件、API、数据库 schema、部署脚本是否都能碰
怎样算修好	页面能打开就行，还是需要构建、测试、线上验证

AI Agent 的能力越强，这种空白越危险。因为它不是只会回答一句“我不确定”。它可能会读文件、改代码、跑命令、生成迁移、甚至尝试发布。你的 Prompt 如果没有边界，它就会用自己的概率判断补齐边界。

所以我更喜欢把 Prompt 看成一个小型工作单，而不是一段请求。

一条好的 Codex Prompt 至少要回答四个问题：

问题	对应 Prompt 块
这次到底要完成什么？	Goal
哪些信息是任务现场？	Context
哪些事情不能做或要按规矩做？	Constraints
什么证据说明任务完成？	Done when

这四块写清楚后，Prompt 不一定很长。很多小任务用 10 行就够了。但这 10 行要有骨架。

2. Goal：先写结果，不要先写做法

我经常看到这样的 Prompt：

帮我把这个组件重构一下。

问题是，“重构”是做法，不是目标。Codex 看到“重构”，会自然开始改结构、抽组件、整理命名。最后代码可能更像它喜欢的样子，但不一定解决你的真实问题。

Goal 应该尽量写成用户可见、测试可见或评审可见的结果。

不够好的 Goal	更好的 Goal
重构登录页	登录页在移动端不再溢出，保持现有视觉风格，不改变登录 API
优化文章	把这篇文章整理成技术笔记风长文，保留个人判断，加入可执行模板
修一下分类	后台文章列表的分类下拉框显示已有分类，并能正确保存到当前文章
加一个导出	在订单列表增加 CSV 导出按钮，导出当前筛选条件下的结果

Goal 最好包含三个层次：

我要改变什么对象？
希望它变成什么状态？
这次不打算解决什么？

比如这个博客后台的任务，可以这样写：

目标：
修复后台文章列表里的分类选择问题。现在下拉框显示为“未分类”，展开后没有可选分类。
我希望它能加载当前数据库里的分类，选择后保存到文章，并且不影响文章列表的其他操作。

这里面有几个信号：

• 对象是“后台文章列表里的分类选择”
• 现象是“显示未分类，展开没有可选分类”
• 期望是“加载分类、选择、保存”
• 边界是“不影响文章列表其他操作”

这比“分类有问题”要稳定很多。

Goal 不要夹太多任务

还有一种常见问题，是把多个任务塞进一个 Goal：

帮我修复后台分类问题，顺便优化一下界面，再把文章发布流程改顺一点，最后检查一下 SEO。

这不是一个任务，而是一串小项目。Codex 可以做，但你会很难 review。它改了 12 个文件后，你不知道哪一处是分类修复、哪一处是界面优化、哪一处是 SEO。

我现在一般会把这种需求拆成：

1. 修复分类下拉框，完成后验证保存行为。
2. 单独 review 后台文章列表的交互问题，只输出建议，不改代码。
3. 根据建议选择一两个点实施。
4. 最后再做 SEO 和元信息检查。

小任务不是效率低。小任务让 Codex 更容易验证，也让人更容易判断它是否真的做对了。

3. Context：不要把所有资料都扔进去，而是给任务现场

Context 是很多人最容易误解的一块。

上下文不是“越多越好”。上下文的作用是让 Codex 少猜，而不是把它淹没。你给它 10 个无关文件、5 段历史聊天、3 张模糊截图，它也能读，但它需要自己判断哪些重要，反而可能把注意力带偏。

我会把 Context 分成五类：

类型	例子	什么时候给
入口文件	src/app/admin/posts/page.tsx、routes/article.ts	你知道任务从哪里开始
现象证据	报错、截图、复现步骤、URL	bug、样式、发布问题
项目地图	上一篇文章里的只读扫描报告	陌生项目、旧项目、跨模块任务
业务规则	分类只能一个、标签可多个、草稿不展示	数据和内容规则容易误解时
外部资料	官方文档、issue、设计稿、参考文章	API、产品行为、写作和研究任务

如果用 Codex IDE 扩展，打开的文件和选中的代码会自动成为上下文的一部分；如果用 App 或 CLI，就更需要你在 Prompt 里明确指向文件、目录、报错和截图。Codex 也会在执行过程中继续从文件内容、工具输出和历史步骤里收集上下文，但初始方向最好由你给出来。

一个实用写法是：

上下文：
- 入口页面：src/app/admin/posts/page.tsx
- 分类 API：src/app/api/admin/categories/route.ts
- 数据库表：schema/categories.sql
- 现象：后台文章列表里分类下拉框没有选项，截图见附件
- 参考：先不要改数据库结构，优先确认前端是否正确请求分类列表

这段上下文没有把所有项目文件都列出来，但它把任务现场框住了。

Context 要包含“你已经知道的判断”

很多人给上下文时只给事实，不给判断。比如：

这里是报错日志。

更好的写法是：

这里是报错日志。我怀疑问题在分类 API 没有返回数据，或者前端没有处理空数组。
这只是猜测，请你先验证，不要直接按我的猜测改。

这句话很有价值。它既把你的经验传给 Codex，又避免 Codex 把你的猜测当成事实。

写技术文章也一样。你可以给：

上下文：
- 读者：已经会用 ChatGPT，但刚开始接触 Codex，不熟悉 Agent 工作流
- 文章定位：技术笔记，不要写成营销文
- 参考资料：OpenAI Codex 官方文档、CodexGuide、codex-orange-book
- 我的经验：这个博客项目里，真正容易出问题的是发布链路和后台分类，不是 Markdown 写作本身

这比“参考这些资料写一篇”更能保留你的个人视角。

4. Constraints：把边界说清楚，Codex 才不会热心过头

Constraints 是 Prompt 里最容易被省略、但最能减少事故的一块。

因为 Codex 的默认倾向是完成任务。它看到一个 bug，可能顺手修周边；看到一个旧组件，可能顺手重构；看到依赖缺失，可能顺手安装；看到发布失败，可能顺手改部署配置。很多时候这很有帮助，但在真实项目里，“热心过头”也是风险。

我会把约束分成六类：

约束类型	你可以怎么写
范围约束	只改后台文章列表相关文件，不重构无关页面
风格约束	保持现有设计系统，不引入新的 UI 组件库
依赖约束	不新增生产依赖；如确实需要，先说明理由
数据约束	不改数据库 schema；不删除现有文章和图片
权限约束	不发布线上；不运行破坏性命令
交互约束	先给计划，经确认后再动手；或者只做 review 不改文件

一个更完整的例子：

约束：
- 保持当前后台页面的视觉风格，不做整体 redesign。
- 不新增 npm 依赖。
- 不修改数据库 schema，除非你先说明为什么必须改。
- 不发布到线上，不操作 Cloudflare。
- 如果发现问题不在前端，而在 API 或数据层，请先停下来说明证据和建议。

这些约束不会降低 Codex 的能力，反而让它更像一个知道项目边界的同事。

约束不是越多越好

约束写太多也会出问题。比如：

不要改结构，不要改样式，不要改接口，不要新增文件，不要影响现有逻辑，但要把这个复杂功能完整实现。

这类 Prompt 可能让任务变得不可完成。Codex 会困在互相冲突的限制里，最后要么绕远路，要么给出很脆弱的补丁。

好的约束应该满足两个条件：

• 它真的重要。
• 它能被检查。

“不要写得太 AI”是一个感受，不太好检查；“保留第一人称经验，避免营销式小标题，每节加入一个可执行示例”就更容易检查。

“不要大改”也很模糊；“优先只改 AdminPostList 和分类 API，如需扩大范围先说明原因”就清楚很多。

5. Done when：验收标准决定 Codex 什么时候该停

我现在最看重 Prompt 里的 Done when。

如果没有验收标准，Codex 会用自己的判断结束任务。它可能觉得“代码改完了”就是完成；但你真正想要的是“页面行为正确、测试通过、风险说清楚、我能 review”。

Done when 可以从这几类里选：

验收类型	例子
自动化验证	npm test、npm run lint、npm run build 通过
手动验证	打开后台页面，分类下拉框有选项，选择后刷新仍保留
数据验证	D1 里文章分类 ID 正确写入，旧文章不受影响
视觉验证	桌面和移动端截图无明显遮挡、溢出、深色图误用
Diff 验收	只改预期文件，解释每个文件为什么改
风险说明	说明未覆盖的测试、可能的边界情况和下一步

一个实际 Prompt 可以这样写：

验收标准：
- 本地构建通过。
- 后台文章列表能显示已有分类。
- 选择分类并保存后，刷新页面仍显示正确分类。
- 最终回复里列出改动文件、验证命令和未验证项。

写文章任务也可以有验收标准：

验收标准：
- 文章不少于 8000 字，结构是技术笔记风，不是清单拼贴。
- 至少包含 3 个可复制 Prompt 模板。
- 每个模板都说明适用场景和不适用场景。
- 引用资料链接完整，涉及 Codex 当前功能的说法以官方文档为准。
- 最后从读者角度 review：是否值得收藏，读完能不能在 30-60 分钟内做出一个产物。

Done when 的核心是：让 Codex 知道它不是“写完就结束”，而是要完成一个可以检查的闭环。

6. 最小可用模板：四段式 Prompt

如果只记一套模板，我建议先记这个：

目标：
我想让你完成什么？最终应该出现什么变化？

上下文：
哪些文件、错误、截图、项目规则、资料或前置判断和这次任务有关？

约束：
哪些事情不要做？必须遵守什么风格、权限、依赖、范围或安全边界？

验收标准：
什么情况才算完成？需要运行什么命令、检查什么页面、输出什么说明？

更像工作单时，可以加一个“输出要求”：

输出要求：
- 先用 3-5 行复述你理解的任务。
- 如果信息不足，先问最多 3 个关键问题。
- 如果可以直接做，先给简短计划，再实施。
- 结束时给改动摘要、验证结果和剩余风险。

注意这里的“先问问题”不是让 Codex 每次都停下来。对于小任务，它完全可以直接动手。关键是：当缺口会影响方向时，它应该先问；当缺口不影响方向时，它应该做出合理假设并在最后说明。

7. 模板一：修 bug

这是我最常用的模板。

目标：
修复 [具体页面/模块/命令] 的 [具体现象]。
期望行为是：[写清楚用户可见结果或测试结果]。

上下文：
- 复现步骤：
  1. ...
  2. ...
  3. ...
- 相关文件/目录：...
- 错误信息/截图：...
- 我目前的猜测：...（请先验证，不要直接当事实）

约束：
- 优先做最小改动，不重构无关代码。
- 不新增生产依赖。
- 不修改数据库结构，除非先说明证据和必要性。
- 保持现有风格和已有接口兼容。

验收标准：
- bug 按复现步骤不再出现。
- 相关测试、lint 或 build 通过。
- 最终说明根因、改动文件、验证结果和未覆盖风险。

不适用场景：

• 你还不知道 bug 在哪里，连复现步骤都没有。
• 这是一个跨系统事故，需要先做排障。
• 你其实想要的是“分析可能原因”，不是立刻修。

这种情况下，应该先用“只读排查模板”。

请先只读排查，不要改文件。

目标：
找出 [现象] 的可能原因，并按证据排序。

上下文：
- 复现步骤：...
- 相关日志：...
- 相关页面/接口：...

约束：
- 不改代码，不运行会修改数据的命令。
- 如果需要访问外部系统或生产数据，先说明原因。

验收标准：
- 输出 2-4 个可能原因，每个原因附上证据。
- 标注最可能根因和建议的最小修复方案。
- 列出还需要我提供的信息。

8. 模板二：加功能

加功能比修 bug 更容易失控，因为“顺手把体验做完整”的诱惑很大。

目标：
在 [页面/模块] 增加 [功能]。
用户应该能：[具体行为]。
这次只做：[本轮范围]，不做：[明确排除项]。

上下文：
- 相关入口：...
- 现有类似功能：...
- 数据来源/API：...
- 设计或交互要求：...

约束：
- 尽量复用现有组件和数据加载方式。
- 不引入新的状态管理库/组件库。
- 不改变已有接口的返回结构，除非先说明迁移影响。
- 如果发现需要拆成多步，请先给任务拆解。

验收标准：
- 新功能在主要路径可用。
- 边界状态可见：loading、empty、error、disabled。
- 相关测试或构建通过。
- 最终说明哪些范围已完成，哪些留到下一步。

比如给博客后台加“按系列筛选文章”，可以这样写：

目标：
在后台文章列表增加“系列”筛选。用户可以选择一个系列，只查看该系列下的文章。
这次只做列表筛选，不做系列管理页面。

上下文：
- 后台文章列表页面：...
- 当前分类筛选逻辑：...
- 数据库里文章已有 series 字段。

约束：
- 复用现有筛选 UI 风格。
- 不改文章编辑器。
- 不新增依赖。

验收标准：
- 默认显示全部文章。
- 选择某个系列后，列表只显示该系列文章。
- 清空筛选后恢复全部。
- 构建通过，最终说明改动文件。

这个 Prompt 的好处是，它让 Codex 知道“系列管理页面”不是本轮范围。否则它可能热心地做一个完整后台模块。

9. 模板三：代码 Review

让 Codex review 代码时，最怕它只给一堆泛泛建议。

我会把 review 分成两类：

• 合并前 review：找 bug、回归风险、测试缺口。
• 学习型 review：解释代码、指出可读性和架构改进。

合并前 review 模板：

目标：
请 review 当前改动，优先找会导致 bug、数据错误、安全风险、性能回退或测试缺失的问题。

上下文：
- 这次改动目标：...
- 相关业务规则：...
- 需要重点看的文件：...

约束：
- 先不要改代码，只输出 review 结果。
- 不要给泛泛的风格建议，除非它会导致维护风险。
- 每个问题尽量给文件、位置、触发条件和建议修法。

验收标准：
- 按严重程度排序。
- 如果没有发现明确问题，要直接说明“未发现阻塞问题”。
- 列出仍未验证的风险。

学习型 review 模板：

目标：
帮我理解这组改动，指出它的设计思路、数据流和可能的维护成本。

上下文：
- 我主要想学习：...
- 相关文件：...

约束：
- 不要改代码。
- 用技术笔记风解释，不要写成 PR 评语。

验收标准：
- 画出主要调用链或用文字列出数据流。
- 说明 2-3 个优点和 2-3 个可改进点。
- 给出我下一步应该读的文件顺序。

这两个模板看起来相似，但目标完全不同。前者是交付风险，后者是理解代码。让 Codex 知道 review 的目的，输出质量会稳定很多。

10. 模板四：资料调研

Codex 不只用来改代码。写 AI 工具教程时，我经常让它先做资料调研。但资料调研也需要 Prompt 骨架，否则它容易变成“看起来很完整的摘要”。

目标：
围绕 [主题] 做一份资料调研笔记，最后服务于一篇 [文章/教程/决策文档]。

上下文：
- 主要问题：...
- 已知资料：...
- 读者是谁：...
- 我希望文章最后能解决：...

约束：
- 涉及当前产品功能、命令、权限、模型、套餐时，只用官方资料或明确标注不确定。
- 社区文章只作为经验参考，不作为事实依据。
- 不要照搬原文结构，不要大段引用。
- 每条重要结论要附来源链接或说明来自本地实践。

验收标准：
- 输出按主题分组的 research note。
- 每组包含：结论、证据、可用于文章的角度、仍不确定的问题。
- 最后给文章大纲，但不要直接写正文，除非我继续要求。

这套模板适合写 Codex 系列。比如调研 Codex Skills 时，我会要求 Codex 区分：

• 官方文档说了什么。
• 社区教程怎么用。
• Claude Skills 能提供哪些横向参考。
• 哪些经验可以迁移，哪些只是某个平台自己的实现细节。

这样写出来的文章更不容易“资料堆砌”。读者看到的是整理后的判断，而不是搜索结果合集。

11. 模板五：写技术文章

这也是这个博客最常用的场景。

目标：
写一篇关于 [主题] 的技术笔记风文章。
文章要解决的问题是：[读者读完能做什么]。

上下文：
- 系列位置：这是第 [几] 篇，前一篇讲了 ...
- 读者画像：...
- 参考资料：...
- 我的个人经验/项目案例：...
- 必须包含的点：...

约束：
- 用中文，语气冷静、务实、有个人判断。
- 不写营销式标题，不堆概念。
- 不照搬参考文章结构。
- 涉及当前产品能力时，发布前核对官方资料并写明整理日期。
- 不要只写观点，每一节尽量给例子、模板、命令或检查清单。

验收标准：
- 文章有清楚的开头：这篇解决什么问题。
- 中间有可复制模板或实操步骤。
- 结尾有收藏清单和下一步练习。
- 从读者角度 review：是否值得收藏，是否能在 30-60 分钟内完成一个小产物。

如果要配图，可以加：

配图要求：
- 生成 1-2 张浅色信息图，风格类似白底网格纸、蓝色标题框、绿/橙/紫卡片。
- 不使用深色背景。
- 图中只放结构关系，不塞太多小字。
- 图片要能在博客正文中解释一个核心概念，而不是装饰。

这里有一个经验：写作 Prompt 里要明确“读者读完能做什么”。否则 Codex 容易写成概念介绍，看起来完整，但读者收藏后也不知道怎么用。

12. 模板六：发布前检查

当文章已经写好，最后可以让 Codex 做一次发布前 review。

目标：
从读者和发布两个角度 review 这篇文章，判断是否适合发布到个人博客。

上下文：
- 文章文件：...
- 博客定位：技术实践、AI 工具、个人经验，风格冷静务实。
- 系列规划：...

约束：
- 先不要改文章，只输出 review。
- 重点看实用价值、结构重复、事实风险、标题摘要、标签分类和图片是否合适。
- 不要只给鼓励，要指出具体可改处。

验收标准：
- 给出“是否值得发布”的判断。
- 列出必须修改、建议修改、可不改三类问题。
- 从读者角度说明是否值得收藏。
- 如果建议修改，给出最小修改方案。

如果 review 通过，再让它执行修改：

请按刚才 review 的“必须修改”和“建议修改”改文章。
保持原文章主线，不重写成另一篇。
修改后再输出一版发布检查：frontmatter、链接、图片、摘要、标签、未验证事实。

这比一开始就说“帮我润色一下”更可靠。因为 review 和改写分成了两步，Codex 的角色更清楚。

13. 什么时候先让 Codex 计划，而不是直接写代码

OpenAI 官方最佳实践也建议：复杂、模糊、难描述的任务，先让 Codex 计划，再开始实现。我的判断是，只要满足下面任意一条，就应该先 Plan：

情况	为什么要先计划
会改多个模块	先确认改动路径，避免越改越散
你不确定根因	先排查，不要按猜测直接修
涉及数据或权限	需要确认破坏性操作边界
没有明确验收方式	先定义 Done when
需求本身还模糊	让 Codex 先问问题或提出拆解
你要写长文或系列规划	先大纲和资料结构，再正文

计划优先的 Prompt 可以这样写：

请先进入计划阶段，不要改文件。

目标：
...

上下文：
...

约束：
...

请输出：
1. 你理解的任务。
2. 需要读取或确认的文件。
3. 可能的实现路径。
4. 风险和需要我确认的问题。
5. 建议的验收标准。

我确认后再让你实施。

如果你用的是支持 Plan mode 的 Codex 入口，可以直接用 /plan 或界面里的计划模式。没有这个入口也没关系，把“请先计划，不要改文件”写进 Prompt，本质上是在给工作流设一个刹车。

14. 一次性 Prompt、AGENTS.md 和 Skill 的边界

Prompt 写顺手以后，很容易想把所有模板都固化下来。这里要小心区分三层东西：

层级	适合放什么
一次性 Prompt	本次任务目标、临时上下文、当前限制
AGENTS.md	项目长期规则、运行命令、内容分类、验收习惯
Skill	可复用工作流、资料引用、脚本、检查清单

比如这篇文章里的“写技术文章模板”，如果只是今天写 Codex 第 5 篇，就放在 Prompt 里。

如果这个博客长期要求：

• 所有文章用中文。
• 分类只能使用受控集合。
• AI 文章必须核对官方资料。
• 发布前检查 frontmatter、摘要、标签、图片。

这些应该放进 AGENTS.md。

如果我以后经常做“技术文章 review”，并且每次都要：

• 检查结构。
• 检查读者价值。
• 检查引用。
• 检查图片。
• 检查发布字段。
• 输出可执行修改建议。

那就可以做成一个 Skill。官方文档里也提到，旧式 custom prompts 已经不再是推荐方向；如果要共享或隐式调用可复用能力，更适合沉淀成 Skill。

我自己的经验是：不要太早做 Skill。先用 Prompt 跑几次，看到重复摩擦，再沉淀。否则你会把还没稳定的习惯固化成一个很重的流程。

15. 反例改写：从一句话到可执行任务

下面用几个常见反例做改写。

反例一：帮我优化一下

原始 Prompt：

帮我优化一下这个页面。

改写：

目标：
优化后台文章列表页的可用性。重点解决三个问题：分类筛选不清楚、操作按钮太密、移动端标题容易被挤压。

上下文：
- 页面文件：...
- 截图：见附件。
- 当前后台主要给我自己使用，不需要做成营销风或复杂仪表盘。

约束：
- 保持现有浅色工作台风格。
- 不新增组件库。
- 这次只改列表页，不改文章编辑页和登录页。

验收标准：
- 桌面端操作按钮仍然一眼可见。
- 移动端标题和按钮不重叠。
- 分类筛选能正常使用。
- 构建通过，最终说明改动文件和未解决的问题。

这里的“优化”被拆成了三个具体问题。Codex 不是在猜“什么叫好看”，而是在解决可检查的体验问题。

反例二：写一篇 Codex 教程

原始 Prompt：

写一篇 Codex 教程。

改写：

目标：
写 Codex 系列第 5 篇，主题是 Prompt 骨架。读者读完后应该能把一个模糊需求改写成可执行的 Codex 任务。

上下文：
- 前一篇讲“先让 Codex 读懂项目”。
- 这篇要承接项目地图，进入 Prompt 写法。
- 参考 OpenAI Codex 官方文档里的 Goal / Context / Constraints / Done when。
- 结合我的博客后台、文章写作和发布实践。

约束：
- 技术笔记风，不要写成营销文。
- 不照搬参考文章结构。
- 不要只讲观点，必须给模板和反例改写。
- 涉及当前 Codex 功能时写明整理日期。

验收标准：
- 有一张浅色结构图。
- 至少 5 个可复制模板。
- 有 30-60 分钟练习。
- 结尾有收藏清单和下一步。

这就不是“写一篇文章”，而是一份明确的编辑任务。

反例三：帮我看一下这个 PR

原始 Prompt：

帮我看一下这个 PR。

改写：

目标：
以合并前 review 的标准检查这个 PR，优先找阻塞问题。

上下文：
- PR 目标：...
- 主要改动文件：...
- 业务规则：...
- 这次最担心：数据兼容和权限判断。

约束：
- 不要改代码。
- 不要把命名、格式这种非阻塞问题放在前面。
- 如果发现测试缺口，请说明具体应该补什么测试。

验收标准：
- 按严重程度列出问题。
- 每个问题说明触发条件、影响和建议修复方向。
- 如果没有阻塞问题，明确说可以合并但列出剩余风险。

Review Prompt 的关键是定义“看什么”。否则 Codex 很容易输出一份漂亮但不锋利的泛评。

16. Prompt 写作的六个常见误区

误区一：把“请你认真一点”当约束

“认真”“仔细”“专业”这些词可以表达态度，但不能作为验收标准。

更好的写法是：

请重点检查：数据一致性、错误处理、权限边界、测试缺口。

误区二：只给资料，不给任务

这里有 5 篇文章，帮我看看。

Codex 不知道你要摘要、比较、批判、改写，还是提炼教程。

更好的写法是：

请把这些资料整理成一份写作 research note，目标是服务于一篇 Codex Skills 教程。

误区三：只给任务，不给现场

修一下登录失败的问题。

没有复现步骤、错误信息、相关文件和预期行为，Codex 会浪费很多时间找入口。

误区四：把多个目标混在一起

修 bug、优化体验、顺便重构、再写测试。

有时可以这么做，但最好先让 Codex 拆解任务。否则最后 diff 过大，很难判断每一处改动是否必要。

误区五：验收标准只写“完成即可”

“完成”不是验收标准。你要说明什么证据能证明完成。

完成后运行 npm run build，并打开后台文章列表手动验证分类选择和保存。

这就具体很多。

误区六：把长期规则塞进每次 Prompt

如果你每次都要说：

• 不要新增依赖。
• 不要改数据库。
• 文章分类只能用受控集合。
• 发布前检查 frontmatter。

那说明这些应该进 AGENTS.md，而不是每次手打。Prompt 应该保留本次任务独有的信息。

17. 我的常用 Prompt 组合

我现在比较常用这三种组合。

组合一：先理解，再实施

适合陌生项目、旧项目、跨模块任务。

第一步请只读扫描，不要改文件。
输出项目地图、相关文件、验证方式、风险和建议实施 Prompt。

我确认后，再按你建议的实施 Prompt 执行。

这其实是上一篇和这一篇的组合。

组合二：先 review，再修改

适合文章、设计、代码质量提升。

先从读者/维护者角度 review，不要修改。
把问题分成：必须改、建议改、可不改。
我确认后，再按必须改和建议改执行。

这样可以避免 Codex 一上来把你的文章改成另一种声音。

组合三：直接小步实施

适合目标非常清楚的小改动。

目标：...
上下文：...
约束：只改这个文件，不新增依赖。
验收标准：运行对应测试，并说明 diff。

不是所有任务都要隆重计划。小任务就应该小步快跑。

18. 30-60 分钟练习：建立自己的 Prompt 模板库

如果你想把这一篇真的用起来，可以做一个小练习。

第一步：选一个真实小任务

不要选太大的任务。可以从这些里面挑：

• 修一个页面样式问题。
• 给一个命令加参数。
• 整理一篇旧文章。
• Review 一段最近改动。
• 调研一个 API 的当前用法。

第二步：先写一句模糊 Prompt

故意写得像平时一样：

帮我优化一下文章列表。

第三步：按四段式改写

补上：

• Goal：优化什么，结果是什么。
• Context：文件、截图、现象、项目规则。
• Constraints：不改什么，不新增什么，风险边界。
• Done when：怎么验证，最后输出什么。

第四步：让 Codex 先计划

把 Prompt 发给 Codex，但要求它先计划，不要改文件。

看它的计划是否准确。如果计划里出现你不想要的方向，说明 Prompt 还要补约束。

第五步：实施一个最小改动

确认计划后，让 Codex 只做最小范围改动。完成后看三个东西：

• diff 是否集中。
• 验证是否真实跑过。
• 最终说明是否暴露了剩余风险。

第六步：沉淀模板

把这次有用的 Prompt 存到自己的笔记里。不要急着做成 Skill。等你在 3 次以上任务里重复使用，再考虑沉淀到 AGENTS.md 或 Skill。

19. 可以直接收藏的 Prompt 清单

最后给一份简版清单。

通用任务

目标：

上下文：

约束：

验收标准：

输出要求：
先复述理解，再给计划；完成后说明改动、验证和风险。

只读理解项目

请先只读扫描，不要改文件。
输出：项目结构、相关文件、运行/验证命令、风险区域、未知问题、建议实施 Prompt。

修 bug

修复 [现象]。
复现步骤是 [...]
相关文件是 [...]
约束：最小改动，不新增依赖，不改无关模块。
完成标准：按复现步骤不再出现，相关测试/构建通过，说明根因和风险。

加功能

在 [位置] 增加 [功能]，用户能 [行为]。
这次只做 [范围]，不做 [排除项]。
复用现有模式，不新增依赖。
完成标准：主路径可用，边界状态完整，构建/测试通过。

Review

请 review 当前改动，优先找 bug、回归、安全、性能和测试缺口。
先不要改代码。
按严重程度输出问题；没有阻塞问题也要明确说明。

写文章

写一篇 [主题] 技术笔记，解决 [读者问题]。
读者是 [...]
参考资料是 [...]
约束：中文、务实、有个人经验、不照搬、不营销。
完成标准：有模板/案例/练习/资料来源，最后从读者角度 review。

20. 这篇的核心判断

我现在对 Codex Prompt 的理解，可以压成三句话：

第一，Prompt 不是咒语，而是任务契约。

第二，上下文不是越多越好，而是越贴近任务现场越好。

第三，验收标准比措辞更重要，因为它决定 Codex 什么时候停、怎么证明自己做完。

真正好的 Codex 使用习惯，不是每次都写一大段复杂 Prompt，而是能根据任务大小选择合适的规格：小任务直接四段式，大任务先计划，重复规则进 AGENTS.md，稳定流程再做 Skill。

下一篇会继续这个方向，进入 AGENTS.md：哪些规则应该从 Prompt 里拿出来，变成 Codex 每次打开项目都能自动读到的项目说明书。

资料来源

• OpenAI Codex：Best practices，关于任务上下文、Prompt 四要素、计划优先、AGENTS.md、验证和 review 的建议。https://developers.openai.com/codex/learn/best-practices
• OpenAI Codex：Prompting，关于 Prompt、线程、上下文、Goal mode 和复杂任务拆解的说明。https://developers.openai.com/codex/prompting
• OpenAI Codex：Custom instructions with AGENTS.md，关于 AGENTS.md 的发现顺序、作用域和覆盖规则。https://developers.openai.com/codex/guides/agents-md
• OpenAI Codex：Skills，关于把重复工作流沉淀成可复用能力的官方说明。https://developers.openai.com/codex/skills
• CodexGuide：快速上手，作为系列路线和学习梯度参考。https://codexguide.ai/start/
• bozhouDev/codex-orange-book，作为 Codex 实践资料和社区经验参考。https://github.com/bozhouDev/codex-orange-book