这两天我又系统看了一遍 Codex 的官方手册，也顺手搜了英文教程、中文博客、GitHub 讨论和一些公开模板仓库。最后我没有把网上所有“技巧”都照单全收，而是按一个标准筛选：能不能被官方文档或真实工作流印证，能不能在日常项目里降低返工，能不能让 Codex 更稳定地理解你的习惯。

我的结论很简单：高效使用 Codex 的重点不是写一条神级提示词，而是把它从“聊天框”调成“工作流”。

我怎么验证这些建议

这篇文章主要参考了几类来源：

  • OpenAI Codex 官方文档：Best practices、Prompting、AGENTS.md、Skills、MCP、Subagents、Automations、Memories。
  • GitHub 上 openai/codex 的公开讨论，尤其是 Plan / Spec Mode、Plan Mode、不同模式模型配置等讨论。
  • 独立开发者和团队写的 Codex 使用文章，例如 Codex CLI guide、可靠工作流实践、中文配置体系文章。
  • GitHub 上一些 AGENTS.md / Skills / Subagents 模板仓库。

我保留的是多处来源能互相印证、并且符合官方机制的做法。没有采信的是这几类内容：过度依赖某个第三方魔改客户端、只适合单个作者习惯的超长提示词、没有验证方式的模型分数比较、以及把所有规则都塞进一个巨大 AGENTS.md 的做法。

1. 用四要素写任务，而不是只写愿望

Codex 可以处理模糊任务，但越大的项目越需要结构。一个好任务最好包含四件事：

1
2
3
4
目标：我要改什么、做什么、修什么
上下文：相关文件、报错、截图、链接、已有实现
约束：不要动什么、必须遵守什么风格
完成标准：跑什么测试、看到什么结果算完成

比如不要只说“优化首页”，而是说：

1
2
3
4
目标：优化首页首屏加载速度。
上下文：首页在 src/pages/index.tsx，图片来自 public/hero。
约束：不改视觉风格，不引入新依赖。
完成标准：npm run build 通过，Lighthouse Performance 到 90 以上。

这不是为了写得漂亮，而是为了让 Codex 有可检查的终点。

2. 复杂任务先开 Plan Mode

官方和社区文章都反复提到 Plan Mode。它的价值不是“让 Codex 多想一会儿”，而是让 Codex 在动手前先读上下文、暴露风险、提出取舍。

在 Codex App 里可以输入：

1
/plan

也可以按：

1
Shift + Tab

适合先计划的任务包括：跨文件重构、复杂 bug、架构迁移、发布流程、性能优化、UI 重做。小改动不用每次都计划，否则会把简单任务做重。

我常用的开场是：

1
先不要改代码。请进入计划模式，阅读项目后给我实现方案、风险点和需要确认的问题。

3. 把重复偏好写进 AGENTS.md

如果你每次都要提醒“用中文回答”“不要大重构”“先跑测试”“不要覆盖我已有改动”，说明这些话不该继续留在 prompt 里，而应该写进 AGENTS.md。

全局个人偏好可以放：

1
~/.codex/AGENTS.md

项目规则放在项目根目录：

1
AGENTS.md

更细的模块规则可以放到子目录。官方文档明确说明，离当前工作目录更近的指令优先级更高。

一个实用的 AGENTS.md 不需要长，最好覆盖：

  • 项目怎么运行、构建、测试。
  • 哪些目录最重要。
  • 代码风格和 PR 预期。
  • 禁止事项。
  • 什么叫完成，如何验证。

我的经验是：AGENTS.md 应该短、准、常维护。每次 Codex 犯同一种错第二次，就让它复盘并补一条规则。

4. 不要把 AGENTS.md 写成百科全书

网上有些模板会把所有流程、所有角色、所有命令都塞进 AGENTS.md。短期看很强，长期会变成上下文噪音。

更合理的分层是：

  • AGENTS.md：项目长期规则和协作约定。
  • Skills：重复的任务流程。
  • config.toml：模型、权限、MCP、功能开关等个人或项目配置。
  • Memories：辅助记住稳定偏好，不替代强规则。
  • Automations：定时或后台重复执行的任务。

AGENTS.md 是“规矩”，Skill 是“做法”，MCP 是“外部能力”，Automation 是“什么时候自动做”。

5. 把第三次重复的流程做成 Skill

如果同一个流程你已经说了三遍，就该考虑做 Skill。

适合做 Skill 的例子：

  • 发布博客。
  • 做 PR review。
  • 生成发布说明。
  • 把视频整理成文章。
  • 按固定格式排查线上故障。
  • 按团队标准写测试。

Skill 的核心是 SKILL.md，里面写清楚何时触发、输入是什么、输出是什么、步骤是什么。官方文档还提到，Codex 会先看到 Skill 的名称和描述，只有真的要用时才加载完整说明。这比把所有流程常驻塞进 AGENTS.md 更节省上下文。

6. MCP 只接真正需要的外部系统

MCP 的价值是让 Codex 直接访问仓库外的上下文，例如 GitHub、Figma、Linear、文档系统、浏览器、Sentry、内部知识库等。

但 MCP 不是越多越好。每多一个外部连接，就多一份权限、故障和安全边界。我的建议是从最常用的三个开始：

  • 文档类：OpenAI Docs、Context7、内部文档。
  • 开发类：GitHub、浏览器、Playwright。
  • 产品类：Figma、Linear、Issue 系统。

如果某个 Skill 需要 MCP，最好在 Skill 的元数据里声明依赖。这样“流程”和“工具”是绑定的，不会每次靠人提醒。

7. Subagents 先用于读和审查，不急着并行写代码

Subagents 很有用，但也最容易被滥用。官方文档的重点很清楚：它适合把高噪声任务从主线程移出去，比如探索、测试、日志分析、审查和总结。

比较稳的用法是：

1
2
3
4
5
请用 subagents 并行审查当前改动：
1. 一个 agent 查安全风险
2. 一个 agent 查测试缺口
3. 一个 agent 查可维护性问题
等全部完成后，由主 agent 汇总，不要让多个 agent 同时改同一批文件。

我不建议一开始就让多个子 agent 同时写代码。并行读很香，并行写很容易冲突。

8. 权限从小开，不要一开始就全放开

很多效率问题其实是权限和工作目录问题：Codex 看不到正确目录、不能写该写的文件、不能运行测试，或者反过来权限太大导致风险变高。

主流做法是：

  • 新项目先保守权限。
  • 熟悉项目后给 workspace 写权限。
  • 只有可信仓库和明确任务才考虑更高权限。
  • 自动化任务尤其要谨慎，因为它是无人值守执行。

权限不是越大越高效。可控、可复现、可回滚，才是真正高效。

9. 给每个任务一个验证门槛

不要让 Codex 自己猜“完成了”。你要告诉它怎么验证。

常见完成标准包括：

  • 指定测试通过。
  • 构建通过。
  • lint 或 type check 通过。
  • 浏览器页面截图确认。
  • 某个 bug 的复现步骤不再失败。
  • 生成的文件、接口或页面符合预期。

我最常用的一句话是：

1
完成后请运行最相关的验证命令，并说明命令、结果和仍未覆盖的风险。

这能显著减少“看起来写完了，但其实没跑过”的情况。

10. 长任务用状态文档或 Goal，不要全靠聊天历史

长任务会遇到上下文压缩、会话中断、需求变化。只靠聊天历史，很容易越做越糊。

官方 Cookbook 里提到 PLANS.md / ExecPlan 这类做法，本质是把计划、进度、发现、决策和验证结果写进一个活文档。你也可以用更轻量的方式：

1
TASK_PROGRESS.md

记录：

  • 当前目标。
  • 已完成。
  • 正在做。
  • 阻塞点。
  • 决策记录。
  • 验证结果。

如果 Codex App 里开启了 Goal，也可以用 /goal 给长任务一个持续目标。关键是让“目标和完成标准”不只存在于聊天窗口里。

11. 自动化只自动化已经稳定的流程

Automations 很适合定时巡检、部署后检查、PR 追踪、构建健康检查、周期性整理报告。

但不要把还没跑顺的流程直接自动化。比较稳的顺序是：

1
手动跑通 -> 写成 Skill -> 小范围验证 -> 再做 Automation

自动化的 prompt 要写清楚三件事：

  • 每次醒来要做什么。
  • 什么情况需要报告。
  • 什么情况应该停止或请求人工输入。

否则后台任务很容易变成“定时产生噪音”。

12. 让 Codex 做复盘，而不是只做结果

真正让 Codex 越来越懂你的，是复盘循环。

当它做错了，不要只说“改掉”。可以说：

1
请复盘这次为什么跑偏。哪些规则应该写入 AGENTS.md，哪些流程应该沉淀成 Skill？

如果是项目规则，写进 AGENTS.md。
如果是重复流程，写成 Skill。
如果是外部系统信息，接 MCP。
如果是周期任务，做 Automation。
如果只是个人偏好，可以放在全局 AGENTS.md 或 Memories。

一套我推荐的落地顺序

如果你是刚开始认真用 Codex，我建议按这个顺序来：

  1. 先固定四要素 prompt。
  2. 给常用项目写一个短 AGENTS.md。
  3. 把构建、测试、验证命令写清楚。
  4. 复杂任务先用 Plan Mode。
  5. 第三次重复的流程做 Skill。
  6. 只接必要 MCP。
  7. 子 agent 先用于探索和审查。
  8. 稳定后再上自动化。

这套顺序的好处是不会一开始就过度工程化。Codex 的高效不是靠一次配置到完美，而是靠每次真实摩擦后的沉淀。

参考资料

最后一句：不要把 Codex 当成一个每次都要重新教育的聊天窗口。把你的经验写进合适的位置，它就会慢慢变成一个越来越懂你的工作系统。