05d - Plan Mode 与 Act Mode

本文是《AI Agent 实战手册》第 5 章第 4 节。 上一节：Agentic Loop 与 Subagent | 下一节：高级 CLI 技巧

概述

Claude Code 提供了三种操作模式——Plan Mode（规划模式）、Normal Mode（普通模式） 和 Auto-Accept Mode（自动接受模式）——它们构成了一个从”只读思考”到”全自动执行”的安全性光谱。掌握这三种模式的切换时机和组合工作流，是高效使用 Claude Code 的关键分水岭。本节深入对比各模式的机制、决策标准、使用场景，并提供经过验证的组合工作流模式。

1. 三种模式全景对比

1.1 模式切换机制

Claude Code 使用 Shift+Tab 键在三种模式间循环切换：

Shift+Tab 循环：

  Normal Mode（默认）
       ↓ Shift+Tab
  Auto-Accept Edit On
       ↓ Shift+Tab
  Plan Mode On
       ↓ Shift+Tab
  Normal Mode（回到起点）

也可以使用 /plan 命令（v2.1.0+）直接进入 Plan Mode。

1.2 核心对比表

1.3 安全性光谱图

安全性高 ◄─────────────────────────────────────► 自动化高

  Plan Mode          Normal Mode         Auto-Accept Mode
  ┌──────────┐      ┌──────────┐        ┌──────────┐
  │ 只读分析  │      │ 逐步确认  │        │ 全自动   │
  │ 零风险    │      │ 可控风险  │        │ 需信任   │
  │ 纯思考    │  →   │ 人机协作  │   →    │ 自主执行 │
  └──────────┘      └──────────┘        └──────────┘
  
  "架构师模式"       "结对编程模式"       "自动驾驶模式"

2. Plan Mode 深度解析

2.1 工作原理

Plan Mode 将 Claude Code 置于只读状态，限制其只能使用分析和研究类工具，禁止一切修改操作。这种约束是刻意设计的——强制 Claude 在动手之前充分探索和思考。

Plan Mode 可用工具：

Plan Mode 禁用工具：

2.2 Plan Mode 的输出特征

与普通模式下格式不一致的建议不同，Plan Mode 强制 Claude 输出结构化、可预测的分析结果：

典型 Plan Mode 输出结构：

1. 问题分析
   - 当前代码结构理解
   - 需要修改的文件列表
   - 潜在的依赖关系

2. 方案选项（通常 2-3 个）
   - 方案 A：[描述] — 优点/缺点/复杂度
   - 方案 B：[描述] — 优点/缺点/复杂度

3. 推荐方案
   - 具体实施步骤
   - 预计影响范围
   - 需要注意的边界情况

2.3 何时使用 Plan Mode

✅ 必须使用的场景

❌ 可以跳过的场景

工具推荐

3. Normal Mode 与 Auto-Accept Mode

3.1 Normal Mode：人机协作的默认模式

Normal Mode 是 Claude Code 的默认工作状态。在此模式下，Claude 可以使用所有工具，但每次执行修改操作前都会暂停并请求用户确认：

Claude: 我需要修改 src/auth.ts 来添加 JWT 验证中间件。
        [允许编辑 src/auth.ts？] (y/n)

你: y

Claude: 修改完成。现在需要运行 npm test 来验证。
        [允许执行 bash 命令？] (y/n)

这种”逐步确认”机制提供了良好的安全性和可控性，适合日常开发中的大多数场景。

3.2 Auto-Accept Mode：全自动执行模式

Auto-Accept Mode 位于安全光谱的另一端——消除所有确认提示，让 Claude 自主执行所有操作。激活后，UI 显示 “auto-accept edit on”，Claude 会立即执行文件编辑、命令运行等操作，不会暂停等待确认。

激活方式：按 Shift+Tab 一次（从 Normal Mode 切换）

适用场景：

安全配置：

可以通过 allowedTools 配置精细控制 Auto-Accept 模式下允许自动执行的工具：

// .claude/settings.json
{
  "permissions": {
    "allowedTools": [
      "Read", "Write", "Edit", "MultiEdit",
      "Glob", "Grep", "LS"
    ]
    // Bash 不在列表中 = 仍需确认
  }
}

3.3 模式选择决策树

4. Opus Plan Mode：高级混合模式

4.1 什么是 Opus Plan Mode

Opus Plan Mode 是 Claude Code 的高级规划模式，随 Opus 4.6 发布。核心理念是用最强模型规划，用高效模型执行——Opus 负责深度分析和方案设计（利用其 1M 上下文窗口），Sonnet 4.6 负责实际代码编写。

操作步骤

步骤 1：启用 Opus Plan Mode

在 Claude Code 中使用 /model 命令，选择选项 4：

/model
# 选择: "Use Opus in plan mode, Sonnet 4.6 otherwise"

步骤 2：描述任务

正常输入你的需求。Opus 会先进入交互式规划阶段：

你: 我需要为这个 SaaS 应用添加多租户支持

Opus: 在开始规划之前，我有几个问题：
1. 你倾向于哪种多租户隔离策略？（共享数据库/独立 Schema/独立数据库）
2. 现有的认证系统是什么？（JWT/Session/OAuth）
3. 是否需要租户级别的自定义配置？

步骤 3：Opus 生成 plan.md

回答澄清问题后，Opus 生成结构化的计划文件：

# 多租户支持实施计划
 
## 架构决策
- 隔离策略：共享数据库 + 行级隔离（RLS）
- 租户标识：JWT claims 中的 tenant_id
 
## 任务分解
1. [ ] 数据库 Schema 变更（添加 tenant_id 列）
2. [ ] 中间件层（租户解析和注入）
3. [ ] API 层修改（所有查询添加租户过滤）
4. [ ] 测试（多租户隔离验证）
 
## 依赖关系
- 任务 2 依赖任务 1
- 任务 3 依赖任务 2
- 任务 4 可与任务 3 并行

步骤 4：审查并修改计划

你可以直接编辑 plan.md 文件，调整任务顺序、添加约束或修改方案。

步骤 5：批准执行

确认计划后，Claude 自动切换到 Sonnet 4.6 按计划逐步执行。

4.2 Opus Plan Mode vs 标准 Plan Mode

5. Auto Plan Mode：自动化规划保护

5.1 概念

Auto Plan Mode 是一种通过系统提示实现的防御性机制——让 Claude 在执行任何修改操作前自动进入规划流程，无需手动按 Shift+Tab。这对于新手用户或在不熟悉的代码库中工作时特别有价值。

5.2 与手动 Plan Mode 的区别

操作步骤

步骤 1：创建系统提示文件

# 创建 auto-plan-mode.txt
cat > auto-plan-mode.txt << 'EOF'
CRITICAL WORKFLOW REQUIREMENT
MANDATORY PLANNING STEP: Before executing ANY tool (Read, Write, Edit, Bash, 
Grep, Glob, WebSearch, etc.), you MUST:
1. FIRST: Use exit_plan_mode tool to present your plan
2. WAIT: For explicit user approval before proceeding
3. ONLY THEN: Execute the planned actions
 
ZERO EXCEPTIONS: This applies to EVERY INDIVIDUAL USER REQUEST involving 
tool usage, regardless of complexity, tool type, or user urgency.
 
CRITICAL: APPROVAL DOES NOT CARRY OVER BETWEEN USER INSTRUCTIONS
- Each new user message requiring tools = new planning step required
- Previous approvals are invalid for new requests
 
WORKFLOW FOR EACH USER REQUEST: Plan → User Approval → Execute
EOF

步骤 2：启动 Claude Code 并注入

claude --append-system-prompt "$(cat auto-plan-mode.txt)"

步骤 3：正常使用

此后每次你给出指令，Claude 都会先展示计划并等待你的批准，然后才执行。

6. 组合工作流模式

6.1 经典四阶段工作流：Explore → Plan → Code → Test

这是 Claude Code 社区公认的最佳实践工作流，将三种模式有机组合：

6.2 Plan-Critique-Execute-Archive 工作流

这是一种更严谨的工作流，在计划和执行之间增加了批评审查环节：

阶段 1：Plan（Plan Mode）
  → Claude 生成实施计划

阶段 2：Critique（Plan Mode）
  → 你说："请以资深工程师的视角审查这个计划，找出潜在问题"
  → Claude 自我批评，指出计划中的薄弱点
  → 迭代修改计划直到满意

阶段 3：Execute（Normal / Auto-Accept Mode）
  → 退出 Plan Mode，按最终计划执行

阶段 4：Archive
  → 将计划和决策记录到项目文档中

Anthropic 内部团队也使用类似方法——一位工程师会让 Claude 写计划，然后启动第二个 Claude 会话”以 Staff Engineer 身份审查这个计划”。

6.3 “15 分钟瀑布”规划法

将传统瀑布模型压缩到 15 分钟内完成，利用 Plan Mode 快速走完”需求→设计→任务分解”：

分钟 0-3：需求澄清（Plan Mode）
  "我要实现 [功能]，请分析需求并提出澄清问题"

分钟 3-8：方案设计（Plan Mode）
  "基于以上需求，请设计实施方案，列出所有需要修改的文件"

分钟 8-12：任务分解（Plan Mode）
  "请将方案拆分为可独立执行的微任务，每个任务不超过 50 行代码变更"

分钟 12-15：审查确认（Plan Mode）
  审查计划，调整优先级，确认执行顺序

之后：逐个执行微任务（Normal / Auto-Accept Mode）

6.4 CLAUDE.md 中的模式配置

你可以在 CLAUDE.md 中预设模式偏好，让 Claude 在特定场景下自动采用合适的工作模式：

# CLAUDE.md 示例片段
 
## 工作流规则
 
- 对于涉及数据库 Schema 变更的任务，必须先进入 Plan Mode 分析影响
- 对于新增 API 端点，先用 Plan Mode 设计接口，确认后再实现
- 对于 bug 修复，如果影响范围明确（单文件），可以直接在 Normal Mode 修复
- 执行重构任务时，先在 Plan Mode 中列出所有受影响的文件和测试

提示词模板

Plan Mode 规划模板

[Plan Mode 下使用]

请分析以下需求并制定实施计划：

需求：[功能描述]

请包含：
1. 需要修改/创建的文件列表
2. 每个文件的具体变更内容概述
3. 变更之间的依赖关系和执行顺序
4. 潜在的风险点和边界情况
5. 建议的测试策略

Plan Mode 架构审查模板

[Plan Mode 下使用]

请以资深架构师的视角审查当前项目结构：

1. 分析 [目录] 的模块划分是否合理
2. 检查是否存在循环依赖
3. 评估当前架构对 [未来需求] 的扩展性
4. 列出你发现的技术债务
5. 提出改进建议，按优先级排序

Plan-to-Execute 切换模板

[从 Plan Mode 切换到执行时使用]

我已审查并批准上述计划。请按以下顺序执行：
1. 先完成 [最关键的变更]
2. 每完成一个文件后运行相关测试
3. 如果测试失败，先修复再继续下一个文件
4. 所有变更完成后运行完整测试套件

实战案例：用 Plan → Execute 工作流添加支付功能

场景

你需要为一个 SaaS 应用添加 Stripe 订阅支付功能，涉及后端 API、数据库变更、前端页面和 Webhook 处理。

操作流程

第一步：进入 Plan Mode 探索

按 Shift+Tab 两次进入 Plan Mode：

你: 我需要添加 Stripe 订阅支付。用户可以从定价页面订阅 Pro 计划。
    请先分析现有代码结构，然后制定实施计划。

Claude 在 Plan Mode 下探索代码库（只读），输出：

Claude 的 Plan Mode 输出：

## 实施计划：Stripe 订阅支付

### 现有代码分析
- 认证系统：NextAuth.js + Prisma（src/lib/auth.ts）
- 数据库：PostgreSQL + Prisma ORM
- 现有 User 模型：id, email, name, image
- API 路由模式：App Router（src/app/api/）

### 方案
1. 安装 stripe 包
2. 创建 Subscription 模型（独立于 User，通过 userId 关联）
3. 创建 /app/api/stripe/checkout/route.ts — Checkout Session
4. 创建 /app/api/stripe/webhook/route.ts — Webhook 处理
5. 更新 prisma/schema.prisma — 添加 Subscription 模型
6. 创建 /app/pricing/page.tsx — 定价页面
7. 创建中间件检查订阅状态

### 风险点
- Webhook 签名验证必须正确配置
- 需要处理订阅过期和续费失败的边界情况

第二步：在 Plan Mode 中迭代

你: 计划看起来不错，但有两个调整：
    1. 请使用 Stripe Customer Portal 管理订阅，不要自建管理页面
    2. 添加一个 Free Trial 期（14 天）

Claude: 好的，更新计划：
    - 步骤 6 改为：集成 Stripe Customer Portal（减少前端工作量）
    - 步骤 3 更新：Checkout Session 添加 trial_period_days: 14
    - 新增步骤 8：添加 Trial 到期提醒逻辑

第三步：批准并切换到执行模式

按 Shift+Tab 退出 Plan Mode，进入 Auto-Accept Mode：

你: 计划已确认。请按顺序执行，每完成一个步骤后运行测试。

Claude 开始自动执行：安装依赖 → 修改 Schema → 创建 API 路由 → 创建前端页面 → 运行测试。

第四步：回到 Normal Mode 验证

执行完成后，切换回 Normal Mode 进行最终验证：

你: 请运行完整测试套件，并手动验证 Webhook 端点的签名验证逻辑。

案例分析

这个案例展示了模式组合的核心价值：

1. Plan Mode 的 30 秒审查避免了昂贵的返工：最初 Claude 打算将订阅字段直接加到 User 模型上，通过 Plan Mode 审查发现后及时调整为独立的 Subscription 模型，避免了后续的 Schema 重构
2. Plan Mode 中的迭代成本极低：修改计划只消耗少量 token（纯文本），而修改已写好的代码消耗大量 token 且容易引入 bug
3. Auto-Accept Mode 加速了执行阶段：计划确认后，7 个步骤的执行无需逐步确认，开发者可以去喝杯咖啡
4. Normal Mode 的最终验证提供了安全网：关键的安全逻辑（Webhook 签名验证）在人工监督下验证

避坑指南

❌ 常见错误

1. 跳过 Plan Mode 直接开始复杂任务

   • 问题：Claude 在没有全局视角的情况下开始编码，容易产生与现有架构冲突的代码，或遗漏关键依赖。研究表明，跳过规划的开发者花在调试上的时间反而更多
   • 正确做法：任何涉及 3 个以上文件的任务，先用 Plan Mode 分析

2. 在 Plan Mode 中给出过于模糊的需求

   • 问题：模糊的输入导致模糊的计划，审查时难以判断方案是否合理
   • 正确做法：提供具体约束——“使用现有的 Supabase 认证，不要引入新的认证系统”、“遵循 /api/users 端点的相同模式”

3. 长时间使用 Auto-Accept Mode 而不检查

   • 问题：Auto-Accept 模式下 Claude 可能在错误方向上走很远，产生大量需要回滚的代码
   • 正确做法：每 10-15 分钟检查一次进度；对于关键路径（安全、数据库迁移），切回 Normal Mode

4. 不在 CLAUDE.md 中记录模式偏好

   • 问题：每次新会话都需要重新沟通工作流偏好
   • 正确做法：在 CLAUDE.md 中明确写出”数据库变更必须先 Plan”等规则

5. Plan Mode 中过度规划

   • 问题：花 30 分钟在 Plan Mode 中完善一个只需要 5 分钟实现的功能
   • 正确做法：Plan Mode 的目标是”足够好的计划”，不是”完美的计划”。结构性决策确认后就可以开始执行

6. 忘记 Plan Mode 的存在，用 prompt 模拟

   • 问题：在 Normal Mode 中写”不要修改代码，只给建议”，Claude 可能不遵守，仍然开始编辑文件
   • 正确做法：使用真正的 Plan Mode（Shift+Tab ×2），它在工具层面禁止修改操作，比 prompt 指令可靠得多

✅ 最佳实践

1. 养成”先 Plan 后 Code”的肌肉记忆——Shift+Tab ×2 应该成为开始新任务的第一个动作
2. 在 Plan Mode 中主动要求 Claude 分析权衡（“这个方案的 trade-off 是什么？”）
3. 利用 Plan Mode 的速度优势——只读分析比执行快得多，且消耗更少 token
4. 对于大型项目，考虑使用 Opus Plan Mode 获得 1M 上下文的规划能力
5. 在团队中建立 Plan Mode 规范——哪些类型的变更必须先规划
6. 善用 Auto Plan Mode 为新成员提供安全网
7. 将 Plan Mode 产出的计划保存为项目文档（ADR、设计决策记录）

相关资源与延伸阅读

工具与参考

• ClaudeLog — Plan Mode  — Plan Mode 的详细功能解析和使用场景
• ClaudeLog — Auto Plan Mode  — 自动 Plan Mode 的配置和使用指南
• Neon Claude Code Cheatsheet  — Neon 团队的 Claude Code 速查表，包含 Plan Mode 工作流

学习资源

• Plan, Critique, Execute, Archive — Ghita.org  — Plan-Critique-Execute 工作流的深度实践
• Stop Speedrunning Claude Code — paddo.dev  — 为什么应该先 Plan 再 Act 的经验分享
• 10 Tips from Inside the Claude Code Team — paddo.dev  — Claude Code 团队内部的使用技巧

工作流模板

• Awesome Claude Code — GitHub  — 包含 Plan Mode 工作流模板的社区资源集合
• Developer Toolkit — Feature Planning  — 使用 Plan Mode 进行功能设计的教程

社区

• r/ClaudeAI  — Claude 用户社区，有 Plan Mode 使用策略的讨论
• ClaudeLog  — Claude Code 功能详解站点，持续追踪 Plan Mode 的更新

参考来源

• Claude Code Plan Mode Guide (2026) — Manast （2026-02）
• Plan Mode — ClaudeLog （2025-12，持续更新）
• Auto Plan Mode — ClaudeLog （2025-12）
• Auto-Accept Permissions — ClaudeLog （2025-12）
• Claude Code Planning Mode — ClaudeFast （2026-02）
• Plan Mode in Claude Code: When to Use It (and When Not To) — Claude AI Chat （2025-11）
• Plan Mode Is Now Mandatory — Paddo.dev （2025-12）
• Stop Speedrunning Claude Code — Paddo.dev （2025-12）
• 10 Tips from Inside the Claude Code Team — Paddo.dev （2026-02）
• Plan, Critique, Execute, Archive — Ghita.org （2026-02）
• Our Claude Code Cheatsheet — Neon （2025-10）
• Deep Reasoning for Feature Design — Developer Toolkit （2025-12）

📖 返回 总览与导航 | 上一节：Agentic Loop 与 Subagent | 下一节：高级 CLI 技巧