写好 Codex 提示词

你通过 prompts 和 Codex 交互。Prompt 描述你希望它做什么，Codex 随后进入循环：调用模型、读取文件、编辑文件、运行命令和调用工具，直到任务完成或被取消。

好的 Codex prompt 不只是“请帮我做”。它要写清目标、上下文、范围、禁止事项、验证方式和交付格式。

Prompting

官方 Codex prompting 基础。

From theory to practice

把模糊需求改写成可执行任务。

How a task completes

理解 Codex 从 prompt 到验证的循环。

两个简单例子

解释代码：

请解释 transform module 是如何工作的，以及其他模块如何使用它。

新增功能：

请添加一个新的命令行选项 `--json`，用于输出 JSON。

这两个 prompt 能跑，但真实项目里还不够。要稳定交付，需要补上下文、范围和验证。

好 prompt 的结构

flowchart LR
    Goal["目标"] --> Context["上下文"]
    Context --> Scope["范围"]
    Scope --> Boundaries["禁止事项"]
    Boundaries --> Verify["验证"]
    Verify --> Deliver["交付"]

建议包含：

目标：用户层面的结果是什么。
上下文：相关文件、错误日志、截图、链接、业务规则。
范围：只允许动哪些文件或目录。
禁止事项：不新增依赖、不改数据库、不动无关文件等。
验证：跑什么测试、lint、build、截图或人工检查。
交付：最后汇报改动文件、验证结果、未验证项和风险。

Outcome-first 写法

GPT-5.5 的官方提示词指导强调 outcome-first：先定义结果、成功标准、约束和可用上下文，让模型选择具体路径。对 Codex 来说，这比写一长串“先做 A、再做 B、再做 C”更稳，除非每一步都是业务硬约束。

可以用这个模板：

目标：
修复用户在移动端打开设置页时按钮错位的问题。

上下文：
- 复现路径：打开 /settings，宽度 390px，点击 Profile tab。
- 相关文件优先看 src/app/settings 和 src/components/tabs。

范围：
- 只改布局和样式相关文件。
- 不改接口、不改数据结构、不新增依赖。

验证：
- 跑现有 lint/build。
- 用浏览器检查 390px、768px、1440px 三个宽度。
- 最后说明改动文件、验证结果和残余风险。

这个 prompt 没规定 Codex 必须先读哪个文件、后改哪个组件，但把目标和验收写清楚了。Codex 可以按实际代码结构选择路径。

停止条件和缺证据行为

长任务尤其要写 stopping conditions。否则 Codex 可能一直扩大搜索范围或改到无关文件。

建议直接写：

如果没有复现到问题，先停下并报告已检查路径，不要猜改。
如果需要新增依赖，先说明原因和替代方案。
如果测试失败且与本次改动无关，记录失败命令和证据，不要顺手大改。
如果超过约定范围，先输出计划，等确认后再继续。

缺证据时也要明确：

如果官方文档、源码和现象不一致，以本仓库当前源码和可复现行为为准；无法确认时标注为推断，不要写成确定结论。

复杂任务先拆

Codex 处理复杂工作时，拆成更小、更聚焦的步骤更稳。小任务更容易测试，也更容易 review。

如果不知道怎么拆，先让 Codex 只做计划：

请先不要改文件。基于当前问题提出最小实现计划，列出需要读取的文件、可能风险和验证方式。

确认计划后，再让它执行第一步。

Prompt 里应该少写什么

很多旧 prompt 会堆满绝对规则，例如 ALWAYS、NEVER、must、only。官方提示词指导建议把这些词留给真正的不变量，例如安全边界、必填字段、绝对禁止的动作。

判断类任务更适合写 decision rules：

不推荐	推荐
“永远不要联网。”	“只有当本地资料不足或需要最新事实时联网，并引用来源。”
“必须先读所有文件。”	“先读入口文件和调用链，发现范围不足再扩展。”
“一定要完整重构。”	“优先最小改动；只有现有结构无法满足目标时再提出重构计划。”

对 Codex 来说，过多绝对规则会让它在冲突指令里浪费推理，甚至错过更简单的验证路径。