# Codex 标准工作流

> 从需求到交付的六步工作流 — 理解→计划→实现→测试→审查→提交,让 Codex 改得准、改得稳。

URL: https://docs.passion8.cc/docs/codex/workflow
Language: zh-CN
Publisher: Passion8

别把需求一句话丢给 Codex 就等结果。一个好的协作流程是:**理解 → 计划 → 小步改 → 测试 → 审查 → 提交**。每步都有明确的产出,出问题才能精确定位。

## 标准六步法

| 步骤 | 目的 |
| --- | --- |
| 1. 需求拆解 | 把模糊需求变成 Codex 能执行的具体描述,划清边界 |
| 2. 制定计划 | 先列改动清单,确认后再动手,避免跑偏 |
| 3. 小步实现 | 一次只改一个功能点,方便回滚、降低出错面 |
| 4. 测试 | 用结果证明改动有效,而不是信 Codex 说"完成了" |
| 5. 代码审查 | 看 diff,检查改得对不对、有没有引入风险 |
| 6. 提交与复盘 | 提交代码,沉淀经验,AI 执行、人最终拍板 |

---









### 需求拆解

**目标:把"优化首页"这类模糊说法变成 Codex 能执行的精确描述。**

好的需求描述应包含:
- **背景**:项目是什么、为什么要做
- **具体问题**:改到什么程度、哪些不在范围
- **相关文件**:可能涉及哪些文件(先列出来,不要改)
- **禁止区域**:哪些功能绝对不能动
- **完成标准**:什么结果算做完
- **风险**:有哪些潜在副作用

```text
请先做需求拆解,不要立刻改代码。

需求:【在这里描述需求】

请分析:
1. 背景(项目是什么 / 为什么做 / 需求类型)
2. 具体问题(做到什么程度 / 哪些不在范围)
3. 可能相关的文件(只列出,暂不修改)
4. 不能动的功能
5. 完成标准
6. 需要哪些测试
7. 潜在风险

最后给一个简短的执行建议。
```








### 制定计划

**目标:在写代码之前对齐方向,错了在这步纠正成本最低。**

需求拆解完成后,让 Codex 出一份改动计划再动手:

```text
先不要写代码,也不要改任何文件。
请根据需求和项目结构制定修改计划,等我确认后再执行。
```




复杂任务可用 `/plan` 命令进入计划模式;需要更强推理时,用 `/model` 临时调高推理强度。











### 小步实现

**目标:一次只落地一个功能点,随时能回滚。**

明确限制,防止 Codex 趁机重构无关代码:

- 本次只改当前功能点对应的文件
- 不顺手重构、不改目录结构、不动全局配置
- 发现可优化的地方记录为建议,不直接改
- 遇到不确定的情况,停下来问

```text
请开始小步实现,当前只执行第【N】步:【功能点名称】。

要求:
- 只改这个功能点涉及的文件
- 不顺手重构其他代码
- 不新增不必要的依赖
- 不删除现有功能

完成后停下来,输出:
- 改了哪些文件 / 每处改动的原因
- 有没有计划外的改动
- 有没有风险
- 下一步建议
```








### 测试

**目标:用实际结果证明改动正确,不只靠 Codex 的自述。**

按从快到慢的顺序逐步推进:

| 检查项 | 命令 / 操作 |
| --- | --- |
| 单元测试 | `npm test` |
| 类型检查 | `tsc --noEmit` |
| Lint | `npm run lint`(区分新增问题和历史遗留) |
| 构建 | `npm run build`(能打包 ≠ 能上线) |
| 手动验证 | UI 交互、表单、登录、支付等逐一点 |
| 浏览器检查 | Console 报错、Network 请求、移动端适配 |
| 回归测试 | 确认旧功能没有被改坏(最容易被跳过) |




回归测试是最容易被忽略的一步,也是上线后最常出问题的地方。




手动测试前可让 Codex 生成一张"操作 → 预期结果"表格,照表逐项验证。








### 代码审查

**目标:测试通过 ≠ 可交付,要看 diff 确认改得对。**

分两轮:

**第一轮:让 Codex 自审**,输出一张表格,说明是否改到计划外的文件、是否新增依赖、是否删除旧逻辑、有没有硬编码或风险。

**第二轮:人工审 diff**,重点盯四类高风险:

- **边界条件**:空数据、接口失败、未登录、权限不足、重复点击
- **安全问题**:密钥暴露、权限判断缺失、输入未校验、接口鉴权
- **误删内容**:重点看 diff 的删除部分,旧组件 / fallback / 配置可能仍被依赖
- **业务逻辑**:能跑 ≠ 逻辑对(跳错页、价格算错、越权等)

```text
请对本次修改做代码审查,不要继续写代码。

审查内容:
1. 自审:是否改到计划外文件 / 是否有无关重构 / 是否新增依赖 / 是否有硬编码
2. 修改范围是否符合计划
3. 边界条件覆盖
4. 安全问题
5. 删除内容:删了什么 / 为什么 / 是否还有地方依赖它
6. 业务逻辑是否正确

结论选一:可以继续 / 需要小修 / 需要回退部分 / 需要重新计划。
只审查,不改代码。
```




涉及登录、支付、权限、数据库的改动,建议用第二个模型交叉复审 — 一个写、一个挑错。











### 提交与复盘

**目标:正式落库,把经验写进项目,让下次更顺。**

- 测试 + 审查全部通过后,执行 `git commit / push`,必要时开 PR
- 把踩过的坑、有效的提示词、项目约定更新到 `AGENTS.md`,下次 Codex 自动读取
- AI 负责执行,**人负责最终拍板**




`AGENTS.md` 是最好的"经验沉淀"载体 — 把本次发现的项目约定写进去,下次省去重新解释的成本。见 [高阶玩法 → AGENTS.md](https://docs.passion8.cc/docs/codex/tips)。