Codex PLANS.md 怎么写？长任务规划官方姿势
Codex PLANS.md 怎么写？OpenAI 官方主推的长任务规划文件，本文给出 5 节模板、3 个真实案例、5 个常见错例，让 2 小时任务不丢方向
30 秒了解：Codex PLANS.md 到底解决什么问题
Codex PLANS.md 是一份给 AI 看的「任务剧本」——把一个 2-5 小时的连续大任务拆成 10-30 个可勾选的小步骤，让 Codex 边做边打勾。 这是 OpenAI 官方在 cookbook 里专门用一整篇讲的「长任务模式」，也是 Codex 跟其他 AI 编程工具拉开差距的地方。
为什么需要 PLANS.md？因为「一句话甩给 AI 一个大任务」必败：
- AI 上下文有限，做到一半忘了最初目标
- 复杂任务很多隐性依赖，AI 一次性想不全
- 出错时分不清「哪一步开始走偏」
- 中途断了不知道从哪续
PLANS.md 把任务外化成可勾选的清单，相当于给 AI 一份「备忘录」+「进度条」。Codex 每完成一步打勾、把进度写回文件——你睡一觉起来看文件就知道做到哪。
这篇按 OpenAI cookbook 的 codex_exec_plans 文章 + 实战，给一份「Codex PLANS.md 5 节模板」+ 3 个真实案例。如果你还没用过 Codex CLI，先看 Codex CLI 怎么用。
准备工作：什么任务该用 PLANS.md
不是所有任务都需要 PLANS.md。判断标准：
| 场景 | 用 PLANS.md 吗 |
|---|---|
| 改一行代码、改一个文件 | ❌ 过度工程 |
| 写一个新组件 | ❌ 直接说就行 |
| 重构整个模块 | ✅ 强烈推荐 |
| 升级框架版本（如 Next 13 → 15） | ✅ 必须 |
| 批量改 20+ 文件 | ✅ 必须 |
| 新功能跨 5+ 文件 | ✅ 推荐 |
| 调一个微妙 bug | ❌ 用 debug 模式 |
| 写一篇文档 | ❌ |
经验值：预计 AI 干 30 分钟内能搞定的，不用 PLANS.md；超过 1 小时的，用 PLANS.md。
Codex PLANS.md 的标准 5 节模板
PLANS.md 不是越长越好，控制在 200-400 行最合理。标准 5 节结构：
# 任务标题（一句话说清要做什么）
## 1. 总体目标
- 改造范围：[具体到目录或文件]
- 不变事项：[必须保持的接口/行为/约定]
- 完成标准：[3-5 条可验证的标准]
## 2. 背景上下文（给 AI 看的）
- 这个项目用什么栈
- 当前代码现状是什么
- 为什么要做这个改造
- 已知的坑和约束
## 3. 分步骤计划
### 阶段 1：[阶段名]
- [ ] 步骤 1.1：...
- [ ] 步骤 1.2：...
### 阶段 2：[阶段名]
- [ ] 步骤 2.1：...
（按你估的执行顺序，每步可独立验证）
## 4. 不要做的事
- ❌ 不要修改 X 文件
- ❌ 不要重命名 Y 变量
- ❌ 不要顺手优化无关代码
## 5. 出错时怎么办
- 如果某步测试挂 → 停下来，把报错贴给我，不要自己继续
- 如果不确定怎么改 → 在 PLANS.md 加 [BLOCKED] 标签等我看
- 如果上下文要满 → 在文件末尾写交接简报第 1 步：让 Codex 帮你起草 PLANS.md
不用自己一行行写。让 Codex 基于你的任务描述起草：
任务：起草一份 PLANS.md 给我们接下来的长任务用
任务全貌：把 src/api/v1/ 下所有 REST 端点改写为 GraphQL resolvers，迁到 src/graphql/，保持外部行为不变（同样的输入返回同样的输出）。
请按 PLANS.md 标准 5 节模板（总体目标 / 背景 / 分步骤 / 不要做的事 / 出错处理）起草。
在写之前先：
- 列出 src/api/v1/ 下所有 .ts 文件
- 估算 endpoint 数量
- 检查项目里是否已经有 GraphQL 相关依赖（grep package.json）
- 看完这些信息再起草 PLANS.md
起草完输出到根目录 PLANS.md。我会 review 后再说继续。
它扫描完你的项目、估算规模、产出一份初稿。你 review 一遍——重点改「分步骤」是不是合理、「不要做的事」是不是齐全。
第 2 步：让 Codex 按 PLANS.md 执行
PLANS.md 写好后，告诉 Codex 进入「执行模式」：
PLANS.md 已经 review 过了，可以开始执行。
执行模式规则：
- 你的所有动作都按 PLANS.md 的分步骤来，不要跳步
- 每完成一步：
- 跑相关测试验证
- 在 PLANS.md 把对应 [ ] 改成 [x]
- git commit 这一步的改动（commit message：「step N.M: …」）
- 每完成一个阶段：
- 跑完整测试套件
- 在 PLANS.md 对应阶段末尾加一行「阶段 N 完成 - YYYY-MM-DD HH:MM」
- 总结这阶段干了啥（3-5 句）
- 任何意外（测试挂、改不动、不确定）：
- 立刻停
- 在 PLANS.md 加 [BLOCKED: 描述] 标签
- 把意外情况贴给我等指示
- 不要私自跳过任何步骤或顺手改 PLANS.md 之外的事
开始第一步：步骤 1.1。
这种「显式声明执行规则」的开场能让 Codex 进入有纪律的工作模式，不会乱跑。
第 3 步：人在中途的 review 节奏
PLANS.md 模式不是「丢给 AI 自己跑」，而是「AI 跑 + 人在关键节点 review」。建议节奏：
| 时间点 | 你的动作 |
|---|---|
| 每个阶段结束 | review 阶段 commit + 看测试报告 |
| 每 30 分钟 | 看 PLANS.md 进度条、看最近 commits |
| 上下文用量 60-70% | 主动让 AI /compact |
| 上下文用量 80% | 让 AI 写交接简报、/clear、续 |
不需要每步都盯，但「阶段边界」一定要看——这是质量出问题的临界点。
第 4 步：处理 PLANS.md 中的「BLOCKED」
执行中肯定会遇到 AI 卡住。它在 PLANS.md 加 [BLOCKED: ...] 标签的时候，你来：
看到 PLANS.md 步骤 2.3 标了 [BLOCKED: src/api/v1/user.ts 用了未导出的内部类型 InternalUser，迁到 GraphQL 后这个类型该放哪]。
我的决定是：把 InternalUser 提到 src/types/internal.ts，所有 GraphQL resolver 共享 import。
请：
- 创建 src/types/internal.ts 包含 InternalUser 定义
- 把原 src/api/v1/user.ts 里的定义删了，改成 import
- 在 PLANS.md 把 [BLOCKED: …] 改成 [RESOLVED: 提到 src/types/internal.ts]
- 跑测试确认绿
- 继续步骤 2.3
PLANS.md 的好处是「BLOCKED 留痕」——所有卡点都在文件里，将来 retro 复盘有据可查。
3 个真实 PLANS.md 案例
案例 1：Next.js 13 → 15 升级
# Next.js 13 → 15 升级
## 总体目标
- 把项目从 Next 13.5 升到 15.0
- 接口零破坏（所有 page / API route 行为不变）
- 完成标准：pnpm build 绿 + pnpm test 绿 + 关键页面手动 smoke 测试通过
## 分步骤计划
### 阶段 1：依赖升级
- [ ] 1.1 package.json 改 next 到 ^15.0.0
- [ ] 1.2 跑 pnpm install
- [ ] 1.3 跑 pnpm build，记录所有 error
### 阶段 2：处理 breaking changes
- [ ] 2.1 cookies() 改成 await cookies()
- [ ] 2.2 headers() 改成 await headers()
- [ ] 2.3 params 类型从 {x: string} 改成 Promise<{x: string}>
### 阶段 3：清理 warnings
- [ ] 3.1 跑 pnpm build 看 warnings
- [ ] 3.2 修每条 warning
### 阶段 4：手动 smoke 测试
- [ ] 4.1 跑 pnpm dev
- [ ] 4.2 测主页、登录、详情页 3 个核心路径
## 不要做的事
- 不要顺手升级其他依赖（除非 Next 强制要求）
- 不要重构组件
- 不要改样式案例 2：批量国际化（i18n）
# 全站文案抽出做 i18n
## 总体目标
- 用 next-intl 把所有硬编码中文文案抽成 key
- 提供中英两种 locale
- 完成标准：grep -r "[一-龥]" src/ 只剩注释和测试
## 分步骤计划
### 阶段 1：基建
- [ ] 1.1 装 next-intl 配 middleware
- [ ] 1.2 建 messages/zh.json 和 messages/en.json
### 阶段 2：组件按文件夹批量改
- [ ] 2.1 components/auth/ - 5 个文件
- [ ] 2.2 components/dashboard/ - 12 个文件
- [ ] 2.3 components/settings/ - 8 个文件
- [ ] ...
### 阶段 3：page 层
...
## 不要做的事
- 不要翻译（英文留 [TODO_EN_TRANSLATION]，后面交翻译团队）
- 不要改文案本身（只是抽 key）案例 3：API rate limiting
# 给所有 public API 加 rate limiting
## 总体目标
- 用 @upstash/ratelimit 给 src/app/api/public/ 下所有 route handler 加限流
- 默认 100 req/min/ip，可在配置文件覆盖
- 完成标准：每个 endpoint 测试覆盖「超过限制返回 429」
## 分步骤计划
### 阶段 1：基建
- [ ] 1.1 装 @upstash/ratelimit @upstash/redis
- [ ] 1.2 配 .env 加 UPSTASH_REDIS_REST_URL/TOKEN
- [ ] 1.3 写 lib/ratelimit.ts 提供 withRatelimit() helper
### 阶段 2：按端点批量加
- [ ] 2.1 src/app/api/public/search/route.ts
- [ ] 2.2 src/app/api/public/login/route.ts（这个限制更严，10/min）
- [ ] 2.3 ...
### 阶段 3：测试
- [ ] 3.1 给每个端点写「超限返回 429」的单测
- [ ] 3.2 跑 pnpm test 全绿
## 不要做的事
- 不要改业务逻辑
- 不要顺手加 CORS / auth 相关改造
- /api/internal/ 不需要加限流（内部网络）5 个常见错例
错例 1：PLANS.md 太抽象
❌ 「步骤 1：重构 auth」 ✅ 「步骤 1.1：把 src/auth/login.ts 的 callback 改 async/await」「步骤 1.2：跑 auth 相关测试」
错例 2：步骤间依赖混乱
❌ 步骤 5 依赖步骤 3 的产出，但顺序写反了 ✅ 用「阶段」组织，阶段内步骤可并行/独立
错例 3：没写「不要做的事」
❌ 只写要做什么 ✅ 必须写禁区，否则 AI 顺手「优化」无关代码
错例 4：完成标准不可验证
❌ 「代码质量更好」「性能更好」 ✅ 「pnpm test 全绿」「构建产物体积小于 500KB」
错例 5：PLANS.md 写完不更新
❌ 起草完丢一边，AI 实际跑跟文件脱节 ✅ 每步打勾、每阶段总结、BLOCKED 留痕
常见坑 + 解决办法
| 现象 | 原因 | 解决 |
|---|---|---|
| AI 不按 PLANS.md 顺序 | 没明确「执行模式规则」 | 用第 2 步那段 prompt 严格声明 |
| AI 改了 PLANS.md「不要做的事」 | 规则没写或没强调 | 在 prompt 里再重复一次 |
| 进度文件没更新 | AI 偷懒 | 每阶段结束让它「确认 PLANS.md 已更新」 |
| 上下文塞满中断 | 长任务超过窗口 | 用 Kimi Code 上下文管理 那篇的技巧 |
| 全部完成但测试还红 | 中途某步没真验证 | PLANS.md 加「每步必须跑测试」硬性要求 |
Codex PLANS.md vs Claude Code 的对应做法
| 维度 | Codex PLANS.md | Claude Code |
|---|---|---|
| 官方推荐 | ✅ cookbook 专文 | ⚠️ 社区自创 |
| 文件名 | PLANS.md | 用户自定义（常用 TASKS.md） |
| 与 AGENTS.md 关系 | AGENTS.md 是项目持久记忆，PLANS.md 是单任务剧本 | CLAUDE.md vs 任务文件同理 |
| 适用场景 | 2-5 小时长任务 | 同 |
| 思路 | 完全通用 | 完全通用 |
PLANS.md 思路本身跟工具无关——你在 Claude Code、Cursor、Cline 上都能用同一份模板。
下一步
- Codex 整体介绍 → Codex 是什么
- Codex CLI 上手 → Codex CLI 怎么用
- Codex 改老代码 → Codex 改写老代码
- Codex 自动修 CI → Codex 修 CI
- Codex Code Review → Codex Code Review 工作流（待发布）
- AGENTS.md / CLAUDE.md 写法 → CLAUDE.md 怎么写
- 长会话续命 → Kimi Code 上下文管理
- AI 编程全景 → AI 写代码完全指南
常见问题
Q：PLANS.md 一定要叫这个名吗？ A：不强制，但建议保留。OpenAI cookbook 用这个名字、社区也在传播这个约定，团队协作时少解释。叫 TASKS.md / ROADMAP.md 也行，但要在 AGENTS.md 里说明。
Q：PLANS.md 该 commit 到 git 吗？
A：建议 commit。理由：1) 团队成员能看到 AI 在做啥；2) 任务做完后留作 retro 资料；3) 跨会话续任务有据可查。任务完成后可以归档到 docs/plans/ 子目录。
Q：一份 PLANS.md 能给多个 AI 工具用吗？ A：能。PLANS.md 是纯 markdown 文本，Codex / Claude Code / Cursor 谁能读 markdown 谁就能用。但模型理解能力不同，PLANS.md 的明确程度要按最弱的那个调。
Q：AI 把 PLANS.md 越改越糟怎么办？ A：在 prompt 加一条「修改 PLANS.md 必须先给我看 diff」。或者把 PLANS.md 锁住，只允许 AI 在「进度区」打勾、不允许改其他部分。
Q：跟普通的 TODO 注释比有啥优势？ A：TODO 散在代码里、没有顺序、没有完成标准、不携带上下文。PLANS.md 是「一份完整执行计划」，给 AI 看的同时也给团队看，是文档+任务管理+AI 工具三合一。