你和 Codex 之间差的不是模型，是方法#

很多人第一次用 Codex，体验大概是这样的：丢一句"帮我加个功能"，它噼里啪啦写了一堆代码，看起来挺像回事。但跑一下测试，红了。改完测试再跑，又出别的问题。来回几轮之后，你开始怀疑：这东西到底有没有用？

问题不在 Codex。OpenAI 内部的数据显示，Codex 已经在审核 100% 的内部 PR。同样是这个工具，为什么别人用出了生产力，你用出了挫败感？

答案是使用方法。OpenAI 最近在开发者文档中发布了一份详尽的 Codex 最佳实践指南，覆盖了从提示词结构到自动化调度的完整工作流。这篇文章会对这些实践进行完整解读，并结合真实使用场景补充一些技巧和踩坑经验。

提示词的四要素公式#

Codex 不是聊天机器人，它是编程智能体。给它一句模糊的"帮我修这个 bug"，它会根据自己的判断去猜你想干嘛。猜对了皆大欢喜，猜错了浪费时间。

OpenAI 推荐的提示词结构包含四个要素：

目标（Goal）：你想做什么？用结果而不是方法来描述。❌ “用正则匹配邮箱” ✅ “在注册表单中增加邮箱格式校验，不通过时显示错误提示”。

上下文（Context）：哪些文件、目录、文档或报错信息跟这个任务相关。在 Codex 中可以用 @ 符号直接引用文件，把关键上下文喂给它。

约束（Constraints）：需要遵循的标准、架构选型、安全要求或团队规范。比如"不能改动数据库 Schema"、“必须兼容 IE11”、“所有 API 返回统一用 camelCase”。

完成条件（Done when）：什么情况算任务完成？测试全部通过？行为符合预期？bug 不再复现？这个条件越具体，Codex 的输出质量越高。

缺少完成条件是最常见的问题。没有明确的验收标准，Codex 会按照自己的理解给出一个"看起来对"的方案。你觉得不对，它觉得挺好，来回拉扯。

计划模式：复杂任务的必经之路#

对于简单任务，直接开干没问题。但遇到复杂、模糊或跨多个模块的需求，跳过计划直接写代码是最常见的翻车原因。

Codex 提供了三种规划策略：

Plan 模式。在 CLI 中输入 /plan 或按 Shift+Tab，Codex 会先进入探索模式，读取相关代码、理解架构、提出方案，确认后再动手。这是最简单也最有效的方式。

反向访谈。让 Codex 先向你提问。告诉它：“先别写代码，问清楚我的需求再说。“它会挑战你的假设，把模糊想法变成具体规格。这个策略特别适合你只有大致方向但不确定细节的场景。

PLANS.md 模板。配置 Codex 遵循一个结构化的执行计划模板，适合长周期、多步骤的任务。模板可以包含阶段划分、验收标准、回滚方案等。

跳过计划步骤是导致会话质量下降的最常见原因。一旦 Codex 在错误的方向上走了太远，纠正的代价比重新来一次还高。

AGENTS.md：把经验写成规则#

提示词写得好，下次还得重新写。AGENTS.md 的价值在于：把反复有效的指令固化下来，让 Codex 每次启动都自带团队经验。

一个好的 AGENTS.md 应该包含：

  • 项目结构和重要目录的说明
  • 构建、测试、lint 的命令和预期退出码
  • 工程规范和 PR 期望
  • 禁止操作（不要改迁移文件、不要在实现任务中修改测试）
  • 验收标准（哪些测试必须通过才算完成）

在 CLI 中输入 /init 可以自动生成一个 AGENTS.md 起步模板。但别直接用，要根据团队实际的开发、测试、审查流程来调整。

关键原则：从简开始，按需增长。 先写最基础的几条规则，然后在使用过程中，每次 Codex 犯了同样的错误，就把对应的纠正写进 AGENTS.md。这种"基于真实摩擦的迭代"比一开始就写一大堆规则有效得多。

AGENTS.md 还支持层级结构：全局的放在 ~/.codex/，仓库级的放在项目根目录，子目录级别的规则放在对应目录下。越靠近当前工作目录的文件优先级越高。

当 AGENTS.md 变得太长时，把详细内容拆分到独立的 markdown 文件中（比如 docs/architecture.md、docs/code-review.md），在 AGENTS.md 里引用即可。

测试驱动的验证循环#

没有测试，Codex 就只能靠自己的判断来验证代码。在有真实复杂度的代码库里，这种判断并不可靠。

OpenAI 推荐的 TDD 工作流：

  1. 先写测试，明确你期望的行为
  2. 确认测试全部失败（在实现之前）
  3. 把失败的测试作为检查点提交
  4. 让 Codex 实现代码，明确要求"不要修改测试文件本身”
  5. 运行完整验证，你自己确认通过后再接受

这个流程的核心思想是：测试是契约。Codex 可以自由选择实现方式，但必须满足测试定义的行为约束。

除了单元测试，lint 检查、类型检查和集成测试都不是可选项。它们是让 Codex 能够自主迭代的基础。没有这些，每一步都需要人工确认，效率大打折扣。

在 Codex 应用中，可以用 /review 命令来审查代码变更。它支持多种模式：对比分支的 PR 式审查、审查未提交的改动、审查某个 commit、使用自定义审查指令。如果你的团队有 code_review.md 文件并在 AGENTS.md 中引用了它，Codex 会遵循团队的审查标准。

会话管理：别让上下文变垃圾场#

Codex 的会话不只是聊天记录，它是积累上下文、决策和操作的工作线程。管理不善会直接影响输出质量。

一个任务一个线程。 如果工作还属于同一个问题，留在同一线程中更好，因为它保留了推理链。只有当工作真正需要分叉时才创建新线程。

用 fork 替代死磕。 当会话开始跑偏时，不要反复纠正。把当前状态保存到文件，fork 一个新线程，用更干净的上下文重来。一旦线程积累了矛盾的指令、半成品代码和过时的假设，每多一轮对话的成本都比从头来更高。

善用子代理（Subagent）。 把边界清晰的工作（探索代码、跑测试、分类问题）交给子代理处理，让主线程聚焦核心问题。

CLI 中几个实用的会话管理命令：

命令用途
/resume恢复之前的会话
/fork从当前线程创建分支
/compact压缩上下文（Codex 也会自动压缩）
/agent在多个代理线程间切换
/review审查代码变更

MCP：让 Codex 连接外部世界#

当 Codex 需要的信息不在代码仓库里时，就需要 MCP（Model Context Protocol）。它让 Codex 能连接到你已经在用的工具和系统，不用手动复制粘贴信息。

什么时候该用 MCP：

  • 需要的上下文在仓库之外（Jira 工单、Confluence 文档、数据库 Schema）
  • 数据频繁变化（不能靠快照）
  • 你想让 Codex 直接操作工具而不是靠文字指令
  • 需要跨用户、跨项目的可重复集成

Codex 支持 STDIO 和 Streamable HTTP（带 OAuth）两种 MCP 服务器。在 Codex 应用中，前往 Settings → MCP servers 管理；在 CLI 中用 codex mcp add 命令添加。

但别一上来就连所有工具。 OpenAI 的建议是：从一两个能消除手动循环的工具开始，验证效果后再扩展。过多的 MCP 服务器会增加上下文噪音，反而降低 Codex 的判断质量。

Skills 和自动化：把经验变成流水线#

当一个工作流变得可重复，就该把它封装成 Skill。Skill 是一个 SKILL.md 文件，定义了 Codex 应该如何执行特定任务，包含指令、上下文和辅助逻辑。

好的 Skill 应该：

  • 聚焦单一职责
  • 明确输入和输出
  • 描述清楚"什么时候用这个 Skill”
  • 包含用户会实际说的触发短语

适合封装成 Skill 的场景：日志分类、Release Note 起草、PR 清单审查、迁移方案规划、事故摘要、标准化调试流程。

当 Skill 稳定之后，可以进一步升级为自动化（Automation）。在 Codex 应用的 Automations 标签页中，你可以设置项目、提示词、执行频率和运行环境。适合自动化的任务包括：总结最近的 commit、扫描潜在 bug、起草 Release Note、检查 CI 失败、生成站会摘要。

一个有用的思考框架：Skill 定义方法，Automation 定义调度。 如果一个工作流还需要频繁干预，先做成 Skill。等它稳定可预测了，再升级为自动化。

常见误区清单#

最后，整理一份 OpenAI 指南中提到的常见错误：

把 AGENTS.md 当垃圾桶。 所有规则一股脑塞进去，结果比 README 还长。正确做法是保持精简，详细内容拆分到独立文档。

不给 Codex 看它的"成绩单"。 不告诉它怎么跑测试、怎么构建，它就无法自我验证。在 AGENTS.md 中写清楚关键命令。

复杂任务跳过计划。 这是会话质量下降的头号原因。不确定的任务，先 Plan 再动手。

一开始就给完全权限。 新仓库应该从严格模式开始，确认安全后再逐步放开。

一个项目一个线程。 应该一个任务一个线程。项目级线程会导致上下文膨胀，输出质量随时间下降。

还没稳定就自动化。 先手动跑通、做成 Skill，稳定后再设置自动化。

把 Codex 当成需要盯着看的工具。 Codex 的真正价值在于并行。你在写代码的同时，它在另一个分支帮你做 code review。

写在最后#

Codex 的进化速度很快。从最初的代码补全，到现在的全栈编程智能体，它正在改变开发者的工作方式。但工具再强，方法不对也白搭。

这份最佳实践的核心思想可以用一句话概括：把 Codex 当成一个需要配置和培养的队友，而不是一个随叫随到的工具。 给它清晰的上下文、明确的约束、可验证的完成条件，然后用 AGENTS.md 把经验沉淀下来。随着使用次数增加，它对你的项目理解越来越深，输出质量也会持续提升。

参考来源：

  • OpenAI Codex 官方最佳实践指南（developers.openai.com/codex/learn/best-practices）
  • OpenAI Codex Best Practices for 2026: Workflows, Governance, and Multi-Provider Routing（getmaxim.ai）