Plan Mode 不是"慢模式",而是让你在修改任何文件之前,先让 Claude Code 看到全局地图,从而避免蝴蝶效应式的连锁修改。

---

本节目标

1. 理解 Plan Mode 的设计哲学:为什么要"先规划,后执行"

2. 掌握 Plan Mode 的触发方式与信号识别

3. 熟练使用 Explore-Plan-Implement-Verify 四步工作流

4. 学会何时必须使用 Plan Mode,何时可以跳过

5. 能够撰写高质量的 Plan 文档并驱动实现

---

核心知识点

蝴蝶效应问题

在 Claude Code 的日常使用中,最常见的翻车场景是"上下文蝴蝶效应":

你在文件 A 中修改了一个函数签名
→ 文件 B 的调用处报了类型错误
→ 修复文件 B 时顺手改了它的逻辑
→ 文件 C 的测试挂了,因为依赖了文件 B 的旧行为
→ 已经改到第四个文件时才意识到方向错了

Plan Mode 的核心理念是:在动任何代码之前,先在"只读规划"模式下完成全局分析,生成一份可审查的计划文档,确认方向无误后再进入实现阶段。

Plan Mode 的技术本质

Plan Mode 并非一个独立的后端服务,而是一种上下文编排策略:

维度	普通模式	Plan Mode
文件修改	允许直接写入	默认只读
探索范围	按需读取	系统性扫描
输出产物	代码变更	计划文档
审查节点	无强制节点	计划确认后方可执行
成本	低(单次操作)	中(探索 + 计划生成)

触发方式

Claude Code v2.1.x 中,有三种方式进入 Plan Mode:

方式一:快捷键 按下 Shift+Tab 两次,在输入框底部可以看到 Plan Mode 的开关状态切换。开启后输入框会显示蓝色边框和"Plan Mode"标识。

方式二:指令触发 在对话中直接使用 /plan 命令:

/plan 实现用户认证模块的重构

方式三:自动建议 当 Claude Code 检测到你的请求涉及多个文件修改时,会自动建议进入 Plan Mode:

检测到该任务可能影响 5+ 个文件。是否切换到 Plan Mode 先做规划?
[Y] 切换 [N] 继续直接执行

何时必须使用 Plan Mode

以下场景强烈建议使用 Plan Mode:

1. 跨模块重构:涉及 3 个以上文件的接口变更

2. 架构决策:引入新的设计模式、技术栈或数据流

3. 删除/废弃功能:需要分析所有引用点和影响范围

4. 数据库 Schema 变更:Migration 伴随代码变更

5. 第三方依赖升级:API 破坏性变更的影响评估

6. 团队协作任务:计划文档本身就是团队的沟通媒介

何时可以跳过 Plan Mode

以下场景可以放心跳过:

1. 单文件小修改:修改变量名、调整配置、修复拼写错误

2. 纯增量的添加:在已有模式的框架下新增一个类似组件

3. 已明确的需求:PR 描述中已经包含了详细的实现方案

4. 探索性实验:你在尝试一个想法,不打算马上合并

---

实操步骤

步骤 1:进入 Plan Mode 并执行 Explore(探索)

# 方式一:快捷键 Shift+Tab 两次后输入任务描述
# 方式二:直接使用 /plan 命令
/plan 将现有的 REST API 客户端从 axios 迁移到 fetch API

进入 Plan Mode 后,Claude Code 会首先进入探索阶段:

[Plan Mode - Explore]
正在扫描项目结构...
​
发现受影响的文件:
- src/api/client.ts (核心客户端,需要重写)
- src/api/interceptors.ts (拦截器逻辑,需要适配)
- src/api/types.ts (类型定义,可能不变)
- src/hooks/useApi.ts (Hook 封装,接口可能变化)
- tests/api/client.test.ts (测试,必须同步更新)
- tests/api/interceptors.test.ts (测试,必须同步更新)
​
共 6 个文件可能受影响。正在分析依赖关系...

你可以通过 Ctrl+G 在任何时候将当前计划内容发送到外部文本编辑器中进行详细编辑和审查。

步骤 2:生成 Plan 文档

探索完成后,Claude Code 会生成一份结构化的计划文档:

# Plan: axios → fetch API 迁移
​
## 影响范围
- 核心文件: src/api/client.ts
- 下游消费者: src/hooks/useApi.ts, src/components/* (12 个文件)
- 测试文件: tests/api/ (2 个文件,覆盖 87%)
​
## 实施步骤
### Phase 1: 核心适配层
1. 创建 src/api/fetch-client.ts,实现与旧 client.ts 相同接口
2. 将拦截器逻辑迁移到 fetch 中间件模式
3. 类型定义不变,确保接口兼容
​
### Phase 2: 逐文件替换
4. 替换 useApi.ts 中的导入路径
5. 逐组件替换,每批 4 个文件,每批后运行测试
​
### Phase 3: 清理
6. 删除 axios 依赖
7. 删除旧 client.ts 和 interceptors.ts
8. 更新 package.json
​
## 风险点
- fetch 不原生支持请求超时,需 AbortController 封装
- 上传进度回调 fetch 不支持,需评估影响
- 拦截器测试中的 axios mock 需要重写
​
## 回滚方案
- 保留原文件备份,branch 为 feat/fetch-migration
- 每阶段 commit,方便逐个 revert

步骤 3:审查并确认 Plan

执行 Ctrl+G 将计划文本发送到 VS Code 或你配置的外部编辑器,仔细审查:

• 影响范围是否遗漏了任何文件

• 实施顺序是否合理(是否可以先做低风险部分)

• 风险点是否有对应的缓解措施

• 回滚方案是否真实可用

确认无误后,对 Claude Code 说"批准此计划,开始执行"或输入 @implement。

步骤 4:Implement 与 Verify

Claude Code 会按计划逐步执行,每完成一个 Phase:

[Plan Mode - Implement]
Phase 1/3: 核心适配层
✅ src/api/fetch-client.ts 已创建
✅ 拦截器中间件已实现
⏳ 类型兼容性测试运行中...
​
Phase 1 完成,测试通过。继续 Phase 2? [Y/n]

你可以在任何阶段暂停审查。如果发现偏差,可以说"偏离了计划,请重新评估"。

---

避坑指南

坑 1:Plan Mode 不等于"不用思考"

错误心态:进入 Plan Mode 就万事大吉,全交给 AI。

正确做法:Plan Mode 产出的计划文档是你的决策辅助工具,不是决策替代品。你需要审查:

• 分阶段是否合理(有没有可以合并的步骤)

• 风险识别是否全面(有没有遗漏的边界情况)

• 回滚方案是否可操作(能不能真的三分钟内回退)

坑 2:在 Plan Mode 中过早进入实现

Claude Code 在 Plan Mode 下也可以写文件,但你需要显式批准。如果你在探索不充分的情况下就批准了代码修改,Plan Mode 的保护机制就失效了。

实践建议:在生成计划文档之前,不要批准任何文件修改操作。先把计划写完、审完、确认完,再批准执行。

坑 3:跳过了有必要的 Plan Mode

一个粗略的判断标准:如果你的修改需要 git commit message 超过一行来描述,就应该考虑 Plan Mode。

# 这类修改可以跳过 Plan Mode
git commit -m "fix: correct typo in README"
​
# 这类修改应该使用 Plan Mode
git commit -m "refactor: migrate auth module from JWT to session-based"
​
详细说明:
- 移除 jwt-utils.ts
- 新增 session-store.ts
- 更新中间件 auth-middleware.ts
- 更新所有受影响的 API 路由(12 个文件)

坑 4:忽略 Ctrl+G 编辑能力

Plan Mode 产生的计划是可以编辑的。不要直接接受第一版计划。使用 Ctrl+G 将计划发送到编辑器:

• 调整实施顺序

• 补充遗漏的测试步骤

• 修改你不认同的技术决策

• 添加团队成员需要关注的要点

编辑后的计划会回传给 Claude Code,它会基于编辑后的版本执行。

---

课后作业

作业 1:诊断"该用但没用 Plan Mode"的场景

回顾过去一周你的 Claude Code 使用记录,找出至少 2 个"应该使用 Plan Mode 但没有使用"的场景。对每个场景:

1. 描述你做了什么修改

2. 分析如果当时用了 Plan Mode,能避免什么问题

3. 如果再来一次,Plan 文档应该包含哪些要点

作业 2:实践一次完整的 Plan Mode 工作流

1. 在你的项目中找到一个涉及 3 个以上文件的功能变更

2. 使用 /plan 命令进入 Plan Mode

3. 审查生成的计划文档:用 Ctrl+G 在编辑器中修改至少一处

4. 批准并执行计划

5. 执行完成后复盘:

   • 计划与实际执行的偏差在哪里

   • 有没有计划遗漏的风险点

   • 整个过程比直接写代码是多花了时间还是省了时间

作业 3:编写 Plan Mode 的使用判断清单

基于你的项目特点,编写一份"何时使用 Plan Mode"的判断清单,格式如下:

## 我的 Plan Mode 判断清单
​
### 必须使用:
- [ ] 涉及 X 个以上文件
- [ ] 
​
### 建议使用:
- [ ] 
​
### 可以跳过:
- [ ] 

---

总结

Plan Mode 是 Claude Code 最被低估的功能之一。它的价值不在于"让 AI 帮你写计划",而在于:

1. 强制性的"先看后改":在你动任何代码之前,系统性地扫描影响范围,这是人类也做不到的全面性

2. 可审查的决策节点:计划文档给了你一个明确的"确认点",防止 AI 在你没注意的时候做错了方向

3. 团队的沟通媒介:一份好的 Plan 文档本身就是团队的异步沟通工具

记住四个字:探索先行。在 Claude Code 的世界里,花 5 分钟做探索和规划,往往能省下后续 50 分钟的调试和回滚。

下一步:学习如何用 CLAUDE.md 进阶配置来为 Plan Mode 提供项目级别的引导,让它产出更贴合你项目实际情况的计划。