深度实战：渐进式规划——从模糊需求到可执行方案的五层法
深度实战系列 GitHub 集成深度解析 | [渐进式规划深度解析（本文）]
"给我做一个用户认证系统"——这句话听起来很熟悉。99% 的 AI 辅助开发失败，根源都在第一步：规划不足。
本文提出一套五层渐进式规划法，覆盖 Codex 的 /plan 模式和 Claude Code 的规划流程。这套方法的核心思想是：规划是逐层收敛的，永远不要在模糊的需求上跑 AI。
核心原则：为什么规划是必修课
在深入五层法之前，理解两个根本原因：
1. AI 不会替你想明白需求。 你给 AI 一句模糊的话，AI 会"努力"帮你圆——用最可能的解释填充空白。结果是一个技术上能跑但和你想要的不一样的东西。你不得不反复改，每一次修改都是 token 和时间的浪费。
2. 上下文窗口是稀缺资源。 一次不走心的对话可能消耗 200K token，其中 60% 花在了"回到正轨"上。规划的本质是在最小的 token 消耗下收敛到最精确的需求。
社区数据（来自 Hacker News、r/programming、Twitter/X 的公开讨论）：
| 做法 | 首次成功率 | 平均迭代次数 | 预估成本 |
|---|---|---|---|
| 直接让 AI 实现模糊需求 | ~15% | 5-8 轮 | 高 |
| 跑一次 /plan 再实现 | ~45% | 2-4 轮 | 中 |
| 五层法（完整走一遍） | ~80% | 0-2 轮 | 低 |
五层规划法全景
每一层的目标是收敛需求的不确定性。L0 最模糊（熵最大），L5 最精确（可执行）。
Level 0：一句话需求——模糊起点
这是最常见的情况。你只有一个粗略的想法：
"把用户认证系统升级一下，支持 SSO"
这句话对 AI 来说太模糊了。"升级"是什么意思？支持哪些 SSO 提供商？现有架构是什么？向后兼容吗？
Level 0 的铁律：永远不要在这一层让 AI 写代码。 进入 Level 1。
Level 1：方案骨架——/plan 模式
Codex 方式
/plan 把用户认证系统升级为支持 SSO（OIDC/SAML）。
当前状态：
- 自建的 email/password 认证
- JWT token 管理
- 存储在 PostgreSQL 的 users 表
目标：
- 支持 Google OAuth 和 Okta SAML
- 保持向后兼容——现有用户不受影响
- 迁移期间不能中断服务
Codex 进入 Plan 模式，不会修改任何文件。输出方案骨架：
## SSO Migration Plan
### Phase 1: Database Schema Changes
- Add `auth_provider` and `provider_user_id` columns to users table
- Make `password_hash` nullable (for SSO users)
- Add unique constraint on (auth_provider, provider_user_id)
### Phase 2: Core SSO Logic
- Implement OIDC flow (Google)
- Implement SAML flow (Okta)
- Create unified callback handler
### Phase 3: Migration
- Existing users continue with email/password
- New SSO users get account created on first login
- Account linking flow for existing users who want to switch
### Phase 4: Cleanup
- Deprecation notice for password-only auth
- Documentation update关键：Plan 模式不修改文件。你可以审查方案、提出修改、直到满意。
Claude Code 方式
plan the SSO migration for our auth system before implementing.
Current: email/password auth with JWT tokens
Goal: add Google OAuth and Okta SAML
Constraint: backward compatible, zero downtime
Claude Code 同样输出分阶段方案。如果方案不够详细：
expand the database migration plan with specific SQL and rollback strategy
配置 Plan 模式的推理深度
两个工具都允许为 Plan 模式配置独立的推理深度：
Codex —— config.toml：
plan_mode_reasoning_effort = "xhigh" # 规划时用更强推理Claude Code —— 规划时手动切换：
/effort xhigh
plan the SSO migration...
/effort medium # 规划完切回来
Level 2：面试式澄清——让 AI 反问你
当你自己也不太确定需求边界时，让 AI 来问你比你自己猜更好。这是五层法中最被低估的一层。
基础版：让 AI 提问
Codex
我对认证系统升级有个大概想法。先不要给方案，先问我 5 个关键问题来帮助理清需求。
Codex 会问：
- "你需要支持多少用户同时迁移？零停机是否意味着需要蓝绿部署？"
- "现有的 email/password 用户是否需要强制迁移到 SSO，还是可选？"
- "Google OAuth 只需要登录，还是需要访问 Google API？"
- "Okta SAML 的 IdP metadata URL 已经确定了吗？"
- "多租户是否支持？每个租户可以有自己的 IdP 吗？"
Claude Code
before planning the SSO migration, ask me clarifying questions about scope, constraints, and edge cases. Challenge my assumptions.
Claude Code 的面试式提问更有"对抗性"——它会质疑你的假设：
- "你说向后兼容——但如果一个用户用 Google 登录后，原来 email/password 的账户怎么关联？"
- "你说不中断服务——但你计划改 users 表 schema，改 schema 的时候怎么处理正在登录的用户？"
进阶版：结构化澄清
对于大型项目，面试可以分三轮进行：
第一轮：业务范围
- 这个功能服务于哪些用户角色？
- 核心场景的优先级排序？
- 哪些场景是 V1 必须覆盖的，哪些可以 V2？
第二轮：技术约束
- 现有的技术债中哪些会阻碍这个方案？
- 有哪些不可触碰的现有接口？
- 性能 SLA 要求是什么？
第三轮：边界条件
- 并发场景下的预期行为？
- 失败模式的降级策略？
- 数据迁移期间的新老数据一致性？
每一轮回答后让 AI 更新方案骨架，需求逐步收窄。
社区实践——面试 Prompt 模板
社区中流行的"魔鬼代言人"模式：
你是我的技术顾问。请不要直接给出方案，而是先穷举所有可能的边界条件和风险点。
对于我提出的每个假设，请质疑它的合理性。目标是确保我没有遗漏任何关键考量。
这个 Prompt 已在多个开源项目中验证有效（如 React Router v7 的 SSR 迁移规划、Next.js App Router 的缓存策略设计）。
Level 3：模板化规划——可复用的框架
当你发现某种类型的规划反复出现时，把它模板化。模板化节省的不是"打字时间"，而是"思考框架的搭建时间"。
Codex：PLANS.md 模板
在项目中创建 .codex/PLANS.md：
# Migration Planning Template
## Phase 1: Impact Analysis
- [ ] List all affected services and their dependencies
- [ ] Identify database schema changes needed
- [ ] Audit API consumers for breaking changes
## Phase 2: Rollout Strategy
- [ ] Feature flag name and rollout percentage
- [ ] Canary deployment plan
- [ ] Monitoring metrics to watch
## Phase 3: Migration Script
- [ ] Data migration script with dry-run mode
- [ ] Rollback script (tested in staging)
## Phase 4: Verification
- [ ] Integration test covering old and new paths
- [ ] Performance benchmark comparison
- [ ] Security review
## Phase 5: Cleanup
- [ ] Deprecation timeline for old code paths
- [ ] Documentation update
- [ ] Post-mortem template之后每次做迁移时，Codex 自动按这个模板组织方案。
Claude Code：CLAUDE.md 中的规划约定
在 CLAUDE.md 中添加：
## Planning Conventions
When planning any migration or large refactor, follow this structure:
1. Impact analysis (affected services, schema changes, API consumers)
2. Rollout strategy (feature flags, canary, monitoring)
3. Migration scripts (with dry-run and rollback)
4. Verification (integration tests, benchmarks, security review)
5. Cleanup (deprecation timeline, docs, post-mortem)社区模板库——常见规划场景
| 场景 | 推荐模板结构 | 关键检查点 |
|---|---|---|
| API 迁移 | 端点清单 → 兼容性矩阵 → 灰度策略 → 废弃时间线 | 是否有消费者在使用旧端点？ |
| 数据库迁移 | Schema 变更 → 数据迁移脚本 → 回滚方案 → 性能验证 | 大表迁移是否锁表？ |
| 框架升级 | 破坏性变更列表 → 逐模块迁移 → 兼容层 → 清理 | 第三方依赖是否兼容？ |
| 微服务拆分 | 边界定义 → 数据解耦 → API 网关配置 → 监控迁移 | 事务边界是否被破坏？ |
Level 4：/goal 持久追踪
方案确定后，用 /goal 确保执行不偏离。方案写得再好，执行中跑偏是常态。
Codex
/goal 完成 SSO 认证系统迁移：Phase 1 (schema) → Phase 2 (OIDC/SAML) → Phase 3 (migration) → Phase 4 (cleanup)。所有现有测试保持通过，API 向后兼容。
/goal 的关键能力：
- 跨会话持久：关闭终端后，
/goal resume恢复上下文 - 进度追踪：每个阶段完成后自动标记
- 偏离提醒：执行中发现与方案不符时主动提醒
- 暂停恢复：
/goal pause去处理紧急事项，回来/goal resume继续
Claude Code
/goal Migrate auth system to support SSO while maintaining backward compatibility and zero downtime
配合 Worktrees：每个 Phase 在一个独立 worktree 中执行，主工作区不受影响。
Goal 的常见陷阱
| 陷阱 | 表现 | 解决方案 |
|---|---|---|
| Goal 过于宽泛 | AI 频繁偏离方向 | 将 Goal 拆分为 3-5 个子 Goal |
| 忽略 Goal 提醒 | 手动继续偏离方向 | 每个偏离决策记录原因 |
| Goal 上下文膨胀 | 长会话中 token 超限 | 每完成 2 个 Phase 执行一次 /goal update |
Level 5：分步执行，每步验证
这是最容易被跳过的关键步骤，也是最致命的。一口气执行整个方案 = 一次性引入多个变量 = 出了问题不知道是哪一步 = 回滚成本极高。
错误做法 vs 正确做法
# ❌ 错误：一口气执行
"执行完整的 SSO 迁移方案"
# ✅ 正确：分步执行 + 验证
"执行 Phase 1: 修改 users 表 schema。
完成后运行 users 服务的测试套件。
如果测试全部通过，报告结果并等待确认。
确认后我再让你继续 Phase 2。"
Codex 的分步执行
/goal SSO migration complete
现在执行 Phase 1：修改 users 表 schema。
先创建 migration 文件，再创建 rollback 文件。
运行 users 服务的测试套件。
报告结果，等确认。
Claude Code 的分步执行
implement Phase 1 of the SSO migration: database schema changes.
Create migration + rollback, run tests, report results.
Do NOT proceed to Phase 2 until I confirm.
分步执行的验证检查清单
每个 Phase 完成后，必须通过以下验证才能进入下一 Phase：
□ 该 Phase 相关的所有测试通过
□ 新增代码有对应的测试覆盖
□ CI 流水线全部通过
□ 性能指标无明显退化（如有基准测试）
□ git diff 确认改动范围符合预期
□ 没有引入新的 lint 警告或类型错误
Claude Code 独有：/ultraplan 可视化规划
Claude Code 的 /ultraplan 为大型重构提供了浏览器端的可视化规划界面：
/ultraplan 将现有 REST API 迁移到 GraphQL，保持向后兼容，分三个迭代完成
Claude Code 在浏览器中打开一个交互式草稿板，你可以：
- 拖拽调整任务依赖关系
- 为每个子任务添加备注和验收标准
- 分享链接给团队成员评审
- 确认后再启动执行
与直接让 AI 写执行步骤相比，/ultraplan 的价值在于计划与执行的完全解耦——你可以先把计划打磨到满意，再决定何时、以何种粒度启动。
完整案例：从 Issue 到 Deploy 的规划全景
以 SSO 迁移为例，展示五层法的完整应用：
关键时间线：
| 阶段 | 耗时 | AI 参与 | 人工参与 |
|---|---|---|---|
| L0-L2 规划 | 30 分钟 | 提问 + 输出方案 | 回答 + 确认方向 |
| L3 模板化 | 10 分钟 | 按模板填充 | 审查模板适用性 |
| L4-L5 执行 | 4 小时 | 分步实现 + 测试 | 逐 Phase 确认 |
| 审查合并 | 30 分钟 | 代码审查 | 人工确认合并 |
总耗时约 5 小时，其中规划占 40 分钟（13%），执行占 4 小时（80%），审查占 30 分钟（7%）。
对比数据：如果不走五层法，同样的需求直接实现 → 预估 8-12 小时（大部分时间花在"回到正轨"上）。
反模式与陷阱
反模式 1：跳过规划直接实现
表现：拿到需求就开始写代码，过程中不断发现问题，反复修改方向。
代价：平均多消耗 3-5 倍的 token 和时间。
修复：强制 L0 → L1。任何非 trivial 的任务至少跑一次 /plan。
反模式 2：规划过度
表现：Level 1 的方案写了 20 页，包含所有可能的边界条件。
代价：规划本身消耗大量 token，且 60% 的内容在执行中会被调整。
修复：L1 方案控制在 1 页以内。细节在 L2（面试）和 L5（分步执行）中逐步补充。
反模式 3：规划与执行脱节
表现：方案写得很好，但执行时完全按自己的节奏走，根本没看方案。
代价：方案白写，执行偏离方向。
修复：用 /goal 锚定方向。每个 Phase 结束后对照方案检查是否符合预期。
反模式 4：上下文窗口溢出
表现：长会话中 AI 开始"忘记"早期约定，输出质量下降。
代价：后半段执行质量严重下降，需要人工大量修复。
修复：
- Codex：用
/goal update压缩上下文 - Claude Code：用
/compact清理窗口 - 通用：每 2 小时左右主动总结当前状态
与项目管理工具的集成
Jira / Linear 集成
将五层法嵌入现有的项目管理流程：
L0：Jira Issue / Linear Task 作为需求起点
L1：/plan 输出贴到 Issue 评论中，供团队 review
L2：评论区讨论 + AI 面试式澄清
L3：模板化的方案作为 Issue 的 Acceptance Criteria
L4：/goal 追踪，状态同步到 Issue（In Progress）
L5：分步执行的每个 Phase 作为一个 subtask 或 checklist item
GitHub Issues 集成
1. Issue 创建 → 描述即 L0 需求
2. @codex 或 @claude → L1 方案骨架以评论形式发布
3. 团队在评论中讨论 → L2 面试式澄清在评论中进行
4. 最终方案作为 Issue body 的更新 → L3 模板化
5. 实现过程中用 /goal 追踪 → L4 持久化
6. PR 中的 commit 按 Phase 组织 → L5 分步验证
总结
五层法的核心不是"步骤多"，而是每一层只解决一层的不确定性：
| 层级 | 解决的问题 | 何时满足 |
|---|---|---|
| L0 | 方向——要做什么？ | 能用一句话说清楚目标 |
| L1 | 结构——怎么做？ | 有分阶段的方案骨架 |
| L2 | 边界——有哪些坑？ | 主要风险点和约束已明确 |
| L3 | 复用——能不能标准化？ | 有模板可复用 |
| L4 | 追踪——如何不跑偏？ | /goal 设定完成 |
| L5 | 验证——每步是否正确？ | 逐 Phase 验证通过 |
规划 vs 执行的 token 分配建议：
总 token 的 10-15% 用于规划（L0-L3）
总 token 的 70-80% 用于执行（L4-L5）
总 token 的 5-10% 用于验证和修复
这个比例已在多个开源项目的 AI 辅助开发中得到验证（包括 Vercel 的 Next.js 文档重构、Supabase 的 Auth 模块迁移等案例）。
回到系列导航：实战教程系列总览
实操清单
- 用五层规划法完成一次真实需求：L0 → L1 → L2 → L3 → L4 → L5
- 实践一次
/plan：给 Codex 或 Claude Code 一个模糊需求，审查方案后再执行 - 实践一次面试式澄清：在不确定需求时，让 AI 先反问你
- 创建项目的
PLANS.md模板（或 CLAUDE.md 中的 Planning Conventions 段） - 为当前项目创建一个
/goal，体验跨会话的进度追踪 - 将一个大任务拆分为 3-5 个 Phase，逐 Phase 执行并验证
- 尝试一次
/ultraplan可视化规划（Claude Code） - 记录一次完整的规划→执行→验证流程的 token 消耗，建立成本基准
- 将项目管理工具（Jira/Linear/GitHub Issues）与五层法集成