Plan / Goal 模式

13.1 何时应该先 Plan

官方 best practices 明确:简单任务(改文案、修小 bug)可以直接做。但如果任务具备以下特征,就应该先让它计划:

• 涉及多个模块
• 需求还不清楚
• 可能影响现有架构
• 需要排查原因
• 需要分阶段上线

官方原文:If the task is complex, ambiguous, or hard to describe well, ask Codex to plan before it starts coding.

13.2 Plan 模式 vs 直接执行

方式	适用	流程
直接执行	简单、范围明确	给 prompt → 出代码
Plan 模式	复杂、模糊、影响大	收集上下文 → 提问 → 出计划 → 你确认 → 实现

Plan 模式的价值不是让流程变慢,而是先把“怎么做”暴露出来,避免 Codex 一上来就改一大片代码。

13.3 进入 Plan 模式

三种方式:

/plan

或快捷键 Shift+Tab 切换。

或在 prompt 里直接要求:

先不要写代码。请先阅读相关文件,给出你的理解、修改计划、风险点和验证方式。等我确认后再开始实现。

13.4 让 Codex 反向采访你

对于不确定的需求,可以让 Codex 反过来问你:

我现在只有一个粗略想法,请你先问我问题,帮我把需求变成可执行的开发任务。

官方 best practices 推荐:如果只有模糊想法,让 Codex 挑战你的假设,把模糊想法变具体。这对产品功能、重构、复杂 bug 都很有用。

13.5 Plan 模式产出什么

进入 Plan 模式后,Codex 会:

1. 阅读相关代码
2. 复述它对问题的理解
3. 找出可能的风险点
4. 给出修改方案
5. 说明验证方式

然后等你确认后才动手。

13.6 PLANS.md 执行计划模板

对于长时间运行或多步骤的工作,官方推荐配置 Codex 跟随 PLANS.md 或执行计划模板。

一个简单的 PLANS.md 模板:

PLANS.md

## 任务:重构 auth 模块

## 背景
- 当前 auth 模块耦合严重,登录/登出/会话混在一起
- 目标:拆分为 login / logout / session 三个子模块

## 步骤
1. [ ] 阅读现有 src/auth/* 代码,理解依赖关系
2. [ ] 拆分 AuthSession 到 src/auth/session.ts
3. [ ] 拆分登录逻辑到 src/auth/login.ts
4. [ ] 拆分登出逻辑到 src/auth/logout.ts
5. [ ] 更新所有 import
6. [ ] 跑测试,确保不回归
7. [ ] 补充新模块的单元测试

## 风险
- 循环依赖:session 和 login 可能互相引用
- 中间件顺序:auth 中间件依赖 session

## 验证
- pnpm test 全绿
- 手动测试登录/登出/会话过期
- git diff 只涉及 src/auth/

更详细的执行计划指南见官方 execution plans guide。

13.7 reasoning effort 等级选择

Plan 阶段配合合适的推理强度效果更好(来自官方 best practices):

等级	适合
low	快速、范围明确的任务
medium	一般任务(默认)
high	复杂变更、调试
extra high	长时间 agentic、推理密集型任务

Plan 复杂任务时建议 high 或 extra high:

codex --model gpt-5-codex -a on-request "..."
# config.toml 中:
# model_reasoning_effort = "high"

13.8 Goal 模式

部分教程提到 Codex 的 Goal 模式——给一个高层目标,让 Codex 自己分解任务并执行。这本质上是 Plan 模式的延伸:先给目标 → Codex 出计划 → 你确认 → 自动执行后续步骤。

适合“我要达成 X,你帮我想怎么做并执行”的场景。

13.9 实战示例

反面案例(直接做)

帮我修一下登录问题。

正面案例(先 Plan)

目标:修复用户登录后偶尔跳回首页的问题。

上下文:登录逻辑在 src/auth,路由守卫在 src/router,
最近错误日志见 logs/login-error.log。

约束:不要改数据库结构,不要重写登录流程,只修复当前跳转问题。

完成标准:补充或更新测试,确认登录后能回到原访问页面,相关测试通过。

请先不要写代码,先阅读相关文件,给出你的理解、修改计划、风险点和验证方式。

资料来源

• OpenAI 官方 Codex best practices——Plan mode、interview you、PLANS.md、reasoning effort
• CSDN《Codex 使用最佳实践》——Plan 中文解读
• 与非网《Codex 高级用法:plan/goal/权限/AGENTS.md/Skills 实战教程》
• 官方 execution plans guide