面对一个小修小补，直接让 Codex 动手通常最省事。但当任务变成跨模块重构、数据迁移、模糊的产品需求，或者“不能改坏现有行为”的高风险调整时，过早写下第一行代码反而容易把后续工作带进错误方向。

计划模式的价值就在这里。它不是要求 Codex 把回答写得更长，而是暂时改变协作顺序：先理解环境和目标，找出仍然影响方案的未知项，再把实现路径、风险和验证方式收束成一份能够直接执行的计划。

计划模式改变的不是答案长度，而是“探索、决策、执行”的先后顺序。

什么是 Codex 计划模式

按照 OpenAI 当前的 Codex Developer Commands 文档，在支持该命令的 Codex 界面中输入 /plan，可以把当前对话切换到 Plan Mode，也可以直接附带任务：

/plan Propose a migration plan for this service

/plan 后面可以继续粘贴文字或附加图片；如果当前任务已经在运行，这个命令会暂时不可用。进入计划模式之后，Codex 应当围绕“怎样把任务想清楚”工作，而不是立即开始修改文件。

这与普通的“先列三步再开工”并不完全相同。OpenAI 开源仓库中的 Plan Mode 协作模板把它定义为一种独立协作模式：可以阅读、搜索、做静态分析和运行不改写仓库的检查，但不应编辑文件、应用 patch，或执行本质上已经在落实方案的副作用操作。

简单说，计划模式负责把路看清楚；退出计划模式之后，执行阶段才真正沿着这条路向前走。

Plan Mode 不是待办清单

计划模式最常见的误解，是把它等同于 checklist。二者都会出现步骤，却处在不同层级：

形式解决的问题是否改变协作方式典型用途
简短待办或 update_plan任务现在进行到哪里否展示已完成、进行中和未开始步骤
Plan Mode这项工作究竟应该怎样做是探索环境、澄清取舍、形成决策完整的方案
ExecPlan长任务如何跨时间持续执行作为仓库内的活文档记录进度、发现、决策、验证与恢复方式

有 checklist 不代表进入了 Plan Mode；进入 Plan Mode 也不等于已经开始实施。

一个任务可以在执行阶段使用待办清单追踪进度，也可以先在 Plan Mode 中把方案想清楚，再把确定的步骤转换成执行清单。真正需要区分的是：前者记录过程，后者改变做决定的方式。

一份可靠计划怎样长出来

当前 Plan Mode 模板把规划过程分为三个阶段：先扎进真实环境，接着澄清无法自行发现的意图，最后补齐实现决策。

flowchart LR
  Task["复杂或模糊的任务"] --> Explore["探索环境\n代码、配置、测试、文档"]
  Explore --> Intent{"仍有产品意图或取舍\n无法从环境确认？"}
  Intent -- "有" --> Ask["集中提问\n锁定目标与约束"]
  Intent -- "没有" --> Design["形成实现方案"]
  Ask --> Design
  Design --> Complete{"方案是否已决策完整？"}
  Complete -- "否" --> Explore
  Complete -- "是" --> Plan["交付可执行计划"]
  Plan --> Execute["退出计划模式后实施"]

先探索环境

仓库里能够查到的问题，应当先由 Codex 自己确认。计划模式不是把搜索工作转交给用户，而是允许 Codex 在不修改项目的前提下，阅读入口文件、调用链、测试、配置、数据结构和已有实现习惯。

一次有价值的探索通常会回答：

  • 功能真正从哪里进入，数据怎样流动；
  • 仓库里是否已有可以复用的组件或工具；
  • 哪些公开接口和旧行为必须保持；
  • 当前测试覆盖了什么，又遗漏了什么；
  • 哪些依赖、部署设置或迁移脚本会受影响。

能从代码、配置和文档中查到的事实，先探索；只有无法从环境推出的偏好与取舍，才交给用户决定。

再澄清意图

完成第一轮探索之后，剩下的问题往往不再是“文件在哪里”，而是“产品希望怎样”。例如：

  • 兼容旧数据与简化新结构发生冲突时，哪一边优先；
  • 新功能面向谁，成功标准是什么；
  • 是否允许改公开 API 或引入依赖；
  • 某个失败场景应该重试、回滚，还是直接提示用户；
  • 上线是否需要灰度、迁移窗口或人工确认。

这些问题如果会实质改变架构、交互或验收结果，就值得在计划阶段问清楚。反之，如果无论怎样回答都不会改变方案，提问只会增加来回沟通。

最后形成无需临场补决策的方案

计划的完成标准不应只是“看起来列得很详细”，而是实施者能够沿着它工作，不必在关键位置重新猜测设计意图。通常需要覆盖：

  • 目标和可观察的完成结果；
  • 主要改动范围与数据流；
  • 接口、状态和兼容性变化；
  • 边界情况与失败模式；
  • 测试、视觉检查或部署验证；
  • 风险、回滚方式和明确的非目标。

文件名和函数名只有在能消除歧义时才有价值。把整个目录树逐项抄进计划，并不会自然变成更好的方案；真正重要的是把会影响实现的选择提前说清楚。

什么时候值得进入计划模式

计划模式有成本：它会把一部分时间花在探索和讨论上。因此，并不是每个任务都应该先开一次小型评审会。

通常可以直接执行

  • 单文件中的明确文案修改；
  • 已知位置、已知预期的小型样式修复；
  • 有现成模式可照搬的低风险调整；
  • 失败后容易回退，并且不会影响外部接口的改动。

适合使用 Plan Mode

  • 多文件或跨模块重构；
  • 需求仍然模糊，需要先看现有实现再讨论；
  • 数据、配置、接口或部署方式迁移；
  • 权限、支付、认证、同步等高风险流程；
  • 需要在多个合理方案之间做产品或工程取舍；
  • 验收方式本身还没有被说清楚。

一个实用判断是：如果第一版实现走错方向，返工成本是否明显高于先花时间把边界问清楚？答案为“是”时，计划模式通常值得使用。

怎样写一个更有用的 /plan 请求

不必把所有实现细节都提前替 Codex 决定，但最好提供四类信息：目标、上下文、约束和完成标准。

/plan
目标：把现有认证流程中的 token refresh 集中到统一入口。
上下文：先检查认证模块、请求拦截器和相关测试。
约束：不改变公开 API；保留现有登录与退出体验；不引入新依赖。
完成标准：现有测试通过，并覆盖刷新成功、刷新失败与退出清理。

请先探索仓库中能够确认的事实；
只向我询问无法从现有实现判断、且会改变方案的取舍；
最后给出包含风险、测试和验收方式的可执行计划。

这类提示不会强迫计划采用某种固定格式，却明确了协作顺序。相比“给我一个详细计划”，它更能避免两种极端：要么尚未阅读项目就开始猜测，要么提出一长串本可以自己搜索得到的问题。

推理强度需要单独调高吗

Codex 配置支持 plan_mode_reasoning_effort，可选值为 none、minimal、low、medium、high 和 xhigh。如果没有设置，Plan Mode 使用内置默认值。

plan_mode_reasoning_effort = "high"

这是一项模式级覆盖，而不是“计划质量”旋钮。提高推理强度可能适合高风险迁移或复杂跨模块设计，但无法替代真实的仓库探索、明确的约束和可验证的完成标准。对于简单任务，与其把推理强度拉满，不如直接执行并认真验证。

长任务为什么还需要 ExecPlan

一次 Plan Mode 对话最终会产出方案，但多小时、多阶段工作还会在执行过程中出现新事实：某个依赖的真实行为与文档不同，迁移需要增加过渡状态，或者原本可行的路径在试验后被否定。如果这些变化只留在聊天记录里，任务恢复或交接时就很难重建全貌。

OpenAI Cookbook 的 Using PLANS.md for multi-hour problem solving把 ExecPlan 定义为自包含、面向结果并持续更新的执行文档。它不仅写“准备做什么”，还维护：

  • 当前进度和明确的停止点；
  • 意外发现与对应证据；
  • 已作出的决定及原因；
  • 最终结果、遗留问题与复盘；
  • 可重复执行的命令、验收方式和恢复路径。
普通计划是开工前的方案，ExecPlan 则是会随着施工持续更新的活文档。 
# 将旧计费表迁移到新结构

## Purpose / Big Picture
## Progress
## Surprises & Discoveries
## Decision Log
## Outcomes & Retrospective
## Context and Orientation
## Plan of Work
## Concrete Steps
## Validation and Acceptance
## Idempotence and Recovery

并非所有仓库都需要 PLANS.md。只有当任务会跨越较长时间、需要多次恢复、可能交给其他人继续，或执行中必然产生重要新决策时，这份文档才真正比普通计划更有价值。

常见的计划失效方式

还没探索，就开始写文件清单

计划里出现大量看似具体的路径，却没有证明这些文件与真实调用链有关。这样的“具体”只是把猜测写得更像结论。

把所有未知项都问给用户

“组件在哪里”“测试命令是什么”通常可以从仓库确认。计划模式应减少用户需要重新解释的内容，而不是把探索成本退回去。

只有步骤，没有决策

“修改组件、补测试、运行构建”适用于几乎所有项目，却没有说明状态如何变化、旧行为怎样兼容、失败时发生什么。

计划完成后不再更新

对于短任务，执行中有小偏差很正常；对于 ExecPlan，新的发现和决策必须回写，否则文档很快会变成一张过期地图。

把计划当作执行本身

计划再完整，也没有替代实现、测试和真实验收。Plan Mode 的终点不是“写完一份漂亮方案”，而是让接下来的执行更少依赖运气。

结语

计划模式真正节省的不是打字时间，而是错误方向上的实现时间。它把复杂任务中最昂贵的部分——环境理解、需求边界和关键取舍——移到文件被修改之前处理。

如果只保留一句总结，可以记成：

小任务直接做，复杂任务先探索再决策；长任务则把计划变成一份会随执行持续更新的 ExecPlan。

这也与本站前几篇文章形成了同一套分层：Codex Memories 保存跨任务仍然有用的背景，Agent Skills沉淀重复任务的方法，而 Plan Mode 负责在这一次复杂任务里，把尚未确定的实现路径讨论清楚。路线确定之后，Codex 派生、Git 分支与 worktree则进一步说明怎样把任务路线、提交历史和文件现场分别管理起来。

参考资料