Codex 工程化落地指南 01：产品形态与工程化使用模式

一：教程定位

很多开发人员第一次接触 Codex，会把它理解为一个更强的代码补全工具：

写一个用户注册接口。

然后直接让 Codex修改项目。

这种使用方式虽然可能快速生成代码，但很容易出现：

没有先理解现有项目 没有确认功能边界 修改范围过大 重复实现已有能力 没有创建独立分支 没有运行完整测试 测试失败后仍然提交 生成代码无法解释和追踪 多个并行任务互相覆盖

Codex 工程化使用的重点，不是"生成了多少代码"，而是建立一套稳定工作流：

分析 ↓ 计划 ↓ 编码 ↓ 测试 ↓ 审查 ↓ 提交

本篇将介绍 Codex 的主要产品形态，并建立适合真实项目的基础开发模式。

二：教程信息

目标读者：Codex 初学者、开发人员、DevOps 工程师 预计时长：约 1 小时 难度等级：★☆☆ 案例项目：城市随手拍平台

三：学习目标

完成本篇后，你应该能够：

理解 Codex CLI、IDE、桌面应用和云端任务的区别 判断一个任务应该本地执行还是云端委派 理解本地任务对当前仓库和开发环境的依赖 理解云端任务的隔离运行方式 建立"分析—计划—编码—测试—提交"工作流 避免让 Codex 在没有边界的情况下直接修改项目 完成一次小型功能的完整开发闭环 检查 Codex 的代码变更和测试证据

第一部分：Codex 是什么

四：Codex 不只是代码生成器

Codex 是面向软件开发工作的智能编码 Agent。

它可以在获得授权的环境中：

读取项目文件 理解代码结构 搜索调用关系 修改代码 新增文件 执行终端命令 运行单元测试 运行 Lint 和类型检查 检查 Git Diff 分析报错 审查代码 准备 Commit 或 Pull Request

Codex 可以在本地工具中与你配合，也可以接收任务后在云端环境中独立执行。官方将其定位为帮助开发人员编写、审查和交付代码的编码 Agent；CLI 和 IDE 可以在仓库中读取文件、修改代码、运行命令和执行测试。([OpenAI Help Center][1])

因此，Codex 更接近：

可以操作开发环境的虚拟工程师

而不是：

只根据一段描述输出代码片段的聊天机器人

五：Codex 的能力边界

Codex 很适合：

理解陌生项目 实现范围明确的小功能 修复可复现的 Bug 补充单元测试 重构局部代码 更新依赖 生成迁移脚本 检查 Pull Request 分析错误日志 更新技术文档

Codex 不应该在没有人工控制的情况下直接承担：

未经评审的生产数据库变更 使用生产管理员凭证 直接修改 main 分支 执行不可逆数据删除 跳过测试强行发布 自行决定重大架构迁移 删除无法理解的历史代码

Codex 可以执行复杂任务，但最终代码仍需要开发人员审查和验证。OpenAI 官方也建议用户检查 Agent 生成的代码、终端日志和测试结果，再决定是否合并。([OpenAI][2])

第二部分：Codex 的主要产品形态

六：产品形态总览

目前可以把 Codex 的常用形态分为：

这些形态不是相互替代关系，而是面向不同开发场景。

七：Codex CLI

Codex CLI 运行在终端中。

典型工作方式：

cd city-snapshot-platform codex

进入项目后，可以让 Codex：

阅读仓库 搜索代码 编辑文件 执行 npm、pnpm、mvn、pytest、go test 等命令 检查 Git 状态 生成和审查修改

Codex CLI 是开源命令行工具，可以在本地读取、修改和运行代码。当前官方安装方式之一是：

npm install -g @openai/codex

([OpenAI Help Center][3])

CLI 的优势

与真实构建环境接近 可以直接运行项目命令 方便查看终端输出 适合 Linux、WSL2 和服务器开发 适合后端与基础设施项目 容易接入脚本和 CI/CD

CLI 的不足

不如 IDE 直观 需要熟悉终端 多个任务同时运行时管理成本较高 查看复杂 Diff 不如图形界面方便

推荐使用场景

后端接口开发 数据库迁移 Docker 构建 测试和构建失败修复 批量代码修改 项目结构分析 自动化脚本

八：Codex IDE 扩展

Codex IDE 扩展可以在 VS Code、Cursor、Windsurf 等兼容编辑器中使用。它可以结合当前打开的文件、选择的代码和编辑器上下文完成任务，也能够查看本地修改，并衔接云端任务。([OpenAI Help Center][1])

IDE 的优势

可以边看代码边提问 可以选择具体代码作为上下文 修改前后差异更直观 适合局部功能开发 适合前端和组件开发 人工调整更加方便

IDE 的不足

大型终端任务不如 CLI 直接 多个并行任务仍可能争用同一工作区 开发人员容易只关注当前文件，忽略全局影响

推荐使用场景

修改一个 React/Vue 组件 调整接口参数 修复 TypeScript 类型错误 补充局部测试 解释当前文件 进行小范围重构

九：桌面应用中的 Codex

截至 2026 年 7 月，Codex 已包含在新的 ChatGPT 桌面应用中，支持 macOS 和 Windows。原独立 Codex 应用更新后会转为包含 Chat、Work 和 Codex 的新桌面应用。([OpenAI Help Center][4])

桌面应用适合把 Codex 作为多个开发 Agent 的管理中心。

它支持：

按项目管理任务 同时运行多个 Agent 查看代码 Diff 查看终端和测试输出 使用 Git Worktree 隔离任务 在编辑器中继续修改 管理 Skills 和自动化任务

桌面应用内置 Worktree 支持，可以让多个 Agent 在同一仓库的隔离副本中并行工作，降低修改互相覆盖的风险。([OpenAI][5])

桌面应用的优势

图形界面直观 适合多任务管理 适合长时间任务 Worktree 隔离方便 查看 Diff 和任务历史清晰

桌面应用的不足

复杂命令仍需要理解终端结果 多个 Agent 并行会增加合并成本 没有良好任务拆分时容易产生重复代码

推荐使用场景

前端、后端、数据库并行开发 同时处理多个 Bug 为不同方案建立独立任务 运行较长的重构任务 管理多个项目

十：Codex Cloud

Codex Cloud 适合把任务委派给云端 Agent。

云端任务会在独立沙箱中运行，并加载指定仓库和配置好的开发环境。Agent 可以读取和修改代码、运行测试、Lint 和类型检查；任务完成后，开发人员可以审查变更、继续修改、创建 Pull Request，或者将结果拉回本地。([OpenAI][2])

典型流程：

选择仓库和分支 ↓ 提交任务说明 ↓ 云端创建隔离环境 ↓ Agent 修改代码并执行测试 ↓ 输出 Diff 和执行证据 ↓ 开发人员审查 ↓ 创建 PR 或拉回本地

云端任务的优势

不占用本地终端 可以并行运行多个任务 每个任务环境相互隔离 适合等待时间较长的任务 方便生成 Pull Request 不会直接扰乱本地工作区

云端任务的不足

需要正确配置云端开发环境 依赖、环境变量和服务可能与本地不同 访问内网数据库和内部服务需要额外配置 任务范围不明确时可能产生较大修改 最终仍需人工审查

推荐使用场景

修复独立 Bug 补充大量测试 更新一批重复代码 依赖升级 文档更新 代码审查 明确边界的重构

第三部分：本地任务与云端任务

十一：什么是本地任务

本地任务是指 Codex 直接在你的电脑、WSL2、远程开发机或 IDE 工作区中执行。

它使用的是当前真实环境：

本地源码 本地 Git 分支 本地安装的依赖 本地数据库或 Docker 本地环境变量 本地网络 本地测试命令

例如：

请分析当前项目为什么启动失败，并运行实际启动命令验证。

这种任务需要访问当前电脑的：

.env Docker 容器 本地数据库 企业内网服务 尚未提交的代码

因此更适合本地执行。

十二：什么是云端任务

云端任务运行在独立环境中，不直接使用你的当前本地工作区。

它更适合：

代码已经推送到仓库 任务不依赖本地未提交文件 测试环境可以通过脚本重建 任务边界清晰 可以独立产生一个 PR

例如：

在当前仓库中为用户 Service 补充单元测试， 要求覆盖手机号重复、密码为空和注册成功场景。 不要修改生产代码，除非测试暴露真实缺陷。

十三：本地与云端选择规则

优先使用本地任务

当任务涉及：

尚未提交的代码 本地 Docker 服务 内网数据库 本地设计稿 需要频繁人工调试 需要立即查看浏览器效果 当前机器独有的工具链

优先使用云端任务

当任务满足：

代码已经推送 任务可以独立完成 开发环境可以自动安装 测试可以在沙箱中执行 希望并行处理 希望直接生成 PR

推荐判断方式

是否依赖本地未提交内容？ 是 → 本地

是否依赖本地服务或内网资源？ 是 → 本地或远程开发机

是否能通过仓库脚本重建环境？ 是 → 可以云端

是否适合单独形成一个 PR？ 是 → 优先云端

是否需要频繁人工视觉调整？ 是 → IDE 或桌面应用

十四：常见错误选择

错误一：把依赖本地数据库的任务交给云端

结果：

云端没有数据库 迁移无法运行 集成测试失败 Agent 只能猜测

错误二：在本地同时启动多个任务修改同一分支

结果：

文件互相覆盖 Git Diff 混在一起 测试结果无法归属 Commit 难以拆分

解决：

使用独立分支 使用 Git Worktree 或把独立任务委派到云端

错误三：云端任务没有配置安装脚本

结果：

依赖不存在 测试无法启动 构建环境与项目要求不一致

错误四：认为云端完成就可以直接合并

云端完成表示：

Agent 已完成其认为正确的修改

不表示：

代码一定满足业务要求 代码一定没有安全问题 代码一定适合生产

第四部分：标准工程化工作流

十五："分析—计划—编码—测试—提交"模型

推荐把所有 Codex 开发任务拆成五个核心阶段：

分析 ↓ 计划 ↓ 编码 ↓ 测试 ↓ 提交

复杂项目可以增加：

审查 发布 验证

形成：

分析 ↓ 计划 ↓ 编码 ↓ 测试 ↓ 审查 ↓ 提交 ↓ 发布

十六：阶段一：分析

分析阶段只理解问题，不修改文件。

需要确认：

用户需求是什么 当前功能是否已经存在 相关代码在哪些目录 涉及哪些接口 涉及哪些数据库表 有哪些测试 有哪些公共模块 可能影响哪些功能 当前工作区是否干净

推荐提示词：

请先分析当前任务，不要修改任何文件。

任务：为城市随手拍平台增加手机号格式校验。

请输出：

1. 当前手机号处理逻辑所在位置。
2. 已有注册接口和验证逻辑。
3. 可能需要修改的文件。
4. 已有测试情况。
5. 对其他功能的影响。
6. 风险和不确定项。
7. 建议实施方案。

所有结论必须基于实际代码。 无法确认的内容标记为"待确认"。

分析阶段的验收

没有修改文件 没有安装依赖 没有创建无关文件 能够指出实际代码位置 能够说明影响范围 没有凭空假设项目结构

十七：阶段二：计划

计划阶段把需求转化为可执行步骤。

一个合格计划应包含：

修改文件 新增文件 数据库变化 接口变化 测试范围 执行顺序 风险 验收标准

推荐提示词：

基于刚才的分析，输出实施计划，暂时不要修改代码。

计划必须包含：

1. 修改范围。
2. 每个文件的修改目的。
3. 实施顺序。
4. 测试方案。
5. 回归范围。
6. 不会修改的模块。
7. 完成验收标准。

本任务只做手机号格式校验， 不增加短信验证码， 不修改登录流程。

计划阶段需要阻止的问题

顺便重构整个用户模块 顺便更换验证框架 顺便修改登录接口 顺便升级全部依赖

计划必须与当前任务范围保持一致。

十八：阶段三：编码

编码阶段按照计划逐步修改。

推荐原则：

一次完成一个可验证的小步骤 优先复用项目现有模式 不擅自更换技术方案 不修改无关代码 不删除无法理解的逻辑 新增行为必须补充测试

编码提示词：

按照已确认的计划开始实现。

要求：

1. 只修改计划中列出的文件。
2. 使用项目现有验证方式。
3. 不引入新的生产依赖。
4. 不修改登录和密码逻辑。
5. 补充手机号合法和非法场景测试。
6. 每完成一个阶段，汇报修改结果。
7. 暂时不要 Commit。

十九：阶段四：测试

Codex 完成编码后，不能只做静态说明。

必须运行项目真实命令，例如：

npm run lint npm run typecheck npm test npm run build

或者：

mvn test mvn package

或者：

pytest ruff check . mypy .

推荐提示词：

实现完成后执行验证。

请先检查 package.json 和项目文档， 确认项目真实可用的命令。

依次运行：

1. 与当前功能相关的单元测试。
2. 完整单元测试。
3. Lint。
4. 类型检查。
5. 构建。

如有失败：

1. 分析失败原因。
2. 只修复与本次修改有关的问题。
3. 重新执行失败命令。
4. 不得隐藏、跳过或删除失败测试。

最后输出每条命令、退出码和结果。

不允许的测试报告

测试应该可以通过。

由于时间原因未运行测试。

从代码上看没有问题。

合格的测试报告

npm test -- user-register.test.ts 退出码：0 结果：8 个测试通过

npm run typecheck 退出码：0

npm run build 退出码：0

二十：阶段五：审查和提交

提交前检查：

git status git diff --stat git diff

需要确认：

当前分支正确 只有当前任务相关修改 没有 .env 和 Secret 没有调试日志 没有无关格式化 没有大范围锁文件变化 测试已经通过

用户当前的工程规则是：

新功能分支： fea-{功能简介拼音}

允许： 自动 Commit 自动 Push

禁止： 直接修改 main Force Push 测试失败后提交 自动合并 main

推荐提示词：

请执行提交前检查。

要求：

1. 输出当前分支。
2. 执行 git status。
3. 执行 git diff --stat。
4. 检查是否有无关修改。
5. 检查是否包含 Secret。
6. 汇总测试结果。

确认全部通过后：

1. 只添加当前功能相关文件。
2. 使用 Conventional Commit。
3. 自动 Commit。
4. 自动 Push 当前功能分支。
5. 禁止 Force Push。
6. 禁止合并 main。

最后输出：

• 分支名称
• Commit message
• Commit ID
• Push 结果
• 测试结果

第五部分：不同产品形态的推荐工作流

二十一：CLI 工作流

进入项目目录 ↓ 检查 Git 状态 ↓ 启动 Codex ↓ 分析仓库 ↓ 输出计划 ↓ 创建功能分支 ↓ 修改代码 ↓ 执行测试 ↓ 检查 Diff ↓ Commit 和 Push

适合：

后端开发 脚本任务 数据库迁移 工程配置 Docker 项目

二十二：IDE 工作流

打开项目 ↓ 选择相关文件或代码 ↓ 让 Codex解释调用关系 ↓ 确认修改范围 ↓ 进行局部修改 ↓ 在 IDE 查看 Diff ↓ 运行测试 ↓ 提交

适合：

前端组件 类型修复 局部重构 接口调整 代码解释

二十三：桌面应用工作流

添加项目 ↓ 为每个功能建立独立线程 ↓ 为并行任务创建 Worktree ↓ 让多个 Agent 独立执行 ↓ 分别审查 Diff 和测试 ↓ 选择保留的方案 ↓ 合并到目标功能分支

适合：

并行开发 多方案探索 多个 Bug 修复 长任务管理

二十四：云端工作流

推送基础分支 ↓ 创建边界明确的云端任务 ↓ 配置安装和测试环境 ↓ Agent 在隔离环境执行 ↓ 查看执行日志和测试 ↓ 审查 Diff ↓ 要求继续修改或创建 PR ↓ 人工合并

适合：

独立测试补全 文档更新 依赖升级 可隔离 Bug 批量但规则明确的修改

第六部分：一小时实操

二十五：实操任务

本次使用一个低风险任务：

为城市随手拍平台后端添加健康检查接口。

接口要求：

GET /health

返回：

{ "status": "UP", "service": "city-snapshot-api" }

要求：

不访问数据库 不需要登录 不修改业务接口 补充接口测试 测试通过后提交功能分支

二十六：时间安排

0～10 分钟：选择使用形态

推荐：

后端项目 → Codex CLI 前端局部调整 → IDE 并行多个任务 → 桌面应用 独立测试补全 → Cloud

本次使用：

Codex CLI 或 IDE 本地任务

10～20 分钟：分析

请先分析当前后端项目，不修改文件。

目标：增加 GET /health 健康检查接口。

请确认：

1. 后端技术栈。
2. 路由或 Controller 目录。
3. 统一响应格式。
4. 测试框架。
5. 需要修改的文件。
6. 是否已有类似接口。

20～30 分钟：计划

请输出健康检查接口的实施计划，不修改代码。

约束：

1. GET /health。
2. 不要求登录。
3. 不访问数据库。
4. 不新增生产依赖。
5. 返回 status 和 service。
6. 补充自动化测试。
7. 不修改其他业务接口。

30～45 分钟：编码

按照计划实现健康检查接口。

要求：

1. 使用项目现有路由和响应方式。
2. 只修改必要文件。
3. 添加自动化测试。
4. 暂时不要 Commit。

45～55 分钟：测试和审查

请执行：

1. 健康检查接口相关测试。
2. 完整测试。
3. Lint。
4. 类型检查。
5. 构建。

然后执行：

git status git diff --stat git diff

输出实际命令和结果。

55～60 分钟：提交

功能分支：

fea-jiankangjiancha

提交要求：

Commit： feat: add application health check endpoint

提交提示词：

确认测试全部通过且没有无关修改后：

1. 当前分支必须为 fea-jiankangjiancha。
2. 只添加当前功能相关文件。
3. Commit message： feat: add application health check endpoint
4. 自动 Push 当前分支。
5. 禁止 Force Push。
6. 不要合并 main。

输出 Commit ID 和 Push 结果。

第七部分：任务完成报告

二十七：标准完成报告模板

Codex 完成任务后应输出：

完成内容

• 新增 GET /health。
• 返回应用健康状态。
• 添加接口测试。

修改文件

• src/...
• tests/...

测试结果

• npm test：通过
• npm run typecheck：通过
• npm run build：通过

Git

• 分支：fea-jiankangjiancha
• Commit：abc1234
• Push：成功

风险

• 当前接口只检查应用进程，不检查数据库和 Redis。

二十八：人工验收清单

开发人员最后检查：

接口地址是否正确 是否无须登录 是否意外访问数据库 返回结构是否符合要求 测试是否真实运行 是否修改无关代码 是否在正确功能分支 是否已经 Push 是否没有提交 Secret

第八部分：常见错误

二十九：上来就让 Codex修改代码

错误：

给项目加上健康检查。

更好：

先分析现有路由、响应格式和测试框架， 输出计划后再实现健康检查。

三十：一个任务包含多个目标

错误：

增加健康检查、重构用户模块、升级依赖并修复所有警告。

应该拆成：

任务 1：健康检查 任务 2：用户模块重构 任务 3：依赖升级 任务 4：警告清理

三十一：没有说明禁止事项

如果没有边界，Codex 可能：

增加新框架 修改公共返回格式 格式化大量文件 升级锁文件 重写已有模块

任务中应明确：

不新增依赖 不修改公共接口 不重构无关模块 不修改生产配置

三十二：只看结果，不看过程

不能只看：

任务完成。

应查看：

修改文件 Git Diff 测试命令 测试输出 退出码 Commit 远程分支

三十三：把所有任务都交给云端

以下任务通常更适合本地：

依赖本地数据库 依赖本地 Docker 依赖当前未提交代码 需要频繁视觉调整 需要企业内网服务

三十四：在同一工作区并行修改

多个 Codex 任务同时修改同一目录时，容易产生：

代码覆盖 冲突 测试混乱 提交污染

应使用：

不同分支 Git Worktree 桌面应用隔离工作区 云端独立任务

第九部分：企业使用原则

三十五：Codex 不应绕过现有工程流程

Codex 应遵守：

需求评审 分支策略 代码规范 测试要求 Pull Request 代码审查 CI/CD 生产审批

不应因为使用了 Agent，就取消：

测试 审查 权限控制 变更记录 回滚方案

三十六：先把项目变得适合 Agent

一个适合 Codex 的项目通常具备：

清晰 README 明确启动命令 可靠测试 统一目录结构 AGENTS.md 独立开发分支 可重复安装环境 稳定构建命令

云端和本地 Agent 都更依赖良好的环境配置、测试和项目文档。官方也建议使用AGENTS.md告知 Codex 如何导航仓库、执行测试和遵守项目规范。([OpenAI][2])

三十七：工程化使用核心原则

简单任务可以直接执行 复杂任务必须先分析 大范围修改必须先计划 所有功能必须独立分支 所有修改必须运行测试 所有提交必须可审查 所有失败必须如实说明 所有生产操作必须有人类审批

第十部分：练习与验收

三十八：练习一：选择正确产品形态

为下列任务选择 Codex 形态：

任务 A

修复当前本地 Docker 环境中的数据库连接错误。

推荐：

CLI 本地任务

任务 B

修改当前 Vue 页面按钮布局。

推荐：

IDE 或桌面应用

任务 C

为 30 个工具函数补充单元测试。

推荐：

Codex Cloud

任务 D

前端、后端和数据库三个模块并行开发。

推荐：

桌面应用 + Worktree

三十九：练习二：完成健康检查接口

验收：

已完成分析 已输出计划 已创建 fea-jiankangjiancha 已实现 GET /health 已添加测试 测试通过 已检查 Diff 已自动 Commit 已自动 Push 未修改 main

四十：本篇验收标准

完成本篇后，应达到：

已理解 Codex 是编码 Agent，而不只是代码补全工具 已理解 CLI、IDE、桌面应用和 Cloud 的区别 已能区分本地任务和云端任务 已知道什么时候使用 Worktree 已掌握分析—计划—编码—测试—提交工作流 已能要求 Codex先分析再修改 已能检查测试证据和 Git Diff 已完成一个小型功能闭环 已理解 Agent 结果仍然需要人工审查

四十一：本篇总结

需要重点记住：

CLI 适合终端和工程任务 IDE 适合局部编码和交互修改 桌面应用适合多 Agent、Worktree 和多项目管理 Cloud 适合隔离、并行和可独立审查的任务 依赖本地环境的任务优先本地执行 能独立形成 PR 的任务适合云端 Codex 开发必须先分析、再计划、后编码 代码完成不等于任务完成 测试、Diff、Commit 和审查都是交付的一部分 不要让多个 Agent 在同一分支和工作区无隔离修改 不要让 Codex 绕过团队原有工程规范