Codex 最佳实践

Codex 已经不是单一的命令行工具。OpenAI 现在把它描述成一个能写、审、改、跑代码的 AI coding agent，入口包括 Codex CLI、IDE extension、Codex app、Codex web/cloud，以及 GitHub 上的代码审查工作流。

这意味着“Codex 最佳实践”不再只是 prompt 技巧，而是一套工程协作方法：

• 任务怎么拆
• 上下文怎么给
• 仓库规则怎么沉淀
• 环境怎么配置
• 权限和网络怎么收紧
• 结果怎么验证
• 重复工作怎么自动化

真正好用的 Codex，不是一次性把大需求扔进去等奇迹发生，而是把它当成一个需要配置、需要验收、需要持续校准的工程同事。

先选对工作模式

Codex 的几个主要入口适合不同场景。

CLI：本地结对和快速修改

Codex CLI 适合在当前仓库里做密集交互：读代码、改文件、跑测试、看 diff。你仍然在终端里掌握节奏，适合这些任务：

• 解释陌生模块
• 修一个明确 bug
• 做小范围重构
• 为已有逻辑补测试
• 对未提交改动做本地 review

CLI 的核心优势是反馈快，缺点是你要自己管理上下文、权限和本地环境。

IDE extension：贴近编辑器的协作

IDE extension 适合你已经在编辑器里定位到文件、选区或错误时使用。它比纯 CLI 更适合 UI 修改、局部实现、跟踪当前打开文件。

如果问题来自“我正在看的这段代码”，IDE extension 通常比重新在终端里描述背景更自然。

Codex app：多项目、多线程和本地工作区

Codex app 更像一个 agent 工作台。官方帮助中心提到，Codex app 支持多 agent 并行、跨项目工作、worktree、skills、automations 和 git 功能。

适合放进 app 的任务通常是：

• 多个仓库的并行探索
• 需要隔离 worktree 的实现
• 可复用的技能化流程
• 定期运行的自动化任务
• 需要长期跟进的开发线程

Codex cloud/web：把任务丢到后台

Codex cloud 会为每个任务创建隔离的云端容器，checkout 选定分支或 commit，运行 setup script，然后让 agent 在容器内执行命令、修改代码、验证结果并输出 diff。

适合 cloud 的任务通常更“可委派”：

• 已经写清楚的 issue
• 可并行探索的方案
• 不阻塞你当前编辑器工作的修复
• 需要生成 PR 的后台任务
• 可以通过测试和 diff 验收的改动

如果一个任务需要你不断盯着细节、不断改口径，先在本地 CLI 或 IDE 里澄清会更稳。

写任务像写 GitHub Issue

OpenAI 自己的实践建议是：把 prompt 写得像一个 GitHub Issue，而不是一句愿望。

一个好任务最好包含四件事：

• 目标：要改什么，为什么改
• 上下文：相关文件、目录、报错、截图、文档、参考实现
• 约束：不要改什么，必须遵守什么模式
• 完成条件：测试、lint、截图、diff、行为验收

差一点的说法：

optimize the checkout flow

更好的说法：

In src/checkout/, reduce duplicate payment validation logic. Keep public API response shapes unchanged. Follow the pattern in src/orders/validation.ts. Add or update unit tests, then run the checkout test suite and summarize the diff.

中文也一样：

修改 src/checkout/ 里的重复支付校验逻辑；不要改变公开 API 返回结构；参考 src/orders/validation.ts 的写法；需要补测试并运行 checkout 相关测试；最后说明改了哪些文件和剩余风险。

这种写法不只是让模型“更听话”。它真正解决的是工程里的三个问题：

1. 限制改动范围
2. 降低错误猜测
3. 让结果更容易审查

难任务先 Plan，不要直接 Code

复杂任务最稳的顺序是：

1. 让 Codex 读代码
2. 让 Codex 解释现状
3. 让 Codex 给出计划
4. 人确认范围
5. 再让 Codex 实现
6. 跑验证
7. 审 diff

很多失败都发生在第 1 步和第 2 步被省略的时候。模型还没理解系统，就开始套一个看起来合理的方案。

适合先 plan 的任务包括：

• 跨模块重构
• 数据模型迁移
• 鉴权、支付、权限这类高风险逻辑
• 测试体系改造
• CI/CD 或部署脚本改动
• 你自己也还没完全想清楚的需求

可以这样问：

Read the current authentication flow first. Do not edit files yet.
Explain the request path, list the files likely affected by token refresh,
then propose a minimal implementation plan with validation commands.

等计划靠谱之后，再让它动手：

Implement the approved plan. Keep the public session format unchanged.
Run the auth unit tests and summarize any test gaps before finishing.

这比“直接帮我实现 token refresh”稳定得多。

把有效经验写进 AGENTS.md

Codex 官方文档明确把 AGENTS.md 当成给 agent 的项目说明文件。Codex 会在开始工作前读取这些文件，并按全局、项目、子目录的层级合并；越靠近当前工作目录的指令优先级越高。

一个好用的 AGENTS.md 不该像工程手册，也不该写空话。它只需要放 Codex 很难从代码里稳定推断，但又必须遵守的信息。

建议包含：

• 仓库结构和关键目录职责
• 本地启动、测试、lint、格式化命令
• PR 或提交前的验收要求
• 不能触碰的边界
• 团队特有约定
• 可以参考的实现文件
• 常见坑和已知限制

示例：

# Validation
- Run `pnpm test --filter checkout` after checkout changes.
- Run `pnpm lint` before finishing TypeScript edits.
- For database schema edits, run `pnpm prisma generate`.

# Constraints
- Do not change public API response shapes without explicit approval.
- Do not add production dependencies unless requested.
- Do not read or write secret files; only reference env var names.

# Patterns
- For validation helpers, follow `src/orders/validation.ts`.
- For background jobs, follow `src/jobs/send-digest.ts`.

两类内容要少写：

• “写高质量代码”“遵守最佳实践”这类没有操作性的空话
• 大段制度、历史背景、完整架构文档

一个实用原则是：Codex 犯同一个错误第二次，就把修正后的规则写进 AGENTS.md。

环境质量决定上限

Codex 的很多“能力问题”，本质是环境问题。

在 Codex cloud 里，任务大致会经历这些阶段：

1. 创建容器
2. checkout 仓库
3. 运行 setup script
4. 应用网络访问设置
5. agent 循环执行命令、编辑代码、跑检查
6. 输出结果和 diff

如果依赖装不上、测试命令不可用、环境变量缺失、setup script 不稳定，Codex 很容易开始猜。

最值得优先配置的是：

• 锁定 Node/Python/Go 等运行时版本
• 明确包管理器和安装命令
• 安装 linters、formatters、type checkers
• 把常用验证命令写入 AGENTS.md
• 为 cloud environment 设置必要的环境变量
• 让 setup script 尽量幂等

注意 secrets 和普通环境变量的区别。Codex cloud 文档说明，secrets 只在 setup script 阶段可用，进入 agent phase 前会被移除；不要假设 agent 执行阶段可以读取 secret 值。

这也是为什么 secret 相关任务要写成：

请确认代码读取 OPENAI_API_KEY 环境变量，不要展示或写入密钥值。

而不是把真实密钥粘给 Codex。

权限和网络默认收紧

Codex 的安全模型由两个旋钮组成：

• sandbox mode：技术上允许它读写哪里、能不能联网
• approval policy：什么时候必须停下来问你

官方文档强调，Codex 默认关闭 agent 阶段的网络访问。本地 CLI/IDE 通常通过操作系统沙箱限制写入范围；cloud 则运行在隔离的 OpenAI 托管容器里。

实践上可以这样分层：

低风险任务

可以给更高自动化权限：

• 格式化
• 单元测试
• 只读代码探索
• 文档修订
• 小范围重命名
• 本地 lint 修复

高风险任务

保持更紧权限：

• 安装新依赖
• 修改部署脚本
• 访问公网
• 触碰 secrets
• 数据迁移
• 批量删除或移动文件
• 修改鉴权、支付、权限、审计逻辑

网络尤其要谨慎。Codex cloud 的 agent internet access 默认关闭；如果必须打开，应该只允许必要域名和 HTTP method，并审查 work log。

原因很直接：agent 读取不可信网页、issue、README 或脚本时，可能遇到 prompt injection；联网还会扩大代码或 secret 外泄、恶意依赖、许可证污染等风险。

验证闭环比生成速度重要

不要把 Codex 的最终回答当成验收。真正的验收应该来自：

• 测试是否通过
• lint/type check 是否通过
• 行为是否复现或消失
• diff 是否符合需求范围
• UI 是否通过截图或浏览器验证
• 代码审查是否发现风险

可以把完成条件直接写进 prompt：

Done when:
- `pnpm test --filter auth` passes
- no public API response shape changes
- the final answer lists changed files and any remaining risks

如果没有测试，也可以让 Codex 先补最小测试，或者至少写出人工验证步骤。

对于 PR，Codex 的 /review 和 GitHub review 工作流适合当第二道关。它不是替代人审，而是先抓明显 bug、回归、越界修改和缺失测试。

一个不错的工作流是：

1. Codex 实现
2. Codex 跑测试
3. Codex review 自己的 diff
4. 人看高风险点
5. CI 最后兜底

MCP 只接真正有用的上下文

Codex 支持通过 MCP 接外部系统。它适合解决“上下文不在仓库里”的问题，比如：

• GitHub issue、PR、CI 状态
• Linear/Jira 需求
• Slack 讨论
• 数据库 schema
• 内部文档
• 设计稿或运维系统

但不要一上来把所有工具都接进去。每多一个外部工具，就多一个权限面、故障点和上下文噪声源。

判断是否值得接 MCP，可以问四个问题：

• 这个上下文是否经常变？
• 手动复制是否浪费时间或容易漏？
• Codex 是否需要实际调用工具，而不是只读一段说明？
• 这个集成是否会被重复使用？

如果答案不清楚，先不要接。先用一个高价值 MCP，把工作流跑顺，再扩展。

Skills 适合沉淀方法，Automations 适合安排节奏

OpenAI 最新 Codex 文档把 Skills 和 Automations 放进了最佳实践。

我的理解是：

• AGENTS.md：仓库规则
• MCP：外部上下文和工具
• Skills：可复用的方法
• Automations：稳定任务的执行节奏

比如你每次都让 Codex 用同一套清单做 PR review，那就应该变成一个 skill。Skill 可以包含 SKILL.md、支持脚本、参考资料和明确输入输出。

适合做成 skill 的流程：

• PR review checklist
• release notes 草稿
• 事故复盘摘要
• 日志排障
• 迁移计划
• 前端视觉 QA
• 依赖升级检查

当 skill 已经稳定、输入输出也清楚，就可以进一步变成 automation：

• 每天扫描 CI failure
• 每周总结近期 commits
• 定期检查依赖更新
• 每天生成 standup 摘要
• 定时回顾近期 Codex 会话，把重复摩擦沉淀进规则

一句话：Skills 定义怎么做，Automations 定义什么时候做。

长任务用 worktree 和并行，但别放弃审查

Codex 的云端和 app 工作流鼓励并行：一个 agent 修 bug，一个 agent 补测试，一个 agent 做 review，一个 agent 写迁移方案。

并行确实有价值，但前提是任务能拆成互不冲突的写入范围。

适合并行：

• 一个 agent 改后端，另一个改文档
• 一个 agent 写测试，另一个调查 bug 根因
• 多个 agent 生成不同方案，再人工选一个
• 一个 agent 实现，另一个只做 review

不适合并行：

• 多个 agent 同时重构同一批文件
• 需求还没定就开多个实现
• 数据库 schema 和调用方同时无协调修改
• 共享抽象还没稳定就让多个 agent 依赖它

如果要用 Best-of-N 或多 agent 方案，最好在 prompt 里要求每个结果说明：

• 采用的关键假设
• 改动范围
• 风险
• 验证方式
• 为什么这个方案比替代方案更合适

不要只看“哪个 diff 最大”或“哪个回答最自信”。

用 /goal 驱动长周期任务

/goal 是 Codex CLI 的一个实验性功能，让 Codex 在多轮对话中持续推进一个目标，直到达到可验证的终止条件，而不是每次都在单轮对话结束后停下来。当你用 /goal 时，Codex 可以连续工作数小时而不需要你介入。

启用方式：从 /experimental 开启，或在 config.toml 的 [features] 下添加 goals = true。之后用 /goal <目标> 设定任务，/goal 查看状态，/goal pause / resume / clear 控制运行。

一个好的 goal 比单条 prompt 大，但比模糊的待办列表小。核心在于契约：Codex 必须在开始前就知道"完成"意味着什么。如果 goal 是迁移，“完成"可能意味着新路径通过契约测试、旧路径还保留回滚能力。如果 goal 是原型，“完成"可能意味着应用能构建、能运行、行为与预期一致。

适合 /goal 的场景

适合放进 goal 的任务：

• 代码迁移：目标技术栈、兼容性检查和约束都已清楚定义
• 大型重构：Codex 可以在每个 checkpoint 后跑测试验证
• 实验、游戏或原型：Codex 可以持续改进一个可运行的产物
• Prompt 优化：有 eval suite 时，Codex 可以自动检查失败、更新 prompt、重跑 eval，直到评分达标

不适合：松散的一批互不相关的任务。

建立 Goal 循环的六步

1. 定义一个目标和一个终止条件
2. 告诉 Codex 需要先读哪些文件、文档、issue、日志或计划
3. 定义什么命令或产物能证明进展
4. 要求 Codex 按 checkpoint 工作，并记录简短的进度日志
5. 运行过程中用 /goal 查看状态
6. 任务完成、卡住或方向改变时，pause / clear

一个好的起点：先和 Codex 聊几句你想做什么，再让它直接设定 goal 并开始工作。

让 Codex 独立运转

Goal 运行期间，要求 Codex 给出紧凑的进度更新：当前 checkpoint、验证了什么、还剩什么、是否遇到阻塞。如果进度描述开始变模糊，优先收紧 goal 定义——告诉 Codex 下一个关键 checkpoint 是什么、用哪条命令证明、什么情况下应该暂停——而不是堆更多临时指令。

Codex 在合理判断达到终止条件后会自动停下来。把 /goal 当成一个后台任务，而不是一场需要盯着的对话。

三类典型示例

迁移 — 把代码库、移动端或游戏迁移到新技术栈：

/goal 把 payment 模块从 stripe-v2 迁移到 stripe-v3。
先读 docs/stripe-v3-migration.md。
按 checkpoint 工作，每次处理一个接口，完成后跑 `pnpm test --filter payment` 并记录结果。
当所有 payment 测试通过且代码中不再有 v2 的引用时停止。
不要改变公开 API 的返回结构。

原型 — 从零构建一个应用、游戏或功能到可交付状态：

/goal 实现 PLAN.md 描述的 CLI 工具。
先读 PLAN.md 了解范围和约束。
按 PLAN.md 的阶段划分 checkpoint。
每个阶段结束后验证工具可以构建并通过冒烟测试。
当所有阶段完成且最终冒烟测试通过时停止。

Prompt 优化 — 对着 eval 结果持续迭代直到达标：

/goal 优化 prompts/summarize.txt 里的摘要 prompt。
用 `python evals/run.py` 测量准确率。
检查失败样本，更新 prompt，重跑 eval。
当准确率达到 85% 或已跑 20 轮时停止。
每轮记录评分和 prompt 版本。

Codex 费用参考

Codex 使用基于 token 的积分（credits）计费模型，按每百万 token 计算费用，不同模型和 token 类型（输入 / 缓存输入 / 输出）对应不同费率。下表为撰写时的 Rate Card 数据，最新数据以 官方 Codex Rate Card 为准。

1 积分 ≈ $0.01。代码审查目前默认使用 GPT-5.3-Codex 模型（以官方 Rate Card 为准）。官方数据显示，典型使用场景下每位开发者每月费用大约在 $100–$200 之间，实际差异较大。可以在 Codex 设置的 Usage 面板查看积分消耗情况。

几个值得注意的点：

• 缓存输入便宜得多：Codex 在多轮任务中重复读取同一份仓库内容时会自动命中缓存，费率大幅降低。长上下文、长周期的 goal 受益最明显。
• 按任务重要性选模型：高风险、高价值的任务用更高质量的模型；探索性或重复性任务用较小的模型降低消耗。
• 清楚的终止条件能省钱：没有明确终止条件的任务可能跑很久而没有有效输出，好的完成条件让 Codex 更早停下来。

费用控制就是任务设计的一部分——清楚的终止条件既是质量要求，也是省钱的手段。

代码审查要给 Codex 明确角色

Codex 的 code review 能力已经成为官方重点功能。OpenAI 的升级文章提到，Codex 可以根据 PR 意图、diff、代码库和依赖来找关键问题，也可以在 GitHub PR 上自动或通过 @codex review 触发。

但 review prompt 仍然很重要。

差一点的说法：

review this PR

更好的说法：

Review this PR for correctness, security, and regression risk. Focus on changed behavior, missing tests, data migrations, and public API compatibility. Do not comment on style unless it hides a bug.

如果团队有自己的审查标准，把它写进 code_review.md，再从 AGENTS.md 引用。这样 Codex 不会每次按不同口径 review。

我建议把 Codex review 定位为：

• 第一轮自动筛查
• 补充人类 reviewer 的注意力
• 抓重复错误和明显回归
• 检查验收条件是否真的完成

不要把它定位为：

• 架构最终裁决
• 安全最终背书
• 业务语义最终确认
• CI 和人工验证的替代品

一个可复制的 Codex 工作流

真实项目里，我会用这个默认流程：

1. 准备规则：维护根目录 AGENTS.md，写清目录、命令、约束、验收标准。
2. 描述任务：按目标、上下文、约束、完成条件写 prompt。
3. 先问计划：复杂任务先让 Codex 读代码并出计划。
4. 限定范围：明确可改文件、不可改行为和验证命令。
5. 让它实现：小步提交或小步 diff，不要一次性吞大需求。
6. 跑验证：测试、lint、type check、截图或手动验证步骤。
7. 二次 review：让 Codex review diff，再由人审高风险点。
8. 沉淀经验：重复出现的问题写回 AGENTS.md、skill 或 automation。

可以直接复用这个 prompt 模板：

Goal:
<要实现或修复什么>

Context:
- Relevant files: <文件/目录>
- Reference pattern: <参考实现>
- Error/output: <报错或现象>

Constraints:
- Do not change <边界>
- Follow <本仓库模式>
- Ask before <高风险动作>

Done when:
- <测试命令> passes
- <行为验收> is true
- Final response includes changed files, validation results, and remaining risks

常见反模式

反模式 1：一口气扔一个巨型需求

rebuild the billing system

更好的做法是先让 Codex 画出现状、风险和拆分计划，再逐个子任务执行。

反模式 2：不给验证命令

没有验证命令时，Codex 只能靠静态推理。静态推理有价值，但不能替代运行结果。

反模式 3：把 secrets 粘进 prompt

永远只引用变量名，不展示真实值。仓库里也只应该提交 .env.example，不要提交 .env。

反模式 4：AGENTS.md 写得太泛

“写好代码”“保持简洁”不会让结果明显变好。具体命令、具体边界、具体参考文件才有用。

反模式 5：盲目打开网络

联网能解决依赖下载和实时资料问题，也会引入 prompt injection、数据外泄和供应链风险。默认关闭，需要时最小开放。

反模式 6：把 review 当形式

Codex 改完后，至少看 diff、跑测试、让它解释风险。否则你只是把编码时间转移成了排查时间。

结论

Codex 的关键能力不是“自动写代码”，而是把读代码、计划、实现、测试、review、自动化这些动作串成一个 agent loop。

所以最佳实践也不是一组神奇 prompt，而是一套工程纪律：

• 任务要小而清楚
• 上下文要可定位
• 规则要沉淀
• 环境要可复现
• 权限要最小化
• 结果要能验证
• 重复流程要工具化

把这些做好，Codex 才更像可靠的工程同事，而不是一个偶尔惊艳、偶尔失控的代码生成器。

参考资料

• Using Codex with your ChatGPT plan
• Codex best practices
• Custom instructions with AGENTS.md
• Codex cloud environments
• Agent internet access
• Agent approvals & security
• Codex CLI features
• How OpenAI uses Codex
• Introducing upgrades to Codex
• Unrolling the Codex agent loop
• Codex changelog
• Follow a goal use case
• Codex Rate Card