Codex 最佳实践：从一次性提示词走向可复用工作流

这篇官方指南表面上在讲很多分散的话题：提示词、计划模式、AGENTS.md、配置、MCP、skills、automations、会话管理。

但把它们串起来看，核心其实很统一：Codex 的效果上限，不主要取决于你临场会不会写 prompt，而取决于你有没有把工作方式逐步沉淀成一套可复用系统。

OpenAI 给出的演进顺序很清楚：先把单次任务描述清楚，再把稳定规则写进仓库和配置，把外部上下文接进来，把高频流程做成 skill，最后把已经稳定的方法交给 automation 定时跑。

如果仓库稍微复杂一点，Codex 最容易出错的地方通常不是“代码能力不够”，而是任务边界不清。

这篇指南给了一个很实用的默认提示结构：

1. Goal：这次到底要改什么、做什么。
2. Context：哪些文件、目录、文档、报错或示例相关。
3. Constraints：要遵守哪些架构、规范、安全约束。
4. Done when：做到什么程度才算完成，比如测试通过、行为变化、问题不再复现。

这个结构的价值不在“更像模板”，而在于它把模糊意图压缩成了可执行边界。边界一清楚，Codex 的探索成本、误判概率和返工次数都会下降。

官方还建议按任务难度调整 reasoning level。简单、边界明确的任务可以偏低；调试、重构、多步骤改动则应提高。这里没有绝对最佳设置，关键是让推理强度和任务复杂度匹配。

对多步骤、歧义大、需求本身还没说清的任务，直接让 Codex 开写，风险通常高于收益。

文档里给了三种前置做法：

1. 用 Plan mode 先收集上下文、澄清问题，再产出计划。
2. 让 Codex 先反问你，把模糊想法压成明确需求。
3. 对长链路任务引入 PLANS.md 一类执行模板。

这背后的判断很简单：复杂任务的首要问题不是“写得快”，而是“先把问题定义对”。

如果需求本身还在漂，越早编码，越容易把错误结构快速固化进代码。

一旦某种提示方式反复有效，就不应该继续手动重复。官方把 AGENTS.md 定义成 agent 的开放式 README，这个定位很准确。

一个好用的 AGENTS.md 不需要很长，但最好覆盖几类高频信息：

1. 仓库结构和关键目录。
2. build、test、lint 等命令。
3. 工程约束、禁区和评审预期。
4. 如何判断任务完成。

文档特别强调两点，我认为很重要。

第一，AGENTS.md 可以分层放置。全局默认、仓库规则、子目录局部规则可以同时存在，离当前工作目录越近的规则优先级越高。
第二，文件要短、要准、要持续更新。它不是宣言文件，而是给 agent 提供稳定操作边界的工作文档。

如果 Codex 在同一类问题上连续犯错，正确做法不是每次在 prompt 里补一句，而是复盘后把规则写回 AGENTS.md。

很多所谓“质量问题”，其实是环境问题：工作目录错了、默认模型不对、缺少写权限、工具没接好，或者不同入口用着不同配置。

因此官方建议尽早把这些内容固定下来：

1. 个人默认放进 ~/.codex/config.toml。
2. 仓库特定行为放进 .codex/config.toml。
3. 命令行覆盖只用于一次性场景。

这里尤其值得记住的是 approval 和 sandbox 两个旋钮。新手默认应该收紧，再按受信任仓库和真实工作流逐步放开，而不是一开始就给满权限。

这其实是在做一件很朴素的事：减少每次会话的随机性，让 Codex 在不同 session、不同 surface 上表现更一致。

这篇指南最务实的一段，是把 testing 和 review 明确放进 Codex 的职责范围里。

不要只说“把这个功能改掉”，还要要求它：

1. 需要时补测试或改测试。
2. 跑相关检查。
3. 确认行为符合预期。
4. 对 diff 做一轮 review，找回归、风险和坏味道。

文档里还提到 /review、diff panel，以及把 code_review.md 接到 AGENTS.md 里统一团队评审口径。其核心思想是一致的：Codex 不该只负责生成，还该参与验证和复核。

如果“完成”的定义只停留在代码写完，最终留下来的通常是更多人肉补洞。

官方对 MCP 的定位也很明确：当关键上下文不在仓库里，而且数据会频繁变化时，用 MCP 比手工复制粘贴更合适。

适用场景包括：

1. 需要访问 repo 外部系统。
2. 数据实时变化，复制到 prompt 很快过期。
3. 希望 Codex 直接操作工具，而不是只看说明。
4. 需要在团队或项目之间复用这条集成链路。

不过文档没有鼓励“先把所有工具都接进来”。它反而建议从一两个真正能消灭手工循环的连接开始。这个取舍很对，因为工具一多，如果没有明确工作流，复杂度会先涨，收益未必先到。

整篇文章里，我最认同的一句话可以概括成：skill 定义方法，automation 定义节奏。

当某条流程已经被你证明可重复，就不要继续靠长 prompt 或反复来回纠偏，应该把它打包成 skill。一个 skill 最好只做一件事，输入输出明确，触发描述直白，先覆盖 2 到 3 个高频案例，不要一开始就试图兜住全部边界。

当这条 skill 已经足够稳定，再进一步让 automation 定时运行。官方给的候选场景也很典型，比如提交摘要、bug 扫描、release notes、CI 失败整理、standup summary。

这里最值得借鉴的，不是“自动化越多越好”，而是顺序不能反：先把方法做稳定，再给它排班。

Codex 的 session 不是普通聊天记录，而是不断累积上下文和决策轨迹的工作线程。

所以官方建议也很直接：

1. 一个线程对应一类连贯任务。
2. 真正分叉了再 fork，不要为同一问题乱开新线程。
3. 长线程要 compact。
4. 把有边界的子任务交给 subagent。

文档最后列的常见错误也都指向同一个问题：把本该沉淀成系统的东西，继续临时塞进 prompt 或混进单一线程里。

比如：

1. 本该进 AGENTS.md 的长期规则仍然写在 prompt 里。
2. 没告诉 Codex 怎么 build、test、verify。
3. 多步骤任务不先计划。
4. 同一项目只开一个超长线程，导致上下文持续膨胀。

这些问题看起来零散，实质上都在制造同一种成本: 让每次任务都从头重新对齐。

如果你想把这篇指南压缩成一套最小实施路径，我会建议按下面三步推进：

1. 先统一单次任务输入，固定 Goal / Context / Constraints / Done when 结构。
2. 再把稳定规则和验证方式写进 AGENTS.md 与 config.toml。
3. 最后把已经成熟的高频流程升级成 skill，再交给 automation。

这也是我读完这篇文档后的核心结论：真正拉开差距的，不是谁会写更多提示词，而是谁更早把 Codex 纳入一套可维护、可验证、可复用的工程工作流。