OpenAI Codex 官方最佳实践：从提示词到自动化工作流

OpenAI 官方发布的 Codex 最佳实践指南，涵盖从提示词编写、AGENTS.md 配置、MCP 集成到 Skill 和自动化工作流的完整使用策略。核心理念：不要把 Codex 当一次性助手，而要当作可以持续配置和改进的队友。

核心思路

Codex 的最佳使用方式是一个渐进式体系：正确的上下文 → AGENTS.md 持久化指导 → 配置一致性 → 测试与审查 → MCP 外部集成 → Skill 可复用 → 自动化稳定流程。

1. 第一次使用就给对上下文

Codex 即使提示词不完美也能产出不错的结果，但清晰的上下文能让结果更可靠，尤其在大代码库或高风险任务中。

好的 prompt 应包含四个要素：

要素	说明
Goal	你想改变或构建什么？
Context	哪些文件、文档、示例或错误信息相关？可以用 @ 提及文件
Constraints	需要遵循什么标准、架构、安全要求或约定？
Done when	任务完成的标志是什么？测试通过？行为改变？Bug 消除？

推理等级选择：

等级	适用场景
Low	快速、范围明确的任务
Medium / High	复杂变更或调试
Extra High	长时间、多 Agent、重度推理任务

提示：在 Codex App 中可以用语音输入来描述任务，比打字更快。

2. 复杂任务先规划再编码

不要让 Codex 直接动手写代码。有几种有效的规划方式：

Plan Mode（/plan 或 Shift+Tab）：让 Codex 先收集上下文、提问澄清、制定计划，然后再实现。对大多数用户最有效。
让 Codex 面试你：告诉它先质疑你的假设，把模糊的想法变成具体方案再写代码。
PLANS.md 模板：配置 Codex 遵循执行计划模板，适合长时间多步骤工作流。

3. 用 AGENTS.md 把指导变成持久化配置

AGENTS.md 是给 Agent 看的开放格式 README，自动加载到上下文中。

好的 AGENTS.md 应包含：

仓库布局和重要目录
如何运行项目
构建、测试、lint 命令
工程约定和 PR 期望
约束和禁止规则
"完成"的定义和验证方式

快速生成： 在 CLI 中使用 /init 命令生成起始 AGENTS.md，然后按团队实际情况编辑。

层级结构：

~/.codex/AGENTS.md — 全局个人默认
仓库根目录 AGENTS.md — 团队共享标准
子目录 AGENTS.md — 局部规则（更具体的文件优先）

实用建议：短小精准的 AGENTS.md 比冗长的模糊规则更有用。从基础开始，只在注意到重复错误时才添加新规则。当 Codex 犯同一个错误两次时，要求它做复盘并更新 AGENTS.md。

4. 配置一致性

通过配置让 Codex 跨会话表现一致：

配置层级：

位置	用途
`~/.codex/config.toml`	个人默认配置
`.codex/config.toml`	仓库特定配置
命令行参数	一次性覆盖
`profile-name.config.toml`	Profile 特定覆盖

可配置项包括：模型选择、推理强度、沙盒模式、审批策略、Profile、MCP 设置等。

新手建议：保持默认权限。默认收紧审批和沙盒，只在信任的仓库或特定工作流中放宽。

CLI、IDE 和 Codex App 共享相同的配置层。

5. 用测试和审查提升可靠性

不要让 Codex 只生成代码——让它也测试、检查和审查。

审查流程应包括：

为变更编写或更新测试
运行正确的测试套件
检查 lint、格式化、类型检查
确认最终行为符合需求
审查 diff 中的 bug、回归或风险模式

Codex App 的审查功能：

切换 diff 面板直接审查变更
点击具体行提供反馈，反馈会作为上下文传递给下一轮
/review 命令支持多种审查模式（对比分支、未提交变更、单次提交、自定义审查指令）

团队实践：在 code_review.md 中定义审查标准并在 AGENTS.md 中引用，让审查行为跨仓库保持一致。

6. 用 MCP 连接外部系统

MCP（Model Context Protocol）是连接 Codex 与外部工具系统的开放标准。当所需上下文存在于仓库之外时使用。

适合使用 MCP 的场景：

所需上下文在仓库外
数据频繁变化
希望 Codex 使用工具而非依赖粘贴的指令
需要跨用户或项目的可重复集成

Codex 支持 STDIO 和 Streamable HTTP 服务器（含 OAuth）。

建议：只在能解锁真实工作流时才添加工具。从一个或两个能减少手动循环的工具开始，然后逐步扩展。

7. 把重复工作变成 Skill

Skill 用 SKILL.md 文件、上下文和支持逻辑封装可复用的工作流，适用于 CLI、IDE 和 Codex App。

Skill 创建建议：

每个 Skill 只聚焦一个任务
从 2-3 个具体用例开始
描述要说明 Skill 做什么以及何时使用（包含用户会说的触发短语）
不要一开始就覆盖所有边界情况
只在能提高可靠性时才加入脚本或额外资源

判断标准： 如果你反复使用同一个 prompt 或反复修正同一个工作流，它应该变成一个 Skill。

Skill 存储位置：

$HOME/.agents/skills — 个人 Skill
.agents/skills/ — 团队共享 Skill（签入仓库）

用 $skill-creator 快速创建第一个 Skill。

8. 用自动化执行稳定工作流

当工作流足够稳定后，可以在 Codex App 的 Automations 标签页中安排定期执行。

适合自动化的任务：

总结最近的 commits
扫描潜在 bug
起草发布说明
检查 CI 失败
生成站会总结
定期运行分析工作流

规则：Skill 定义方法，Automation 定义时间表。 如果工作流还需要大量引导，先变成 Skill。可预测之后，自动化才能成为倍增器。

9. 用会话控制管理长期工作

合理管理 Codex 会话对质量影响很大。

CLI 常用命令：

命令	功能
`/plan`	切换 Plan 模式
`/resume`	恢复已保存的对话
`/fork`	创建新分支（保留原始记录）
`/compact`	压缩长对话
`/agent`	在并行 Agent 间切换
`/review`	代码审查

一个线程处理一个逻辑单元的工作。如果仍是同一问题的一部分，留在同一线程中（保留推理轨迹）。只有工作真正分叉时才 fork。

常见错误

错误	正确做法
在 prompt 中塞入持久化规则	移到 AGENTS.md 或 Skill 中
不让 Agent 看到自己的工作结果	提供构建和测试命令的详细说明
多步骤复杂任务跳过规划	先用 Plan Mode 规划
在不理解工作流前就给完全权限	从默认权限开始，逐步放宽
同一文件上运行多个线程不用 worktree	用 git worktree 隔离
工作流不稳定就自动化	先手动跑稳定，再自动化
一步一步盯着 Codex 操作	利用并行性做自己的事
一个项目一个线程	一个任务一个线程，避免上下文膨胀

字节笔记本