Appearance
第五章：Plan Mode 规划模式
5.1 什么是 Plan Mode
在前面的章节中，我们学习了 Claude Code 的基本使用方法。大部分时候，你告诉它做什么，它就会直接去做——读取文件、修改代码、运行命令。
但对于复杂的任务，这种"边想边做"的方式可能不太合适。就像盖房子之前需要先画图纸一样，复杂的任务也需要先规划再执行。
Plan Mode（规划模式） 就是为此设计的。在这个模式下，Claude Code 会：
- 分析你的需求
- 探索相关的代码和文件
- 制定一个详细的实施方案
- 但不会实际修改任何文件
只有当你审核并批准了方案之后，再切换回普通模式执行。
一句话总结
Plan Mode = "先画图纸，再盖房子"。规划模式只思考不动手，等你确认后再执行。
5.2 为什么需要 Plan Mode
场景：没有规划的后果
想象一下，你对 Claude Code 说：
> 帮我把整个项目从 JavaScript 迁移到 TypeScript如果 Claude Code 直接开始执行，它可能会：
- 一口气改几十个文件
- 有些改动可能破坏了原有功能
- 改动范围太大，你不知道它改了什么
- 想回退也很困难
有规划的做法
使用 Plan Mode 后，Claude Code 会先给你一个方案：
Plan Mode > 帮我把整个项目从 JavaScript 迁移到 TypeScript
✻ 我来分析这个项目并制定迁移方案...
[读取项目结构]
[分析依赖关系]
[检查现有配置]
## TypeScript 迁移方案
### 第一阶段：基础配置（影响范围：小）
1. 安装 TypeScript 和相关依赖
2. 创建 tsconfig.json 配置文件
3. 更新 build 脚本
### 第二阶段：核心模块迁移（影响范围：中）
4. 迁移 src/utils/ 下的 12 个文件（无依赖，最安全）
5. 创建 src/types/ 目录，定义公共类型
6. 迁移 src/hooks/ 下的 8 个文件
### 第三阶段：组件迁移（影响范围：大）
7. 迁移 src/components/ 下的 32 个组件
8. 迁移 src/pages/ 下的 15 个页面
### 第四阶段：收尾（影响范围：小）
9. 更新测试文件
10. 清理残留的 .js 文件
11. 更新 CI/CD 配置
预计涉及 67 个文件，建议分 4 次完成，每次完成一个阶段后运行测试确认。
要我开始执行第一阶段吗？你可以清楚地看到整个计划，决定哪些要做、哪些不做、以什么顺序做。
Plan Mode 的核心价值
- 可预测性：你知道 Claude Code 将要做什么
- 可控性：你可以修改方案，调整优先级
- 安全性：不会在你不知情的情况下修改文件
- 质量：有规划的工作通常比临时发挥质量更高
5.3 如何进入 Plan Mode
有两种方式进入 Plan Mode：
方式一：使用 Shift + Tab 快捷键（推荐）
在输入框中按 Shift + Tab 键可以在三个模式之间循环切换。这是进入 Plan Mode 的主要方式：
> 这是普通模式的输入区域
[按 Shift + Tab]
> [Auto-accept edits] 自动接受编辑模式
[再按 Shift + Tab]
plan> 现在进入了 Plan Mode
[再按 Shift + Tab]
> 切回了普通模式你会注意到，输入提示符从 > 变成了 plan>，表示你现在处于 Plan Mode。中间的自动接受编辑模式（Auto-accept Edits）会自动确认所有文件修改操作，适合信任度高的批量操作场景。
方式二：使用 /plan 命令
也可以直接输入 /plan 命令进入 Plan Mode：
> /plan
✻ Switched to Plan Mode.
I will analyze and plan without making changes.
plan>推荐使用 Shift + Tab
Shift + Tab 是切换模式的主要方式，因为它更快捷，并且可以在三个模式之间灵活切换。/plan 命令也可以使用，但只能进入 Plan Mode。
退出 Plan Mode
再次按 Shift + Tab（循环切换到普通模式）或直接在普通模式下输入即可退出。
5.4 Plan Mode 的工作流程
一个完整的 Plan Mode 工作流程通常是这样的：
步骤 1：进入 Plan Mode
↓
步骤 2：描述你的任务
↓
步骤 3：Claude Code 探索和分析
↓
步骤 4：Claude Code 给出方案
↓
步骤 5：你审核方案
↓ ↙ 方案不满意？
↓ → 提出修改意见，回到步骤 4
↓
步骤 6：切换到普通模式
↓
步骤 7：让 Claude Code 执行方案
↓
步骤 8：验证结果详细示例
让我们走一遍完整的流程：
步骤 1-2：进入 Plan Mode 并描述任务
plan> 我想给商品管理模块添加批量导入功能。
用户可以上传 Excel 文件，系统自动解析并导入商品数据。
需要支持：商品名、价格、库存、分类、描述这些字段。
上传前需要数据校验，失败的行要给出明确的错误提示。步骤 3-4：Claude Code 分析并给出方案
✻ 让我分析当前项目结构和商品模块的实现...
[读取 src/pages/products/ 目录]
[读取 src/api/products.ts]
[读取 src/types/product.ts]
[读取 package.json 检查现有依赖]
## 批量导入功能实施方案
### 分析结果
- 当前商品模块位于 src/pages/products/
- 已有 ProductList、ProductDetail、ProductForm 三个页面
- 商品 API 在 src/api/products.ts 中定义
- 商品类型定义在 src/types/product.ts
- 项目未安装 Excel 解析库
### 需要新增的文件
1. `src/pages/products/ImportProducts.tsx` - 导入页面
2. `src/components/ExcelUploader.tsx` - Excel 上传组件
3. `src/utils/excelParser.ts` - Excel 解析工具
4. `src/utils/productValidator.ts` - 数据校验工具
### 需要修改的文件
5. `src/api/products.ts` - 添加批量导入接口
6. `src/types/product.ts` - 添加导入相关类型
7. `src/router/config.ts` - 添加路由
8. `src/pages/products/ProductList.tsx` - 添加"批量导入"按钮
### 需要安装的依赖
9. `xlsx` - Excel 文件解析库
### 实施步骤
1. 安装 xlsx 依赖
2. 定义导入相关的 TypeScript 类型
3. 创建 Excel 解析工具（支持 .xlsx 和 .xls）
4. 创建数据校验工具（校验必填项、数据格式、业务规则）
5. 创建上传组件（支持拖拽上传、文件大小限制）
6. 创建导入页面（预览数据、显示校验结果、确认导入）
7. 添加后端 API 接口定义
8. 更新路由和导航
9. 在商品列表页添加入口按钮
### 数据校验规则
- 商品名：必填，长度 2-100 字符
- 价格：必填，大于 0 的数字
- 库存：必填，非负整数
- 分类：必填，需匹配已有分类
- 描述：选填，最长 500 字符
### 预估工作量
- 新增代码：约 400 行
- 修改代码：约 50 行
- 涉及文件：8 个步骤 5：你审核方案
plan> 方案整体不错，有几个修改意见：
1. 不用安装 xlsx 库，我们后端会处理 Excel 解析，
前端只需要上传文件即可
2. 请添加一个导入历史记录功能，
可以查看之前的导入记录和状态
3. 上传文件大小限制为 5MBClaude Code 更新方案：
✻ 好的，我来更新方案：
### 调整内容
- 移除 xlsx 依赖安装，前端只负责上传文件
- 新增导入历史记录功能
- 添加 5MB 文件大小限制
### 更新后的文件列表
1. `src/pages/products/ImportProducts.tsx` - 导入页面（上传 + 历史）
2. `src/components/FileUploader.tsx` - 文件上传组件（5MB 限制）
3. `src/api/products.ts` - 添加上传和历史记录接口
4. `src/types/product.ts` - 添加导入相关类型
5. `src/router/config.ts` - 添加路由
6. `src/pages/products/ProductList.tsx` - 添加入口按钮
方案已更新，要我开始执行吗？步骤 6-7：切换到普通模式执行
plan> 方案确认，请开始执行
[按 Shift + Tab 切换到普通模式]
> 请按照刚才的规划方案执行
✻ 好的，我按照规划开始执行...
[开始创建和修改文件]5.5 Plan Mode 适用场景
适合使用 Plan Mode 的场景
| 场景 | 说明 | 复杂度 |
|---|---|---|
| 多文件重构 | 涉及修改 3 个以上文件的改动 | 高 |
| 新功能开发 | 从零开始添加一个完整功能 | 高 |
| 架构变更 | 修改项目结构、技术选型 | 很高 |
| 技术迁移 | 语言迁移、框架升级等 | 很高 |
| 性能优化 | 需要分析和制定优化策略 | 中高 |
| Bug 分析 | 复杂 bug 需要先定位原因 | 中 |
不需要使用 Plan Mode 的场景
| 场景 | 说明 | 直接执行即可 |
|---|---|---|
| 简单修改 | 改个颜色、改个文案 | 是 |
| 单文件操作 | 只涉及一个文件的修改 | 是 |
| 信息查询 | "这个函数是干什么的" | 是 |
| 代码生成 | 生成一个小工具函数 | 是 |
| 格式调整 | 代码格式化、排序 import | 是 |
判断标准
如果你觉得："让 Claude Code 直接去做，我能不能对它的改动有信心？"
- 如果答案是"能"，直接执行
- 如果答案是"不太确定"，先用 Plan Mode
5.6 实战演练：使用 Plan Mode 重构代码
让我们通过一个完整的实战案例来演练 Plan Mode。
任务背景
你发现项目中有很多重复的 API 错误处理代码，想要统一重构。
第一步：进入 Plan Mode，描述问题
plan> 我发现项目中很多地方的 API 调用都有重复的错误处理代码，
比如这样的模式反复出现：
try {
const res = await api.getUsers();
setData(res.data);
} catch (error) {
if (error.response?.status === 401) {
redirectToLogin();
} else if (error.response?.status === 403) {
showPermissionError();
} else {
message.error('请求失败');
}
} finally {
setLoading(false);
}
我想把这些重复的错误处理逻辑统一封装起来。
帮我规划一下如何重构。第二步：Claude Code 分析现状
✻ 让我先分析项目中 API 错误处理的现状...
[搜索所有包含 try/catch 和 API 调用的代码]
[分析错误处理的模式]
## 现状分析
我在项目中找到了 28 处类似的 API 错误处理代码，
分布在 15 个文件中：
### 重复代码统计
- 401 未授权处理：出现 28 次
- 403 权限不足处理：出现 20 次
- 网络错误处理：出现 25 次
- loading 状态管理：出现 28 次
### 变化点
- 成功后的数据处理逻辑（各不相同）
- 部分接口有特殊的错误处理（3处）
- loading 状态的变量名不统一
## 重构方案
### 方案一：自定义 Hook（推荐）
创建一个 `useApiRequest` Hook，封装通用逻辑：
```typescript
const { data, loading, error, execute } = useApiRequest(api.getUsers);优点：
- 最符合 React 的使用习惯
- 自动管理 loading 状态
- 统一错误处理
- 支持自定义错误处理
需要修改的文件：
- 新增：src/hooks/useApiRequest.ts
- 修改：15 个使用了 API 调用的文件
方案二：Axios 拦截器增强
在现有的 Axios 拦截器中增强错误处理：
优点：修改范围小 缺点：不能管理 loading 状态
方案三：两者结合（最优）
- 在 Axios 拦截器中处理通用错误（401/403/网络错误）
- 用自定义 Hook 管理 loading 和特殊逻辑
推荐方案三，分两步执行：
步骤一：增强 Axios 拦截器
- 修改 src/api/request.ts
- 添加统一的错误提示和 401 跳转
步骤二：创建 useApiRequest Hook
- 新建 src/hooks/useApiRequest.ts
- 封装 loading、error、data 状态管理
- 逐个文件替换原有的 try/catch 代码
步骤三：清理和验证
- 移除各文件中重复的错误处理代码
- 运行测试确保功能正常
- 处理 3 处特殊错误处理的情况
预计减少约 300 行重复代码。
### 第三步：审核并调整方案plan> 我同意方案三。但有几个补充： 1. useApiRequest 需要支持手动触发和自动触发两种模式 2. 需要支持请求取消（组件卸载时） 3. 那 3 处特殊错误处理的情况能不能先告诉我是哪里？
### 第四步：确认后执行plan> 方案没问题了，我们切到普通模式开始执行。 请先执行步骤一（增强拦截器），完成后我确认再继续。 [Shift + Tab 切换到普通模式]
请执行重构方案的步骤一：增强 Axios 拦截器
✻ 好的，开始执行步骤一... [修改 src/api/request.ts] ...
## 5.7 Plan Mode 使用技巧
### 技巧一：提供足够的上下文
在 Plan Mode 中描述任务时，提供越多的上下文，方案就越准确：不够详细
plan> 帮我优化性能
更好
plan> 用户反馈商品列表页在商品数量超过 1000 时非常卡顿。 目前的实现是一次性加载所有商品数据，然后在前端做分页。 我想改成后端分页，每次只请求当前页的数据。 另外，列表中的商品图片也可能需要做懒加载优化。
### 技巧二：分阶段规划
对于特别大的任务，可以让 Claude Code 分阶段规划：plan> 我们要把项目从 Create React App 迁移到 Next.js。 请先给我一个大的阶段划分， 每个阶段的详细方案我们单独讨论。
### 技巧三：要求评估影响范围plan> 我想把状态管理从 Redux 换成 Zustand。 请先评估一下影响范围： - 涉及多少个文件 - 有没有特别复杂的迁移点 - 预计需要多长时间 - 风险点有哪些
### 技巧四：要求提供替代方案plan> 我想提高首页的加载速度。 请给我 2-3 个方案对比， 包括每个方案的优缺点和实施难度。
### 技巧五：结合 CLAUDE.md 使用
在 CLAUDE.md 中记录项目的架构决策和技术规范，Plan Mode 会参考这些信息来制定更合适的方案。
```markdown
# CLAUDE.md 中的架构决策记录
## 架构决策
- ADR-001: 使用 Zustand 而非 Redux（2024-01 决定）
- ADR-002: API 层使用 Axios 统一封装（2024-02 决定）
- ADR-003: 组件库使用 Ant Design 5（2024-01 决定）
## 性能要求
- 首页加载时间 < 3 秒
- 列表页支持 10000 条数据
- 接口响应时间 < 500ms5.8 Plan Mode 与普通模式的对比
让我们通过同一个任务的不同处理方式来对比：
任务：给用户列表添加搜索功能
普通模式（直接执行）：
> 给用户列表添加搜索功能
✻ 我来添加搜索功能...
[修改 UserList.tsx - 添加搜索框]
[修改 api/users.ts - 添加搜索接口]
完成！
你：等等，搜索应该支持模糊匹配...
你：而且搜索框的样式和设计稿不一样...
你：还需要支持按不同字段搜索...
（不断修修补补）Plan Mode（先规划再执行）：
plan> 给用户列表添加搜索功能
✻ 让我分析需求和现有代码...
搜索功能方案：
1. 搜索方式：支持按姓名、邮箱、手机号搜索
2. 匹配规则：模糊匹配（后端 LIKE 查询）
3. 交互方式：搜索框 + 筛选条件下拉
4. 防抖处理：输入停止 300ms 后自动搜索
5. UI 位置：列表上方，和筛选按钮同行
涉及文件：
- UserList.tsx：添加搜索 UI
- api/users.ts：更新接口参数
- types/user.ts：添加搜索参数类型
需要确认：
- 搜索字段是否都满足需求？
- 要不要支持组合搜索？
- 搜索结果要不要高亮匹配的文字？
> 补充以下需求：
- 支持组合搜索
- 搜索结果高亮
- 添加"最近搜索"记忆功能Plan Mode 适合团队协作
当你是产品经理，需要让 Claude Code 帮你做技术方案评审或可行性分析时，Plan Mode 特别有用。它让你能在不写代码的情况下，理解技术方案的全貌。
5.9 高级用法：Plan Mode + 非交互模式
你也可以在非交互模式中使用 Plan Mode，这在自动化流程中很有用：
bash
# 让 Claude Code 分析并输出方案，但不执行
claude -p "分析 src/ 目录下的代码质量问题，给出改进方案，不要做任何修改"虽然这不是严格的 Plan Mode，但通过在提示中明确说明"不要做任何修改"，可以达到类似的效果。
5.10 常见问题
Plan Mode 中 Claude Code 可以读取文件吗？
可以。Plan Mode 中 Claude Code 可以读取文件和执行只读命令（如 ls、cat、git log 等），但不会修改文件或执行写入操作。它需要读取文件才能给出准确的方案。
Plan Mode 的方案会被记住吗？
会。当你从 Plan Mode 切换到普通模式时，之前讨论的方案仍然在对话上下文中。你可以直接说"按照刚才的方案执行"，Claude Code 会记住。
可以在 Plan Mode 中修改方案吗？
当然可以。Plan Mode 就是让你和 Claude Code 反复讨论、打磨方案的。你可以提出修改意见、补充需求、调整优先级，直到你满意为止。
Plan Mode 会消耗更多 token 吗？
Plan Mode 本身不会额外消耗 token。但因为规划阶段会有更多的分析和讨论，整体的 token 用量可能比直接执行多一些。不过考虑到规划带来的质量提升和避免返工，这个投入是值得的。
5.11 本章小结
| 要点 | 内容 |
|---|---|
| 作用 | 先规划再执行，避免盲目修改 |
| 进入方式 | Shift + Tab（推荐，循环三个模式）或 /plan |
| 工作流 | 描述任务 -> 分析 -> 方案 -> 审核 -> 执行 |
| 适用场景 | 多文件修改、新功能、架构变更、技术迁移 |
| 不需要的场景 | 简单修改、单文件操作、信息查询 |
| 核心价值 | 可预测、可控制、更安全、更高质量 |
练习任务
- 进入 Plan Mode，让 Claude Code 为你的项目制定一个"代码质量改进方案"
- 和 Claude Code 讨论方案，提出至少两个修改意见
- 确认方案后，切换到普通模式执行其中最简单的一步
- 使用 Plan Mode 规划一个新功能的添加方案（可以是任何你感兴趣的功能）
- 尝试在非交互模式中使用类似 Plan Mode 的方式获取分析报告
恭喜你完成了 Claude Code 基础教程的所有章节！让我们回顾一下整个学习路径：
| 章节 | 学习内容 | 核心技能 |
|---|---|---|
| 第一章 | 什么是 Claude Code | 理解工具定位和能力 |
| 第二章 | 环境搭建与安装 | 独立安装配置 |
| 第三章 | 基础使用方法 | 日常操作和命令 |
| 第四章 | CLAUDE.md 项目记忆 | 项目配置和效率提升 |
| 第五章 | Plan Mode 规划模式 | 复杂任务的规划与执行 |
继续学习
掌握了这些基础之后，你可以在日常工作中不断实践。Claude Code 的进阶用法（如 MCP 扩展、自定义 Slash Commands、CI/CD 集成等）可以在你熟练掌握基础后进一步探索。
最好的学习方式就是在真实项目中使用。从小任务开始，逐渐尝试更复杂的操作，你会越来越熟练的！