# Plan Mode 与设计先行：让 AI 先想再做


<!-- more -->


给建筑师一块地，他不会立刻开始砌砖。他会先画图、计算承重、考虑采光、规划管线。等蓝图确认了，施工队才进场。

给 AI 编程助手一个需求，它默认会立刻开始改代码。不是因为它不懂"设计先行"，而是因为**它的循环机制鼓励行动**——Think-Act-Observe 循环里，"Act"是核心能力。模型被训练成"有帮助的"，"有帮助"在编程场景里通常意味着"动手改"。

Plan Mode 的存在就是为了打断这种冲动。

## Plan Mode 是什么

Plan Mode 是 Claude Code 的一种权限模式。开启后，Agent 只能读不能写——它可以查看文件、搜索代码、运行只读命令，但不能修改文件、不能执行有副作用的操作。

表面上，这只是权限系统的另一个级别（我们在第 4 篇聊过 5 级权限模型）。但 Plan Mode 的意义不止于权限控制，它是一种**工作流阶段的强制分离**。

Plan Mode 回答了一个被忽略的问题：**AI 编程助手在"理解问题"和"解决问题"之间需要一个明确的边界。**

## 为什么"先想再做"对 AI 特别重要

人类程序员天然有"先想再做"的习惯——至少在经验丰富的程序员身上如此。接到需求后，你会先在脑子里过一遍：涉及哪些文件、改动范围多大、有没有边界情况、测试怎么写。

AI 没有这个习惯。不是它不能想，而是它没有"想"和"做"的分离冲动。对模型来说，思考是文本，行动也是文本——两者在输出层面没有本质区别。如果没有外部约束（Plan Mode），模型倾向于尽快从"思考"跳到"行动"，因为"行动"（生成代码）是它的核心训练目标。

Plan Mode 通过技术手段强制了一个认知分离：

**Plan 阶段（只读）**：
- 阅读现有代码，理解架构
- 识别需要修改的文件
- 分析依赖关系和潜在影响
- 制定修改计划
- 向用户展示方案，等待确认

**Execute 阶段（读写）**：
- 按照确认的方案执行修改
- 编写或更新测试
- 运行验证

两个阶段之间有一个明确的**人工确认点**。用户看到了 AI 的计划，可以提出修改意见、调整方向、或者完全推翻重来。这个确认点在"想"和"做"之间竖起了一道闸门。

## 读-想-写的分离

Plan Mode 的本质是**读-想-写的三阶段分离**：

**读（Read）**——Agent 扫描项目，收集信息。读文件、看依赖、查测试、分析结构。这个阶段产出的是"事实"。

**想（Think）**——Agent 基于收集的事实制定计划。分析影响范围、设计修改方案、评估风险。这个阶段产出的是"决策"。

**写（Write）**——Agent 执行计划，修改代码。这个阶段产出的是"变更"。

三个阶段的输入输出各不相同：
- 读的输入是文件系统，输出是事实
- 想的输入是事实，输出是决策
- 写的输入是决策，输出是变更

分离的好处是**每个阶段可以独立审查和优化**。你可以检查"读"是否全面（有没有漏掉关键文件），检查"想"是否合理（方案是否正确），检查"写"是否准确（代码是否符合方案）。如果三个阶段混在一起，审查变得困难——你很难从一堆代码变更中逆向推断 AI 的思考过程。

## Plan Mode 的质量增益

Plan Mode 为什么能提高代码质量？因为它拦截了 AI 编程最常见的三类错误：

**理解错误。** AI 没搞清楚现有代码的逻辑就动手改，结果破坏了隐含的依赖关系。Plan Mode 强制 AI 先读再想，理解错误在"想"的阶段就能被发现。

**范围错误。** AI 只改了表面相关的文件，漏掉了间接依赖的文件。Plan Mode 的分析阶段要求 AI 列出所有受影响的文件，用户可以检查是否遗漏。

**方向错误。** AI 的理解和用户意图有偏差，但它已经改了一半代码才发现。Plan Mode 在改之前就让用户确认方向，偏差在零成本阶段被纠正。

这三类错误的共同特点是：**越早发现，成本越低。** 在 Plan 阶段纠正方向错误成本接近零（只消耗了 token），在 Write 阶段纠正需要回滚变更，在生产环境发现就可能是事故。

## Plan Mode 与多代理的关系

Plan Mode 和多代理架构（第 8 篇）有微妙的互补关系。

多代理架构里有一个专门的 Plan 角色——它接收 Explore 的发现，生成执行方案。Plan Mode 是一种权限状态——它限制 Agent 只能读不能写。

两者可以组合使用：在 Plan Mode 下启动一个 Plan 角色的子代理，让它做深度分析。Plan Mode 提供安全边界（确保不会意外修改），Plan 角色提供专业方法论（确保分析结构化）。

但两者也可以独立使用：Plan Mode 不需要多代理（单 Agent 在只读模式下也能规划），多代理不需要 Plan Mode（Explore 角色本身就是只读的，不需要额外的权限限制）。

## 什么时候不需要 Plan Mode

Plan Mode 不是银弹，它有成本——额外的 token 消耗、额外的等待时间、额外的交互步骤。不是所有任务都值得规划。

适合跳过 Plan Mode 的场景：
- **简单修改**——"把这个函数名从 foo 改成 bar"
- **局部修复**——"这个测试失败了，修一下"
- **增量补充**——"给这个组件加个加载状态"

需要 Plan Mode 的场景：
- **架构变更**——"把 Redux 迁移到 Zustand"
- **跨模块修改**——"重构错误处理机制"
- **需求不明确**——"帮我想想怎么加个用户权限系统"

判断标准是**改动范围和不确定性**。范围小、确定性高的任务不需要规划；范围大、不确定性高的任务必须规划。

## Plan Mode 的哲学

Plan Mode 背后有一条设计哲学：

**AI 编程助手最大的风险不是写不出代码，而是写出"方向错误"的代码。**

写不出代码，用户自己写就行。写出方向错误的代码，用户需要花更多时间发现、回滚、重新指导。方向错误的成本远大于不行动的成本。

Plan Mode 通过一个简单的设计决策——在行动前强制一个只读规划阶段——将方向错误的成本从"代码级别"降低到"文本级别"。规划是文本，改错方向只需要重新规划。行动是代码，改错方向需要回滚变更。

**让错误发生在便宜的地方，这是 Plan Mode 的核心价值。**

## 延伸阅读：BYF 为什么移除了 Plan Mode

[BYF](https://github.com/ByronFinn/byf) 做了一个和 Claude Code 相反的选择：**在 ADR 0008 中，BYF 主动移除了 Plan Mode。**

原因不是 Plan Mode 没有价值，而是在 BYF 的上下文最小化审查中，Plan Mode 被判定为"过早的抽象"：

- **Token 成本**：EnterPlanMode（~572t）+ ExitPlanMode（~853t）工具描述每次消耗约 1425 token。加上 PlanModeInjector 周期性的提醒（每次 300-800 字符），长期会话中这些开销累积明显。
- **TUI 复杂度**：CLI/TUI 层有 30+ 处引用（`/plan` 斜杠命令、快捷键、plan 卡片渲染、审批面板、footer badge）。
- **架构分布**：Plan Mode 触及 agent-core（状态机、权限策略、注入系统）、SDK（RPC 透传）、CLI（TUI 状态）、vis（wire record 渲染）和 wire records（`plan_mode.*` 事件类型）。
- **使用量**：用户可以通过自然语言"先做个计划"达到同样的效果，不需要特殊模式。

BYF 的结论是：**Plan Mode 强制了一个二元状态（规划 vs 执行），而代理应该流畅地交错探索和行动。** 移除 Plan Mode 后，BYF 节省了约 73 个代码文件、~1425 token 的工具定义开销，简化了用户的思维模型——用户不需要学习"什么时候该进入模式"。

这并不否定 Plan Mode 的价值。Claude Code 的 Plan Mode 和 BYF 的移除决策都是合理的——取决于你的用户群和设计哲学。Claude Code 选择给用户一个明确的"规划按钮"作为安全网，BYF 选择相信用户可以自然地用语言表达"先想想"。两种选择都有取舍，重要的是**有意识地在取舍之间做决策**。

## 下一篇

Phase 2 完成了。我们从上下文压缩、记忆系统、Skill、多代理、MCP、Plan Mode 一路拆解下来，看到了 AI Agent 的高级能力是如何构建的。

Phase 3 进入更宏观的视角。下一篇文章我们要做一个大胆的对比：**3000 行 vs 50 万行**——claude-code-from-scratch 的极简实现和 Claude Code 的真实源码之间，到底差了什么？从玩具到产品，架构深渊里藏着多少工程细节？

---

> 本系列基于 [Claude Code 官方源码](https://github.com/anthropics/claude-code)项目进行架构分析，聚焦设计思想而非代码实现。