Codex Plan 模式完整教程：复杂任务如何先规划再实现

Plan 模式的价值不是多生成一段文字，而是让 Codex在修改代码前完成：

收集上下文；
明确需求歧义；
识别模块边界；
评估风险；
设计可验证的里程碑。

官方建议复杂、模糊或难以描述的任务先规划。在支持的客户端中，可以输入：

/plan

或使用界面快捷方式进入 Plan。

1. 哪些任务应该使用 Plan

建议使用：

需要修改多个模块；
涉及数据库迁移；
涉及认证、支付、权限或安全；
需要保持公共 API 向后兼容；
需要升级框架或核心依赖；
需要重构大型模块；
需求存在多种合理实现；
预计要分多个提交完成。

不一定需要：

修改一个文案；
调整单个 CSS 属性；
修复一个已明确定位的小错误；
增加一个简单测试用例。

2. Plan 提示词的基本结构

/plan

目标：
把当前本地文件上传改成支持对象存储的实现。

要求：
- 保持现有上传 API 兼容；
- 支持灰度切换；
- 旧文件仍可访问；
- 提供回滚方案；
- 不直接修改代码。

计划需要包含：
1. 当前实现和调用链；
2. 目标架构；
3. 修改文件；
4. 配置和数据迁移；
5. 测试策略；
6. 上线与回滚；
7. 风险和待确认问题。

最后明确写“先不要修改代码”，可以减少代理过早进入实现。

3. 一份合格计划应包含什么

3.1 当前状态

计划必须基于真实代码，而不是通用猜测：

- 上传入口：src/api/upload.ts
- 存储接口：src/storage/StorageProvider.ts
- 当前实现：LocalStorageProvider
- 下载路径：src/routes/files.ts

3.2 目标状态

描述最终组件关系和数据流：

Controller -> StorageService -> StorageProvider
                              -> LocalProvider
                              -> S3Provider

3.3 影响范围

列出：

新增文件；
修改文件；
配置项；
数据库变化；
外部服务；
部署变化；
监控变化。

3.4 里程碑

每个里程碑都应：

可以独立审查；
可以独立测试；
尽量可以独立提交；
有明确完成标准。

3.5 验证和回滚

计划不只有“怎么做”，还应包含“怎么证明”和“怎么撤回”。

4. 如何让 Codex先调查再计划

对于陌生代码库：

/plan

先调查当前支付流程，不修改代码。
调查内容：
- 创建订单入口；
- 支付回调；
- 幂等处理；
- 订单状态机；
- 退款流程；
- 相关测试和监控。

基于真实文件和调用关系，设计增加第二支付渠道的计划。
所有结论引用文件和函数名。

这样可以防止计划变成脱离项目的通用架构文章。

5. 如何评审 Codex 的计划

不要看到计划就直接执行。重点检查：

5.1 是否遗漏关键路径

例如支付功能是否考虑：

重复回调；
超时；
退款；
对账；
签名验证；
旧订单兼容。

5.2 是否修改范围过大

如果需求只是增加一个渠道，计划却要求重写整个订单系统，应要求缩小范围：

保留现有 PaymentService 公共接口，把计划改为增量接入，不做无关重构。

5.3 是否有无法验证的表述

例如：

优化性能，确保系统更稳定。

应改成：

定义要测量的接口、数据规模、延迟指标和负载脚本。

5.4 是否能分阶段回滚

大型一次性改动风险高。要求：

每个里程碑说明回滚方式，避免数据库迁移和代码发布形成不可逆绑定。

6. 与 Codex 协商计划

第一次计划通常不是最终计划。可以连续修订：

把计划调整为 3 个可独立提交的里程碑。

为每个里程碑列出精确文件和测试命令。

增加旧配置兼容和灰度开关。

删除与本需求无关的目录重构。

补充失败重试、幂等和监控指标。

这一步相当于工程设计评审。

7. 从 Plan 进入实现

计划确认后，不要简单说“开始”。更好的方式是按里程碑执行：

实现计划的 Milestone 1：抽象 StorageProvider 接口并保持 LocalProvider 行为不变。
只完成这一阶段。
完成后运行相关测试并汇报 Diff，不进入 Milestone 2。

审查后再继续：

Milestone 1 已确认。实现 Milestone 2：增加 S3Provider 和配置解析。
保持默认仍使用 LocalProvider。

这样可以控制上下文、Diff 和回滚成本。

8. 使用 PLANS.md 固化长期任务

对于长周期项目，可以建立 PLANS.md 或团队自己的执行计划模板。

示例：

# Execution Plan

## Goal

## Current state

## Constraints

## Milestones

### Milestone 1
- Files:
- Changes:
- Verification:
- Rollback:

### Milestone 2

## Risks

## Open questions

## Final acceptance

然后在 AGENTS.md 中要求复杂任务遵循它：

## Planning
- For changes spanning more than one subsystem, create or update `PLANS.md` first.
- Each milestone must include verification and rollback steps.
- Do not start implementation until the plan is approved.

9. 数据库迁移计划示例

/plan

目标：
把 users.name 拆分为 first_name 和 last_name。

约束：
- 线上无停机；
- 旧版本应用继续可用 2 个发布周期；
- 数据可回滚；
- 不能一次性删除 name。

计划必须包含：
- 双写阶段；
- 历史数据回填；
- 读取切换；
- 数据一致性检查；
- 旧字段停止写入；
- 最终删除条件；
- 每阶段监控和回滚。

一个合理方向通常是 Expand → Migrate → Contract，而不是直接重命名字段。

10. 大型重构计划示例

/plan

目标：
拆分单体 notification.ts，使邮件、短信、Push 可以独立实现和测试。

限制：
- 现有 sendNotification 调用不变；
- 不改变用户可见行为；
- 不同时更换第三方供应商；
- 每个阶段测试必须通过。

输出：
- 当前依赖图；
- 目标接口；
- 分阶段迁移调用方；
- 兼容适配层；
- 测试和回滚。