Plan 模式不是一个"暂停键"——它是 Claude 内部的一种受限运行态: 只能读、不能写,只能想、不能动。两个工具切换状态、用户审批闭环—— 这是 Anthropic 设计上对"自动化"与"安全"之间的精确妥协。

状态机视角

两个工具的契约

为什么需要"受限态"

# 反例 — 没有 Plan 模式
> 把 auth 模块拆成 controller + service + repository 三层
# Claude 立刻开 Edit/Write 改 12 个文件,
# 改到一半发现 service 层应该按 domain 拆,
# 此时 12 个文件已经是一个尴尬的中间态——回滚成本高

# 正例 — 进入 Plan 模式
> 进入 plan 模式, 把 auth 模块拆成 controller/service/repository 三层
# Claude 读完 auth/ 所有文件、grep 调用关系,
# 写一份 plan: "建议按 domain 切, 而不是按层切, 因为..."
# 你 review → 调整方向 → 同意 → 才真正动 0 个文件以外的代码

三种触发方式

并不是每个任务都需要 plan——给三行字符串改个变量名也走 plan 就是过度仪式。 下面这张矩阵告诉你什么时候必须 plan、什么时候可跳过,以及边界场景的判断口诀。

四象限

六条硬触发条件

三种"别走 plan"的场景

一个能被 review 的 plan 长什么样?——下面这套五要素模板覆盖 95% 场景。 关键不是"全",而是结构稳定:reviewer 一眼就知道哪里看目标、哪里看变更、哪里看风险。

结构示意

完整 plan 样例

## PLAN · auth-refactor

### 01 目标 + 范围
把 auth 模块按 domain (user / session / token) 拆分;
**不动**: db schema, public API, 错误码契约。

### 02 前置事实
- src/auth/index.ts 共 642 行, 含 31 个 export
- 调用方共 4 处: app.ts / routes/api.ts / middleware/auth.ts / tests/
- public API 在 README 第 89 行声明,需保持向后兼容

### 03 变更清单
**新建**
- src/auth/user/{index,types,service}.ts      (~ 200 行)
- src/auth/session/{index,types,service}.ts   (~ 150 行)
- src/auth/token/{index,types,service}.ts     (~ 180 行)

**修改**
- src/auth/index.ts → 改为 re-export 聚合, 保持外部 API
- 4 处调用方: 不动 (因为 re-export 兼容)

**删除**
- 无

### 04 风险 + 回滚
- 风险 R1: token 模块依赖 session 的循环引用 → 用 type-only import 拆解
- 风险 R2: 单测 import 路径硬编码内部细节 → 不动调用方但测试可能失败
- 回滚: `git revert` 单 commit 即可, 无 db 变更

### 05 验证 + 测试
- 全部 unit test 通过: `pnpm test src/auth`
- e2e auth flow 跑通: `pnpm test:e2e auth.spec.ts`
- 启动 dev server 手动验证登录: 1 次成功 + 1 次错密码
- bundle size 不超过原 + 5%: `pnpm analyze`

让 Claude 按模板出 plan

# 写进 CLAUDE.md, 全局生效
## Plan 模式规范

进入 plan 模式时, plan 必须按下列五要素结构:
1. 目标 + 范围 (做什么 / 不做什么)
2. 前置事实 (源码读到的关键数据)
3. 变更清单 (文件级, 新增/修改/删除/移动)
4. 风险 + 回滚 (已知风险 + 回滚路径)
5. 验证 + 测试 (完成的定义 + 复现命令)

**禁止**: plan 阶段直接写函数实现, 那是执行阶段的事。

Plan 模式单用已经很有价值——但和前面学过的子代理 (Day 14)、 Hooks (Day 10)、CLAUDE.md (Day 03) 组合起来, 能搭出一张"动手前必先规划"的物理护栏。

三种联动模式

联动 A · Plan 子代理

# 主代理在 ACT 态, 但外包"规划"工作给 Plan 子代理
# 子代理只读, 输出 plan 文本回主代理

> 我要把 src/payment 拆成独立 service.
  先调用 Plan 子代理写一份拆分方案,我 review 后你再执行。

# 主代理内部会触发:
# 1) Agent(subagent_type="Plan", prompt="拆分 src/payment 为独立 service")
# 2) 子代理只读地调研, 返回 5 要素 plan
# 3) 主代理把 plan 呈给你审批
# 4) 你同意后, 主代理按 plan 在 ACT 态执行

联动 B · PreToolUse Hook 物理阻断

# .claude/hooks/require-plan.sh
# 当 Claude 在 ACT 态准备 Edit/Write 时, 检查是否经过 plan

#!/usr/bin/env bash
tool="$1"   # 钩子第一个参数: 工具名
file="$2"   # 第二个: 目标文件

if [[ "$tool" == "Edit" || "$tool" == "Write" ]]; then
  # 仅对特定敏感目录拦截
  if [[ "$file" == src/auth/* || "$file" == migrations/* ]]; then
    if [[ ! -f .claude/last-plan-approved ]]; then
      echo "BLOCK: 此目录需先进入 plan 模式并获用户审批"
      exit 2   # 非零退出 → Claude 收到阻断信号
    fi
  fi
fi
exit 0

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": ".claude/hooks/require-plan.sh"
      }
    ]
  }
}

联动 C · CLAUDE.md 沉淀触发规则

# CLAUDE.md 片段 —— 项目级 plan 偏好

## Plan 模式触发规则

下列任一情况, **必须先进入 plan 模式**:
- 修改 src/auth/, src/payment/, migrations/ 三个目录的任何文件
- 一次任务涉及 ≥ 3 个文件
- 任务描述含"重构 / 迁移 / 升级 / 拆分"等关键词
- 需要写 db migration / 修改公开 API

下列情况 **可直接 ACT**:
- 改 README / 注释 / 测试用例
- 单文件 bugfix 且范围 < 20 行
- typo / lint 修正

## Plan 文件五要素 # 接前面的模板要求

每次 ExitPlanMode 时, plan 必须包含:
01 目标 + 范围 ｜ 02 前置事实 ｜ 03 变更清单 ｜
04 风险 + 回滚 ｜ 05 验证 + 测试

缺任意一项, plan 视为不完整, 应继续在 plan 模式补全。

三者组合的安全等级

Plan 模式用错了, 反而比不用更慢——它需要纪律。 下面四类反模式是社区里反复出现的"plan 走过场"现象。

四种典型反模式

三条纪律

把 plan 变成 PR 描述

# Plan 文档与 PR description 高度同构 —— 可以直接复用

> 把刚才审批通过的那份 plan 整理成 PR 描述:
  - 把"前置事实"改成"背景"
  - "变更清单"改成"This PR"
  - 风险/验证保留原样
  - 末尾加 Test plan checkbox

# 结果: 评审者拿到的 PR description 就是被你审批过的 plan,
# 评审节奏: 看 plan + 抽查代码 << 看代码 + 反推意图

四个递进的实验——从体会 plan 模式的"约束感"开始, 到把整套护栏装到自己的项目里。 预计 50 分钟, 每个 Lab 完成后用 /status 看模式徽章状态。

1. EnterPlanMode 与 ExitPlanMode 的契约分别是什么? 为什么 Plan 模式需要"受限态"而不仅仅是"先想后写"的提示?
2. 用决策矩阵的四象限说出"必须 plan / 建议 plan / 先 Explore / 直接 ACT"各自对应什么场景, 各举一个例子。
3. plan 文件的五要素是什么? 缺哪一项最致命, 为什么?
4. Plan 与 Subagent / PreToolUse Hook / CLAUDE.md 各自能解决什么问题? 怎样的组合算"完整安全网"?
5. 说出至少三种 plan 反模式, 每种给出对应的防御措施。