D5 · plan mode 与 explore→plan→code

D3 讲过:plan mode 本质上只是权限模式之一。但它值得单独上一课,因为围绕它长出了 Claude Code 官方最推荐的工作流——explore→plan→code。学完本课,你能判断一个任务该不该先 plan,并完整走通一次「探索 → 出计划 → 批准 → 实现」。

为什么这天学这个

本课直接承接 D3 · 权限模式与沙箱:那天你学了 default、acceptEdits、auto 等模式各自「不问就能做什么」,plan mode 也在那张表里。今天换一个视角——不再把 plan mode 当成一条权限配置,而是当成一种工作方式:把「搞清楚问题」和「动手改代码」拆成两个阶段,中间加一道由你把关的闸门。

它也为后面铺路:D6 · checkpoint / rewind 讲的是做错了怎么回退,而 plan mode 是让你少走到「需要回退」那一步;实战 Tip 「让 Claude 面试你,把需求聊成 SPEC」则是本课思路的进阶版——计划做得更重、更正式。本站观点跳过这课,你会习惯性让 Claude 拿到需求就开写,大任务上返工率明显更高。

概念讲清楚

官方plan mode 的定义一句话:让 Claude 只做研究、提出改法,但不真正改动。Claude 可以读文件、跑命令做探索、写出一份计划,但不会编辑你的源码;在批准计划之前,编辑一直被挡住(唯一例外见下文误区节)。CLI 状态栏此时显示 ⏸ plan mode on。官方给它的定位是「改动一个代码库之前先探索它」。

权限视角:拦住了什么、放行了什么

官方在 plan mode 下,读操作不需要批准。shell 命令分两种情况:如果你的账号具备 auto mode 条件,且 useAutoModeDuringPlan 设置开启(默认开启),计划阶段的 shell 命令由分类器模型审查——通过的直接运行,不通过的被拦下,不再弹窗问你;否则,内置只读命令集之外的命令仍会弹窗请求批准。

本站观点可以这样记:plan mode = 「读随便、写不行、跑命令看情况」。它拦的是对源码的修改,不拦你为搞清楚问题所需的一切探索动作。

进出与批准:一道闸门

官方进入 plan mode 有三条路:

会话中按 Shift+Tab 循环切换权限模式,顺序是 default → acceptEdits → plan;再按一次 Shift+Tab 即可不批准计划直接离开 plan mode。
单条消息前缀 /plan,只对这一条 prompt 启用计划模式。
启动时 claude --permission-mode plan;想让某个项目默认进 plan,可在 .claude/settings.json 里设 "permissions": {"defaultMode": "plan"}。

explore→plan→code 工作流:探索与计划都发生在 plan mode 里,「计划批准」是唯一的闸门;批准即退出 plan mode 开始实现,不批准则留在计划阶段继续打磨。

官方计划写好后,Claude 会把它摆出来问你怎么继续,通常有三个选项:

Yes, and use auto mode——批准并以 auto mode 开始执行;auto mode 不可用时这一项显示为 Yes, auto-accept edits;以 bypass permissions 启动的会话则显示 Yes, and bypass permissions。
Yes, manually approve edits——批准计划,但每个编辑逐一人工确认。
No, keep planning——留在 plan mode,告诉 Claude 计划哪里要改。

官方注意:批准计划会退出 plan mode,并把会话切换到你所选选项对应的权限模式。想再规划一轮,得重新 Shift+Tab 切回去或用 /plan 前缀。批准前还可以按 Ctrl+G 把计划文本打开到你的默认编辑器里直接改;接受计划还会自动用计划内容给会话命名(除非你已用 --name 或 /rename 起过名)。

为什么先探索再计划:官方的理由

官方best practices 里把这条列为核心建议之一,理由很直接:让 Claude 拿到需求就写码,产出的很可能是「解决了错误问题」的代码。plan mode 的作用就是把探索与执行分开。官方推荐的完整工作流是四步:Explore(在 plan mode 里读代码、回答问题)→ Plan(让 Claude 写出详细实现计划)→ Implement(批准计划或 Shift+Tab 退出后开始编码,并对照计划验证)→ Commit(提交并开 PR)。

本站观点换个讲法——这就是装修的逻辑:先量房看承重墙(探索),再画图纸报价(计划),你签字(批准)之后才开工(实现),最后验收交付(提交)。跳过前两步直接砸墙,砸错了的成本远高于画图纸的时间。对 LLM 还有一层额外收益:探索阶段读进上下文的代码,恰好构成实现阶段最相关的背景知识,写出的计划则把「要做什么」固定成文字,后续实现有了可对照的锚点,不容易越写越偏。

什么任务值得先 plan、什么不值得

官方判断标准官方plan mode 有用,但也有开销。范围清楚、改动很小的任务——改个 typo、加一行日志、重命名变量——直接让 Claude 做。计划最有价值的场景是:你对做法不确定、改动横跨多个文件、或者你对要改的代码不熟。官方给的一句话判断法:如果这个 diff 你能用一句话描述清楚,就跳过计划。

本站观点还有一个实用信号:你打算之后离开屏幕让 Claude 自己跑(比如批准后切 auto mode),就更值得先 plan——闸门是你在无人值守前的最后一次人工把关。

常见误区

误区一:「plan mode 下 Claude 什么命令都跑不了」。官方不对。读操作一直放行;auto mode 可用时,计划阶段的 shell 命令由分类器审查后自动放行或拦截。plan mode 拦的核心是「改你的源码」,不是「动任何东西」。

误区二:「进了 plan mode 就绝对安全」。官方有一个明确例外:在启用了 bypass permissions 的会话里,plan mode 的拦截并不强制执行——Claude 仍被指示只规划不编辑,但它若真的尝试编辑或跑命令,会直接执行而不弹窗。别把 plan mode 和 bypass 组合当成「只读保险箱」。

误区三:「批准计划后我还在 plan mode 里」。官方不在了。批准即退出,会话切换到你选的那个模式(auto / 逐个批准等)。很多人实现到一半想「再规划一下」,以为自己还在 plan mode,其实早已切出去了——要再按 Shift+Tab 或用 /plan。

当天能做完的实操

找一个你熟悉的真实项目(有几个源码文件即可),完整走一遍闸门流程,约 20–30 分钟:

以 plan mode 启动:claude --permission-mode plan。预期:状态栏出现 ⏸ plan mode on。
发一条探索 prompt(下面第一段可直接抄,把目录名换成你的)。预期:Claude 读文件、给出分析,但不改任何文件。
接着发第二段 prompt 让它出计划。预期:Claude 给出分步骤计划,并弹出批准选单(Yes, and use auto mode / Yes, manually approve edits / No, keep planning 三类选项,措辞随你的账号配置略有差异)。
先选 No, keep planning,提一条修改意见(比如「第 2 步先写测试再改实现」)。预期:仍在 plan mode,计划被更新。
在批准选单出现时按 Ctrl+G。预期:计划文本在你的默认编辑器里打开,可直接编辑,保存后回到选单。
选 Yes, manually approve edits。预期:状态栏的 plan mode 标记消失,Claude 开始按计划改代码,每个编辑单独弹窗让你确认。
收尾时按几次 Shift+Tab,观察 default → acceptEdits → plan 的循环,确认你能随时切回 plan mode。

通读 src/ 下和登录、会话相关的代码,搞清楚现在的认证流程。
先不要改任何文件。回答我两个问题:
1. token 是在哪里生成、哪里校验的?
2. 现在的会话过期逻辑写在哪个文件?

我想给登录加一个「记住我 30 天」选项。
基于刚才的探索,给我一份分步骤的实现计划:
每一步列出要改哪些文件、为什么改、以及改完怎么验证。
计划里明确标出哪些东西不在本次范围内。

验收标准

能不看文档说出进入 plan mode 的三种方式(Shift+Tab 循环、/plan 前缀、--permission-mode plan),以及不批准计划时怎么退出。
能解释 plan mode 在权限层面拦了什么、放行了什么,以及 bypass permissions 会话里的那个例外。
能复述批准选单的三类选项,并说清「批准 = 退出 plan mode + 切到对应模式」。
实操 7 步全部跑通,包括用 Ctrl+G 编辑过一次计划。
自测题一:「改一个 typo」和「跨五个文件接入 OAuth」,哪个该先 plan?用官方的一句话判断法说明理由。
自测题二:批准计划时选了「Yes, and use auto mode」,此刻会话处于什么权限模式?还在 plan mode 里吗?