Codex 项目实战
真正稳定的用法不是“给一句需求，等它写完”，而是让 Codex 按探索、计划、实现、验证、审查、交付的顺序闭环。
核对日期 2026-07-15 · CLI 示例实测于 codex-cli 0.144.3 · 配套阅读：入口与快速开始 · 桌面 App · CLI
入口说明
下面的提示词可以在 App、CLI 或 IDE 中使用。需要可视化 diff、集成终端和 Worktree 时优先用 App；需要脚本化输入输出时用 CLI；只围绕当前文件或选区时用 IDE。无论入口如何，验证命令和 Git diff 必须来自同一个实际工作区。
实战总流程
| 阶段 | Codex 要做什么 | 你要确认什么 |
|---|---|---|
| 探索 | 阅读代码、文档、Git 状态和测试 | 它是否找对入口、没有凭空猜测 |
| 计划 | 拆分步骤、风险和验证方式 | 方案是否符合业务与边界 |
| 实现 | 做范围明确的修改 | diff 是否集中、是否引入多余依赖 |
| 验证 | 跑测试、lint、类型检查或构建 | 命令是否真实执行、失败是否说明 |
| 审查 | 检查回归、安全和遗漏 | 结论是否按严重程度、有文件依据 |
| 交付 | 汇报结果与剩余风险 | 你能否快速复核并继续工作 |
复杂任务使用 /plan 先做前两步。计划得到确认后，再明确说“按刚才的计划实现并验证”。
实战一：快速读懂陌生项目
先用只读模式启动：
codex -s read-only输入：
先不要修改文件。请像接手项目的高级工程师一样阅读这个仓库。
请输出：
1. 项目目标、技术栈和启动入口；
2. 主要目录及职责；
3. 一次用户请求经过的关键调用链；
4. 安装、开发、测试、构建命令，注明依据文件；
5. 当前 Git 状态和明显风险；
6. 你无法从代码确认的问题。
不要只复述 README；所有结论尽量引用具体路径。接着让它补一份项目规则草案：
根据刚才确认的信息，起草一份简短 AGENTS.md。
只写能从仓库验证的命令和约束；不确定的内容放到“待团队确认”，不要编造。人工核对后再保存。项目说明一旦写错，会让后续每个任务都稳定地走错方向。
实战二：修复一个可复现的 Bug
一个可靠的修复请求需要“现象、复现、范围、验证”：
修复：用户连续点击两次“提交订单”时，偶尔会创建两条订单。
复现：
1. 启动测试环境；
2. 在订单确认页快速双击提交按钮；
3. 可以看到两次 POST /orders。
请按以下顺序工作：
1. 先阅读相关页面、请求封装和现有测试；
2. 复现并说明根因，不要先猜修复；
3. 添加能失败的回归测试；
4. 做最小修复，不修改后端接口；
5. 运行相关测试、类型检查和 lint；
6. 审查 diff，确认没有破坏键盘操作和错误重试；
7. 最后列出根因、修改文件、验证命令和结果。如果它没能复现，不要让它“凭经验修”。改为要求：
停在诊断阶段。列出已经验证的事实、无法复现的原因，以及还需要哪一条日志或环境信息。
不要修改生产代码。实战三：开发一个完整小功能
以“订单列表增加状态筛选”为例。
第一步：计划
输入 /plan，然后发送：
为订单列表增加状态筛选：全部、待支付、已支付、已取消。
筛选条件要同步到 URL，刷新和前进后退后保持一致。
请先调查：
- 当前列表的数据获取和路由参数方式；
- 是否已有可复用筛选组件；
- 相关测试如何组织；
- 移动端布局约束。
输出实施步骤、会修改的文件、测试方案和风险。
现在不要改代码。你需要检查：它是否复用了现有模式、是否理解 URL 是状态来源、是否覆盖浏览器历史和空结果。
第二步：实现
按已确认的计划实现。
约束：
- 不新增状态管理依赖；
- 不修改服务端接口；
- 查询参数使用 status；
- 非法状态值回退到“全部”；
- 保持现有桌面和移动端布局。
完成前运行相关单元测试、类型检查、lint 和构建。
如果测试环境本身失败，保留原始错误并区分“本次引入”和“已有问题”。第三步：验收
先不要继续改代码。请对照原始需求审查当前 diff：
- 是否遗漏刷新、前进后退、非法参数、空结果；
- 是否有无关修改；
- 测试是否真正覆盖行为而不是实现细节；
- 是否存在可访问性或移动端回归。
发现问题按严重程度列出；确认无问题后给出最终验收摘要。实战四：安全地做重构
重构最容易变成“改了很多，但无法证明行为没变”。提示词要锁住外部行为：
重构 src/services/payment.ts，目标是拆分支付渠道选择和请求发送逻辑。
外部行为必须保持不变：
- 导出的函数名和参数不变；
- 错误类型和错误码不变；
- 重试次数、超时和日志字段不变；
- 不升级依赖，不修改调用方。
先列出现有可观察行为和测试缺口。
必要时先添加特征测试，再分小步重构。
每一步都运行相关测试，最后比较 diff 并说明为什么行为等价。如果当前测试不足，先让 Codex 写“特征测试”，把已有行为固定下来，再动结构。
实战五：处理测试失败
把真实输出通过标准输入交给 Codex，比口述“测试挂了”更准确：
npm test 2>&1 | codex exec --ephemeral \
"分析失败测试，区分根因和连带失败。只给诊断和最小修复建议，不修改文件。"交互会话中可以这样要求：
运行与当前改动最相关的测试。
如果失败：
1. 保留完整的首个根因错误；
2. 判断是实现、测试、环境还是依赖问题；
3. 不要通过删除断言、跳过测试或扩大超时来掩盖问题；
4. 修复后重新运行同一命令，再跑更广的检查。实战六：代码审查
审查未提交内容：
codex review --uncommitted相对主分支审查：
codex review --base main审查某个提交：
codex review --commit COMMIT_SHA需要按基线审查：
codex review --base main需要自定义审查标准时单独使用 prompt：
codex review "重点检查权限绕过、数据竞争和缺失测试；按严重程度输出，只报告可验证的问题"--uncommitted、--base、--commit 与自定义 prompt 互斥，不能写在同一条命令中。
高质量审查结果应该包含具体文件位置、触发条件、影响和修复方向，而不是泛泛的“建议优化”。
实战七：前端页面验收
不要只让 Codex 看组件代码。要求它运行页面并检查真实状态：
完成页面修改后启动本地开发服务器，并验证：
- 1440×900 桌面视口；
- 390×844 移动视口；
- 加载、空数据、错误、长文本和禁用状态；
- 键盘可操作性与焦点状态；
- 控制台错误和失败请求。
对页面截图做视觉检查，确认没有文字溢出、遮挡、布局跳动或横向滚动。
发现问题后修复并重新验证。如果当前环境没有浏览器能力，Codex 应明确说明缺少哪项验证，而不是声称“页面正常”。
入口要分清：
- ChatGPT 桌面 App：安装或启用 bundled Browser plugin 后，在提示词中使用
@Browser。它使用独立浏览器环境；提交表单、发送信息等敏感动作仍应人工确认。 - CLI / IDE：没有相同的内置 Browser 入口。项目应接入 Playwright 命令、测试脚本或经过审查的 browser MCP，再要求 Codex运行并保存证据。
- Chrome extension / Computer Use：会接触登录态网站或桌面 App，权限和数据面更大。先确认 profile、站点范围、文件下载、外部写入和敏感操作确认，不要默认复用个人浏览器状态。
浏览器能看到真实页面，不等于自动证明后端数据、邮件、付款或第三方写入成功；关键外部状态必须用对应系统的只读查询再次验证。
实战八：非交互自动化
codex exec 适合脚本、CI 和批处理。它默认以只读沙箱运行，自动修改时要显式给出工作区写权限。
生成仓库风险摘要：
codex exec --ephemeral \
"阅读仓库并列出五个最高风险区域。引用文件路径，不修改文件。"输出 JSONL 供脚本消费：
codex exec --json "总结当前仓库结构，不修改文件" > codex-events.jsonl只保存最终消息：
codex exec -o review.md \
"审查当前未提交改动，按严重程度输出可验证的问题，不修改文件"允许在当前工作区修复：
codex exec --sandbox workspace-write \
"修复现有 lint 错误，只修改直接相关文件，并重新运行 lint"自动化边界
不要在包含不可信仓库代码的同一进程环境中暴露长期 API Key。CI 中优先使用官方 Codex GitHub Action、短期凭据和最小仓库权限，并把“生成补丁”和“推送或开 PR”拆成不同权限阶段。
让结果更稳定的复盘法
任务完成后，可以追加一轮：
复盘这次任务：
1. 哪些信息最晚才发现，导致了返工；
2. 哪条项目约定应该写进 AGENTS.md；
3. 哪个验证步骤应该变成固定命令；
4. 有没有不应长期保留的临时配置。
只提出有本次证据支持的改进。把反复出现的问题写入规则，把稳定的多步骤流程做成技能或脚本。不要把一次性的特殊要求永久化。
交付前检查清单
- 目标与边界是否仍和最初一致。
git diff中是否只有相关修改。- 新行为是否有回归测试或可重复验证步骤。
- lint、类型检查、测试、构建是否真实执行。
- 失败项是否保留原始错误并说明影响。
- 是否意外记录了密钥、日志、缓存或构建产物。
- 最终摘要能否让另一位工程师快速复核。