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

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

给 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 做了一个和 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 官方源码项目进行架构分析，聚焦设计思想而非代码实现。