Codex 最佳实践

2026-05-03 约 4915 字预计阅读 10 分钟

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 相关测试；最后说明改了哪些文件和剩余风险。

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

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

难任务先 Plan，不要直接 Code

复杂任务最稳的顺序是：

让 Codex 读代码
让 Codex 解释现状
让 Codex 给出计划
人确认范围
再让 Codex 实现
跑验证
审 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 里，任务大致会经历这些阶段：

创建容器
checkout 仓库
运行 setup script
应用网络访问设置
agent 循环执行命令、编辑代码、跑检查
输出结果和 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、回归、越界修改和缺失测试。

一个不错的工作流是：

Codex 实现
Codex 跑测试
Codex review 自己的 diff
人看高风险点
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 最大”或“哪个回答最自信”。

代码审查要给 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 工作流

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

准备规则：维护根目录 AGENTS.md，写清目录、命令、约束、验收标准。
描述任务：按目标、上下文、约束、完成条件写 prompt。
先问计划：复杂任务先让 Codex 读代码并出计划。
限定范围：明确可改文件、不可改行为和验证命令。
让它实现：小步提交或小步 diff，不要一次性吞大需求。
跑验证：测试、lint、type check、截图或手动验证步骤。
二次 review：让 Codex review diff，再由人审高风险点。
沉淀经验：重复出现的问题写回 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 才更像可靠的工程同事，而不是一个偶尔惊艳、偶尔失控的代码生成器。