深入研究

Claude Code 的 Plan Mode 在架构里处于什么位置

Plan Mode 不是一个普通“模式切换按钮”

很多人会把 Plan Mode 理解成：“先写计划，不直接写代码”的产品交互。
但从源码看，它远不只是一个 UI 状态，而是贯穿：

工具系统
权限系统
会话状态
审批流

的一套架构能力。

先看它在工具层的存在方式

在 tools.ts 里，Plan Mode 不是神秘隐藏能力，而是明确的工具：

export function getAllBaseTools(): Tools {
  return [
    ...
    ExitPlanModeV2Tool,
    ...
    EnterPlanModeTool,
    ...
  ]
}

这说明 Plan Mode 的进入和退出，都是系统正式建模过的操作，而不是临时插进去的布尔开关。

先看整体关系图

加载图表中...

`ExitPlanModeV2Tool` 很能说明它的真正定位

来看关键定义：

export const ExitPlanModeV2Tool: Tool<InputSchema, Output> = buildTool({
  name: EXIT_PLAN_MODE_V2_TOOL_NAME,
  searchHint: 'present plan for approval and start coding (plan mode only)',
  shouldDefer: true,
  isReadOnly() {
    return false
  },
  requiresUserInteraction() {
    if (isTeammate()) {
      return false
    }
    return true
  },
})

这段代码非常重要，因为它说明：

退出 Plan Mode 是一个正式工具调用
它默认要求用户交互
在 teammate 场景下行为又不同

也就是说，Plan Mode 并不是一个“提示词建议”，而是系统级审批节点。

为什么它和权限系统绑得这么紧

再看它的权限检查逻辑：

async checkPermissions(input, context) {
  if (isTeammate()) {
    return {
      behavior: 'allow' as const,
      updatedInput: input,
    }
  }

  return {
    behavior: 'ask' as const,
    message: 'Exit plan mode?',
    updatedInput: input,
  }
}

这段代码说明，Plan Mode 的退出并不是模型自己说了算。
它是一个需要系统权限流承认的动作。

状态层也为它预留了语义

在权限上下文中还能看到 prePlanMode 这样的字段，说明系统会记住进入 Plan Mode 前的权限状态，以便退出后恢复。

这意味着 Plan Mode 不是孤立状态，而是对整个权限语义有影响。

加载图表中...

为什么 Claude Code 要把 Plan Mode 做到这个程度

因为工程任务里最危险的，不是“模型不会写”，而是“模型太快开始写”。
Plan Mode 本质上是在系统层引入一个暂停点：

先整理方案
再给人审核
审核通过后再进入执行

这对高风险修改、团队协作、多 Agent 场景都非常重要。

它在多 Agent 场景里更关键

源码里还能看到 teammate / approval / mailbox 相关逻辑，这说明：

对主线程来说，Plan Mode 是用户审批点
对子 Agent 来说，Plan Mode 可能变成团队领导审批点

也就是说，Plan Mode 是协作工作流的一部分，不只是单用户交互功能。

小结

从架构上说，Plan Mode 更准确的定位是：

Claude Code 在自动化执行链路中人为插入的一个“计划审批闸门”。

它通过工具、权限和状态系统协同工作，确保“从规划到实现”的切换是可控的。