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

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

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

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

的一套架构能力。

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

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

1
2
3
4
5
6
7
8
9
export function getAllBaseTools(): Tools {
  return [
    ...
    ExitPlanModeV2Tool,
    ...
    EnterPlanModeTool,
    ...
  ]
}

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

先看整体关系图

ExitPlanModeV2Tool 很能说明它的真正定位

来看关键定义：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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 并不是一个“提示词建议”，而是系统级审批节点。

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

再看它的权限检查逻辑：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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 在自动化执行链路中人为插入的一个“计划审批闸门”。

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