Plan Mode 是 Claude Code 内置的只读权限模式，作用是让 Agent 在不修改任何文件的前提下完成代码探索与方案设计；它把”理解问题”和”动手改代码”两件事硬性隔开，使坏方案在落地前就能被拦截。当改动涉及多文件、不熟悉代码库、需要在多种方案中抉择时启用 Plan Mode 收益最大；改动可以一句话说清、或者只动一行时直接执行更划算。
一、Plan Mode 的核心机制
进入 Plan Mode 后，Agent 只能读文件、跑只读搜索、用 AskUserQuestion 与用户澄清，不能写文件、不能跑会改变状态的 shell 命令。这一硬约束让”理解”和”修改”分成两个阶段：先在 Plan Mode 内把方案打磨到可评审，再切回默认或 acceptEdits 模式执行。Plan Mode 本身不额外消耗 token，但因多一轮探索与计划，前置阶段的 token 总量会增加。
激活方式有四种，按需选择：
| 方式 | 命令 | 场景 |
|---|---|---|
| 切换权限模式 | Shift+Tab 循环切到 plan |
交互式会话中临时切到只读 |
| 启动即进入 | claude --permission-mode plan |
一上来就要先看清现状 |
| 单轮前缀 | 提示词前加 /plan |
只对这一轮进入只读 |
| 设为默认 | settings.json 中 defaultMode: "plan" |
项目级强制 explore-first |
按 Ctrl+G 可以把生成的方案直接拉进系统编辑器做人工修订，修订完切回默认模式让 Agent 执行。
二、Explore → Plan → Code → Commit 四阶段
社区广泛采用的四阶段工作流，每一步都对应不同模式与产出：
- Explore（Plan Mode）：让 Agent 读相关代码、梳理依赖、回答”现状是什么”；
- Plan（Plan Mode）：在只读约束下产出”要改哪些文件、测试怎么写、风险点是什么”的步骤清单；
- Code（默认 / acceptEdits）：审完方案后切回可写模式，让 Agent 照计划执行；
- Commit（默认）：按逻辑变更分批提交，每个 commit 配描述性信息并可附 PR。
“先想清楚再动手”的价值在于：改一行就完成的 typo 修复可以跳过，但跨文件、跨模块的重构如果上来就写代码，几乎一定会因为缺少全局视角而返工。Plan Mode 的核心作用是把返工成本前置到方案评审阶段。
三、Plan Mode 适用的典型场景
| 场景 | 启用 Plan Mode 的理由 |
|---|---|
| 跨多文件改动 | 防止 Agent 漏掉共享工具、重复造轮子 |
| 不熟悉代码库 | 避免”自信地错”——写得通但不符合既有架构 |
| 多种技术方案并存 | 如 WebSocket vs SSE、单体 vs 微服务，让 Agent 把选项摆出来再选 |
| 架构评审 | 把 Agent 当作”会读代码的架构师”，给出可被讨论的方案 |
| 多人协作前的方案对齐 | 方案先评审再执行，减少返工与争议 |
| Bug 诊断 | 在不修改线上状态的前提下追踪调用链，定位可疑点 |
| 安全审计 | 只读扫描漏洞、识别可疑依赖，不触发任何写动作 |
当一个改动可以用一句话概括 diff 内容时，Plan Mode 反而是负担——多一轮探索与计划带来的 token 与时间开销，不值得为一句”加一行日志”付出。
四、何时应当跳过
判断”跳过”有一条经验法则：如果改动可以在一句话内写完 diff，就不要拉 Plan Mode。明确可跳过的典型场景包括：
- 单文件、目标明确的修改：给某行加
null判断、变量改名、修一个简单的 log 字符串； - 一句话能说清的 Bug 修复：定位与补丁路径都已确定；
- 探索性提问：用户只想知道”这块代码在做什么”，不需要 Agent 给出实施计划；
- 时间紧、改动小：Plan Mode 的前置 token 投入在紧迫任务里得不偿失。
跳过 Plan Mode 不是”偷懒”，而是为”低成本改动”避免重型流程的反模式。
五、Plan Mode 与 Agent Teams 的组合
在大型任务里，Plan Mode 还能与 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 联动：团队负责人可以要求所有队友在写代码前先以只读模式起草方案，负责人审完再放行。这一模式适合并行代码评审（安全 / 性能 / 测试三个队友各出一份只读方案）、新模块多 owner 协作、竞争假设调试等场景，能在多 Agent 形态下继续保留”先想后做”的纪律。
六、评审方案时的清单
拿到 Plan Mode 生成的方案后，建议按以下清单逐条核对，再决定是否切回默认模式执行：
- Agent 是否定位到正确的目标文件，是否漏看关键依赖；
- 方案是否对齐既有代码风格、复用既有工具与测试基线；
- 是否超出任务范围，做了未经授权的”顺手优化”；
- 边界条件与错误处理是否覆盖，测试设计是否到位；
- 实施顺序是否合理，能否按步骤回滚。
清单通过再切模式，能最大限度避免”方案看着没问题，落地后翻车”。
下面这段 settings.json 把 Plan Mode 设为项目级默认，对应”先想后做”的工程化习惯：
// ~/.claude/settings.json
{
"permissions": {
"defaultMode": "plan"
},
"plans": {
"plansDirectory": "~/.claude/plans",
"showClearContextOnPlanAccept": true,
"useAutoModeDuringPlan": true
}
}启动 Claude Code 后，状态栏会出现”⏸ plan mode”标识；按 Ctrl+G 可以把生成的方案直接拉进系统编辑器做人工修订。配合 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 还能让团队负责人在多 Agent 形态下要求队友先出只读方案再放行。
常见问题（FAQ）
Q1：Plan Mode 会比默认模式多花 token 吗？
Plan Mode 本身不额外计费，但因多一轮探索与计划，前置 token 总量会增加。
Q2：可以在 Plan Mode 内直接改文件吗？
不行；Plan Mode 写文件与变更命令都会被运行时拒绝。
Q3：什么场景最不该用 Plan Mode？
单文件、可一句话说清 diff 的小改动；此时跳过 Plan 反而更高效。
