Codex 官方工作流指南｜IDE/CLI/云端全场景标准化开发实践

Codex 的最佳使用方式是将其视为具备明确上下文感知能力的团队成员，通过清晰的任务描述、完整的上下文传递与可验证的完成标准，实现高效协同开发。本文基于 OpenAI 官方工作流文档，整理9 套标准化端到端工作流，覆盖代码解读、Bug 修复、测试编写、原型开发、迭代优化、云端重构、代码审查、文档更新全场景，同时明确 IDE 扩展、CLI、Codex Cloud 三种使用端的差异与最佳实践，新手可直接照搬使用。

一、工作流通用基础规则

1.1 核心协作原则

• 所有工作流遵循目标 + 上下文 + 约束 + 完成标准四要素提示结构

• 明确 “完成定义”：Codex 需完成哪些校验、测试、检查才算任务结束

• 上下文传递：IDE 自动带入打开文件；CLI 需显式使用 @文件路径 或 /mention 附加文件

1.2 终端差异速览

二、9 套官方标准工作流（含步骤 + 提示 + 验证）

工作流 1：代码库解读（新人上手 / 接手服务）

适用场景：新成员入职、接手现有服务、梳理请求流程 / 数据模型 / 协议
适用端：IDE 扩展（最快）、CLI

IDE 扩展步骤

1. 打开核心相关文件

2. 选中需分析的代码（可选但推荐）

3. 输入提示词

解释选中代码的请求流转流程，包含：
1. 涉及模块的职责摘要
2. 数据校验的位置与规则
3. 修改时需注意的 1-2 个坑点

1. 验证：要求输出结构化清单

将请求流程总结为步骤列表，并列出所有涉及的文件

CLI 步骤

1. 仓库根目录启动交互式会话：codex

2. 附加文件并输入提示

读取 @foo.ts @schema.ts，解释服务使用的协议、Schema 与请求/响应流程，重点说明必填/可选字段与兼容规则

工作流 2：可复现 Bug 修复

适用场景：本地可复现的功能异常、逻辑错误
适用端：CLI（闭环复现验证）、IDE 扩展

CLI 完整流程

1. 仓库根目录启动 Codex：codex

2. 提供完整复现步骤 + 约束

Bug：设置页点击“保存”显示成功但数据未持久化
复现步骤：
1. 启动应用：npm run dev
2. 进入 /settings
3. 切换“启用提醒”开关
4. 点击保存
5. 刷新页面，开关恢复原状
约束：
- 不修改接口结构
- 最小化修改，尽可能补充回归测试

1. 验证：修复后自动复现校验

修复完成后，运行 lint 与最小化相关测试套件，返回命令与结果

IDE 扩展流程

1. 打开可疑文件与调用方文件

2. 输入提示

找到导致“显示保存成功但未持久化”的 Bug，给出修复方案并说明 UI 验证方法

工作流 3：单元测试编写

适用场景：为函数 / 模块编写覆盖正常场景与边界情况的单元测试
适用端：IDE 扩展（选中精准）、CLI

IDE 扩展步骤

1. 打开目标函数文件

2. 选中函数代码，命令面板选择 Add to Codex Thread

3. 输入提示

按照项目现有测试规范，为该函数编写单元测试

CLI 步骤

为 @transform.ts 中的 invert_list 函数添加测试，覆盖正常场景与边界情况

工作流 4：截图转可运行 UI 原型

适用场景：基于设计截图 / 原型稿快速生成可运行页面
适用端：CLI（图片附加）、IDE 扩展

CLI 步骤

1. 保存截图至本地（如 ./specs/ui.png）

2. 启动 Codex，拖拽图片附加到对话

3. 输入提示

根据截图创建仪表盘页面
约束：
- 使用 React+Vite+Tailwind，TypeScript 编写
- 严格匹配间距、排版、布局
交付物：
- 新页面路由与渲染代码
- 所需小组件
- 本地运行说明 README.md

1. 验证：要求启动服务并告知访问地址

启动开发服务器，告知原型预览的本地 URL

IDE 扩展步骤

1. 拖拽粘贴截图到 Codex 聊天

2. 输入提示

根据截图创建设置页面，遵循项目现有设计与样式规范

工作流 5：UI 实时迭代优化

适用场景：设计→调整→刷新→微调的快速视觉迭代
适用端：CLI + 本地服务并行

操作步骤

1. 单独终端启动开发服务：npm run dev

2. Codex 中输入优化指令

为首页提出 2-3 项样式优化方案

1. 选定方向后精准迭代

采用方案2，仅修改头部：
- 优化排版为编辑风格
- 增加间距
- 保证移动端适配

1. 验证：浏览器实时预览，确认后提交，回退需告知 Codex

工作流 6：云端托管重构任务

适用场景：大型模块重构，本地规划 + 云端异步执行
适用端：IDE（规划）→ Codex Cloud（执行）

本地规划（IDE）

1. 提交 / 暂存现有代码，保证对比干净

2. 生成重构计划（可显式调用 $plan 技能）

我们需要重构认证子系统，目标：
- 拆分职责（令牌解析/会话加载/权限控制）
- 减少循环引用
- 提升可测性
约束：
- 无用户可见行为变更
- 保持公共 API 稳定
- 输出分步迁移计划

1. 审核并调整计划：明确文件迁移步骤 + 回滚方案

云端执行（IDE→Cloud）

1. 选择云端环境

2. 输入指令分步执行

执行计划中的里程碑1

1. 审查云端 diff，完成后拉回本地或直接创建 PR

工作流 7：本地代码审查

适用场景：提交 / PR 前的本地自检
适用端：CLI

操作步骤

1. 启动 Codex：codex

2. 运行审查命令

/review

1. 自定义审查焦点

/review 重点检查边界情况与安全问题

1. 验证：根据反馈修复后重新审查

工作流 8：GitHub PR 在线审查

适用场景：无需拉取分支，直接在线审查 PR
适用端：GitHub（需提前开启 Codex Code Review）

操作步骤

1. 打开目标 GitHub PR

2. 评论区标记 Codex 并指定审查方向

@codex review

@codex review 审查安全漏洞与权限问题

工作流 9：项目文档更新

适用场景：修正 / 补充项目文档，保证准确可用
适用端：IDE、CLI

操作步骤

1. IDE 打开 / CLI @ 指向文档文件

2. 输入提示

更新“高级特性”文档，补充认证排查指南，校验所有链接有效性

1. 验证：查看渲染后的页面确认效果

三、工作流串联最佳实践

1. 复杂任务拆分：先规划（工作流 6）→ 再开发 → 写测试（工作流 3）→ 审查（工作流 7）→ 文档（工作流 9）

2. 上下文复用：高频规范写入 AGENTS.md，避免重复说明

3. 必做验证：所有修改后必须运行校验、测试、审查，不直接合并未验证代码

4. 终端搭配：本地快速修改用 IDE，批量 / 脚本用 CLI，长时间任务用 Cloud

四、通用验证方法（所有工作流通用）

1. 代码修改：运行 lint/type check，审查 diff

2. 功能修复：复现步骤验证，回归测试

3. 文档更新：校验链接，预览渲染效果

4. 重构任务：对比前后行为，保证无破坏性变更

五、总结

Codex 官方工作流的核心是标准化任务传递与结果校验，通过固定流程降低沟通成本、提升输出稳定性。无论个人快速开发还是团队协同，均可直接套用上述 9 套工作流，结合 IDE/CLI/Cloud 各自优势，让 Codex 真正成为可落地、可预期的开发协作伙伴。