Prompt 编写最佳实践

26.1 四要素框架

官方 best practices 给出的 Prompt 默认框架,包含四块:

要素	说明
Goal(目标)	你到底想改什么、做什么
Context(上下文)	哪些文件、目录、文档、错误日志相关
Constraints(约束)	代码风格、架构边界、安全要求、不能改的东西
Done when(完成标准)	什么情况算完成(测试通过、bug 不再复现等)

官方原文:

A good default is to include four things in your prompt: Goal, Context, Constraints, Done when. This helps Codex stay scoped, make fewer assumptions, and produce work that’s easier to review.

26.2 反面案例 vs 正面案例

❌ 反面案例

帮我修一下登录问题。

问题:目标模糊、没上下文、没约束、没完成标准。

✅ 正面案例

目标:修复用户登录后偶尔跳回首页的问题。

上下文:登录逻辑在 src/auth,路由守卫在 src/router,
最近错误日志见 logs/login-error.log。

约束:不要改数据库结构,不要重写登录流程,只修复当前跳转问题。

完成标准:补充或更新测试,确认登录后能回到原访问页面,相关测试通过。

CSDN《Codex 使用最佳实践》指出:这不是为了“教模型怎么写代码”,而是为了减少它做无谓假设。

26.3 让 Codex 反向采访你

对于不确定的需求,让 Codex 反过来问你:

我现在只有一个粗略想法,请你先问我问题,帮我把需求变成可执行的开发任务。

官方推荐:让 Codex 挑战你的假设,把模糊想法变具体。这对产品功能、重构、复杂 bug 都很有用。

26.4 @ mention 文件作为上下文

可以在 prompt 中 @ mention 文件,Codex 会把它作为上下文:

查看 @src/auth/login.ts 和 @src/router/guard.ts,
分析登录后跳转的逻辑

26.5 语音输入(Codex App)

官方 best practices 提到:

To provide context faster, try using speech dictation inside the Codex app to dictate what you want Codex to do rather than typing it.

在 Codex App 里可以用语音口述代替打字,加快上下文输入。

26.6 避免把长期规则塞进 prompt

常见误区:把每次都要遵守的规则反复写进 prompt。

正确做法:重复的规则写进 AGENTS.md 或 Skill,不要每次都说。例如:

• ❌ 每次 prompt 都写“用 pnpm,不要用 npm”
• ✅ 写进 AGENTS.md 一次,Codex 自动遵守

26.7 复杂任务先 Plan

Prompt 里直接加一句:

先不要写代码。请先阅读相关文件,给出你的理解、修改计划、风险点和验证方式。等我确认后再开始实现。

详见第 13 章 Plan 模式。

26.8 验证要求写进 prompt

实现后请运行相关测试,并检查 git diff,确认没有无关修改。
如果测试无法运行,请说明原因和你已经做过的验证。

让 Codex 不止写代码,还要验证代码(见第 14 章)。

26.9 reasoning effort 配合

根据任务难度选推理强度(见第 8 章):

• 简单任务:low
• 一般任务:medium
• 复杂变更、调试:high
• 长 agentic 任务:extra high

26.10 Prompt 模板速查

【目标】
<一句话说清要做什么>

【上下文】
- 相关文件:@path/to/file
- 错误日志:<粘贴或路径>
- 历史实现:<简述>

【约束】
- 不要改 <xxx>
- 遵循 <约定>
- 安全要求 <xxx>

【完成标准】
- <可验证的条件>
- 测试通过
- git diff 无无关修改

【验证要求】
实现后跑相关测试,检查 diff,如测试无法运行请说明原因。

资料来源

• OpenAI 官方 Codex best practices——Prompt 四要素、语音输入
• CSDN《Codex 使用最佳实践》——四要素中文解读与正反案例
• 官方 prompting 文档