Claude Code 计划模式与任务编排三件套实战

概述

本教程深入讲解 Claude Code 中用于"先想清楚再动手"的三个核心机制：计划模式（Plan Mode）、任务清单（TodoWrite） 与 结构化提问（AskUserQuestion）。它们共同构成了一个低返工、可审计的任务编排闭环——调研而不改、跟踪而不漏、澄清而不猜。适合已经会用 Claude Code 写代码、但常常遭遇"AI 自作主张改坏文件"或"做到一半发现方向错了"的中级开发者。学完后你将掌握在任意复杂改造前先冻结现场、产出可审批方案、并在执行中保持全可见性。

前置条件

• 已安装 Claude Code（CLI 或 IDE 插件），能跑通一次基础会话
• 熟悉 Git 基本操作（diff、status、stash）
• 手头有一个真实的小项目（3 个以上源文件）用于演练
• 了解终端中 Shift+Tab 这类快捷键的输入方式

第一部分：先理解"三模式"——Plan 不是开关而是第三种状态

很多人误以为 Claude Code 只有"问我"和"不问我"两种状态。实际上它有三种权限模式（permission modes），理解它们的差异是掌握 Plan 模式的前提：

关键认知：Plan 模式是一个只读研究态。进入后，Edit、Write、NotebookEdit 等修改工具被禁用，连 git commit、npm install 这类有副作用的 Bash 命令也会被拦截。Claude 只能 Read、Glob、Grep、LS 以及运行只读 Shell 命令。这种"手脚被绑住"的状态，恰恰逼着它把精力花在阅读和理解上，而不是急着改代码。

三种切换方式

方式一：Shift+Tab 循环（最常用）

在交互式 REPL 中，连按 Shift+Tab 在三种模式间循环：

default  ⇄  acceptEdits  ⇄  plan  ⇄  default ...

底部状态栏会实时显示当前模式。一个实战技巧：连按两次 Shift+Tab 可以从默认模式直接跳进 Plan 模式，省去中间的 acceptEdits。

方式二：/permissions 命令

输入 /permissions 可以查看当前模式、权限规则（allow/deny/ask），并在此面板中手动切换默认模式。

方式三：启动参数与配置文件

# 启动时直接进入计划模式
claude --permission-mode plan

# 或在项目 .claude/settings.json 中固化
{
  "permissions": {
    "defaultMode": "plan"
  }
}

把 defaultMode 设为 plan 适合放在关键生产仓库里——团队任何人起会话都先调研、出方案、经评审后才放开执行权限。

第二部分：Plan 模式实操——从调研到可审批方案

步骤 1：进入 Plan 模式并下达任务

按 Shift+Tab 两次进入 Plan 模式（状态栏显示 plan），然后描述你的改造目标。例如：

"把这个 Express 项目里的 JWT 认证中间件，重构成支持 access token + refresh token 的双令牌方案，并补上单元测试。"

步骤 2：预期行为——只读调研

Claude 此时会进入调研阶段，你会看到它执行一系列只读动作：

• Glob 搜索 **/*auth*、**/*middleware*
• Read 当前认证中间件源码、路由注册文件、配置文件
• Grep 搜索 jwt.sign、verify、Bearer 的用法位置
• 运行只读 Bash：git log --oneline -5、cat package.json

关键点：它不会改动任何文件。如果它尝试调用 Edit，工具会直接返回错误（"Cannot edit in plan mode"），它必须转而继续调研或产出计划。

步骤 3：产出计划文件（plan file）

调研充分后，Claude 会调用 ExitPlanMode 工具，把方案写入一个计划文件（通常位于会话的计划目录），并把这个计划呈现给你审批。一份合格的计划应当包含：

• 目标与验收标准（双令牌、access 短期、refresh 长期、单测覆盖）
• 受影响文件清单（src/middleware/auth.js、新增 src/utils/token.js、tests/auth.test.js）
• 实施步骤（按依赖顺序排列）
• 风险与回滚（兼容旧令牌的过渡期、数据库 session 表新增字段）

步骤 4：审批与切换

你审阅计划后有三个选择：

1. 批准 —— Claude 退出 Plan 模式，通常自动进入 acceptEdits 开始执行
2. 修改 —— 回复"把 refresh token 改成存 Redis 而不是数据库"，它会重新调研并修订计划
3. 拒绝 —— 放弃当前方案

常见问题与解决

Q：我在 Plan 模式里，Claude 却报错说不能编辑，是不是卡住了？ A：这不是 bug 而是特性。Plan 模式的目的就是禁止编辑。如果你希望它直接改，按 Shift+Tab 切回 default 或 acceptEdits。

Q：计划太长，审批面板看不完？ A：计划会写到磁盘文件，你可以用编辑器打开逐行核对。也可以直接在对话框里说"把计划精简成 5 步以内的要点"。

Q：SDK / -p 无头模式下怎么用 Plan 模式？ A：在编程式调用中，Plan 模式映射为两个工具——EnterPlanMode（进入调研态）和 ExitPlanMode（提交计划）。你的编排脚本需要监听 ExitPlanMode 的调用，把计划文本拿到后再决定是否允许进入执行态。

第三部分：TodoWrite——执行阶段的全可见任务跟踪

计划批准后进入执行。复杂任务容易"做着做着忘了第几步"，TodoWrite（交互式会话中的任务清单工具，对应 SDK 中的 TaskCreate/TaskUpdate）就是为此而生。

使用原则

Claude 内部遵循三条硬规则：

1. 3 个或以上离散步骤才创建清单。给一行代码改个 typo 不需要清单。
2. 一次只有一个任务处于 in_progress，其余为 pending 或 completed。
3. 完成一步立即标记 completed，绝不提前标记——如果测试还没跑通，任务必须停在 in_progress。

任务结构

每个任务项包含：

• subject：祈使句标题，如"实现 refresh token 轮换"
• description：详细要求与验收点
• activeForm：进行时态的简短描述，显示在加载动画上，如"实现令牌轮换逻辑"
• status：pending → in_progress → completed
• addBlocks / addBlockedBy：任务间依赖（A 完成后 B 才能开始）

预期行为

执行双令牌重构时，你会看到 Claude 创建一个清单：

☐ 1. 抽取 token 工具模块 src/utils/token.js
☐ 2. 重写中间件支持双令牌校验
☐ 3. 实现 refresh token 轮换与吊销
☐ 4. 补充单元测试（覆盖过期、轮换、吊销）
☐ 5. 跑通 npm test 并修复回归

随着推进，状态实时更新：第 1 项变 in_progress，完成后变 completed，第 2 项自动接上 in_progress。你在终端里能直观看到进度条，而不是干等一个黑盒跑完。

常见问题

Q：清单和计划有什么区别？ A：计划是 Plan 模式产出的"待审批方案文档"；清单是执行期的"实时进度看板"。计划是事前承诺，清单是事中跟踪。

Q：中途发现计划错了怎么办？ A：Claude 应当更新清单（新增、拆分或删除任务项）而不是抛弃它。如果它悄悄删掉了某项，你可以明确说"把第 3 项拆成轮换和吊销两个子任务"。

第四部分：AskUserQuestion——在岔路口做结构化决策

很多返工源于 Claude 在关键决策点上"猜"。AskUserQuestion（Claude Code v2.0.21 引入）让它在分叉点弹出结构化的多选题，把猜测变成确认。

它会怎么问你

假设在认证重构中，Claude 遇到"refresh token 存哪"的决策，它会调用 AskUserQuestion：

问题：refresh token 的存储后端选哪个？
选项：
  (R) Redis  —— 高性能，天然支持 TTL 过期，推荐
  ( ) 数据库表 —— 持久化，但需手动清理过期记录
  ( ) 内存 + 持久化日志 —— 简单但不适合多实例
[可选: Other 让你输入自定义]

四个关键约束：

• header（标签）：最多 12 字符，显示为标签，如 存储后端
• options（选项）：每题 2-4 个，互斥；推荐项放第一个并加 (Recommended)
• multiSelect：默认单选；设 true 则允许多选
• questions：一次最多 4 个问题

使用时机（什么时候该问，什么时候不该问）

应该问： - 架构选型（存储后端、协议、依赖库） - 不可逆操作的确认（删表、改公开 API 签名） - 多个合理方案且影响面大的取舍

不该问： - 能从代码推断的事实（"这个项目用 React 还是 Vue"——自己读 package.json） - 有常规默认值的琐事（"变量名用 camelCase 还是 snake_case"——跟随代码库风格） - 答案会改变后续动作的重大分叉——这种情况应先用 EnterPlanMode 调研，而不是空手就问

与 Plan 模式的配合

最佳实践是：在 Plan 模式的调研阶段用 AskUserQuestion 澄清歧义，而不是在执行到一半才问。因为 Plan 模式还没动任何文件，此时改方向零成本；执行期才发现选错了存储后端，已经写了一半的代码就得回滚。

第五部分：三件套协同——一个完整闭环

把三者串起来，Claude Code 的复杂任务流程是这样的：

1. Shift+Tab×2 进 Plan 模式 —— 冻结现场，禁止任何修改
2. 只读调研 —— Glob/Grep/Read 摸清代码库现状
3. AskUserQuestion 澄清关键决策 —— 在动笔前锁定存储、协议、范围
4. ExitPlanMode 产出计划文件 —— 提交可审批方案
5. 审批 → 切 acceptEdits —— 放开执行权限
6. TodoWrite 建清单 —— 把计划拆成可跟踪的任务项
7. 逐项执行 + 实时更新 —— 一步一标记，全可见
8. 遇阻 → 回 Plan 模式重调研或更新清单 —— 始终可回退

这个闭环的核心价值是低返工 + 可审计：每一次文件改动都经过审批，每一个步骤都有进度，每一个决策都有记录。

实战案例：用三件套重构一个真实模块

下面是一个完整可演练的场景。假设有一个 Node.js 项目，认证中间件只支持单一 JWT，现在要升级为双令牌。

操作命令

# 进入项目，以 Plan 模式启动
cd ~/projects/my-api
claude --permission-mode plan

在 REPL 中输入任务描述：

> 把 src/middleware/auth.js 的单 JWT 认证，升级为 access token(15分钟) + 
  refresh token(7天) 双令牌方案，refresh token 支持轮换与吊销，补全单测。
  老令牌要兼容 30 天过渡期。

预期结果

1. Claude 调研：读 auth.js、路由文件、package.json（确认是否已装 jsonwebtoken、是否已有 Redis 客户端）。
2. 调研中触发 AskUserQuestion： - 存储后端 → 你选 Redis - 老令牌兼容策略 → 你选"双写校验"
3. Claude 调用 ExitPlanMode，计划文件包含 6 个步骤、3 个新增文件、2 个修改文件。
4. 你批准，Claude 自动切 acceptEdits，创建 TodoWrite 清单：

☐ 1. 新建 src/utils/token.js（签发与校验）
☐ 2. 新建 src/utils/refreshStore.js（Redis 轮换/吊销）
☐ 3. 重写 src/middleware/auth.js（双令牌校验 + 老令牌双写）
☐ 4. 新增路由 /auth/refresh 与 /auth/logout
☐ 5. 编写 tests/auth.test.js（过期、轮换、吊销、兼容）
☐ 6. npm test 全绿

5. 逐项执行，状态实时刷新。若第 3 项发现老令牌双写需要数据库 schema 变更，Claude 会更新清单插入新任务而非闷头继续。

常见问题

Q：执行到一半想改存储后端（从 Redis 换成数据库）怎么办？ A：Shift+Tab 回 Plan 模式，让它重新调研并修订计划，重新审批。已写的代码会被纳入修订评估，而不是盲目覆盖。

Q：清单一直卡在某个 in_progress，它好像死循环了？ A：这通常说明遇到了真问题（测试不过、依赖缺失）。读它的最新输出，明确指令"如果第 4 项依赖外部服务跑不起来，先跳过并标记，继续第 5 项"。

三件套协同工作流

flowchart TD
    A[Shift+Tab ×2 进入 Plan 模式] --> B[只读调研: Glob/Grep/Read]
    B --> C{有关键决策点?}
    C -- 是 --> D[AskUserQuestion 结构化提问]
    D --> B
    C -- 否 --> E[ExitPlanMode 产出计划文件]
    E --> F{用户审批}
    F -- 修改/拒绝 --> D
    F -- 批准 --> G[切换 acceptEdits 模式]
    G --> H[TodoWrite 建立任务清单]
    H --> I[逐项执行 + 实时更新状态]
    I --> J{遇阻或需改方向?}
    J -- 是,需重调研 --> A
    J -- 否,全部完成 --> K[任务完成, 全程可审计]

    style A fill:#fef3c7,stroke:#92400e
    style E fill:#dbeafe,stroke:#1e40af
    style H fill:#dcfce7,stroke:#166534
    style K fill:#fce7f3,stroke:#9d174d

图中虚线回环体现了三件套最大的优势——任何阶段都可回退到调研态，而不是一条走到黑的直线。

三种提问/澄清机制对比

记住一个优先级：能用调研解决的，不要靠问；必须问的，用结构化提问而非自由文本；任务一旦复杂到 3 步以上，先 Plan 再 TodoWrite。

训练营适用性评估

延伸阅读

• 官方权限模式文档：code.claude.com/docs/en/permission-modes —— 三模式的权威定义与 Shift+Tab 说明
• SDK 中的 EnterPlanMode / ExitPlanMode：code.claude.com/docs/en/agent-sdk/subagents —— 编程式集成计划模式的入口
• Claude Code Plan Mode 完整指南（2026）：masteringai.io/guides/claude-code-plan-mode-guide —— 含 /plan 命令与键盘快捷键全集
• Plan Mode 最佳实践：cuong.io/blog/2025/07/15-claude-code-best-practices-plan-mode —— 三模式的工程化取舍经验
• claude-code-book 工程实践篇：github.com/HaKuLax/claude-code-book —— 第 14 章 Plan Mode 与结构化工作流

参考来源

1. Choose a permission mode — Claude Code Docs — 官方权限模式权威定义，含 default/acceptEdits/plan 三模式与 Shift+Tab 循环说明
2. How to Use Plan Mode Effectively in Claude Code — Inventive HQ — Plan 模式在编写代码前设计实现策略的完整流程
3. Claude Code AskUserQuestion Tool Guide — SmartScope — v2.0.21 引入的结构化提问工具工作原理与降低返工的用法
4. Claude Code Plan Mode: Complete Tutorial + Keyboard Shortcuts (2026) — Mastering AI — Shift+Tab、/plan 命令与 SDK 中 EnterPlanMode/ExitPlanMode 映射
5. Claude Code Best Practices: The Plan Mode — Code Centre (cuong.io) — 三模式工程化取舍与 Plan 模式何时该用的实战经验
6. Subagents in the SDK — Claude Code Docs — 编程式调用中计划模式工具与子代理隔离上下文的配合

掌握计划模式与任务编排三件套，本质上是在重塑与 AI 协作的纪律：让它先证明理解、再获得改动权。这种"调研—审批—跟踪"的闭环，是把 Claude Code 从"会写代码的助手"升级为"可信赖的工程协作者"的关键一步。下次面对任何超过三个文件的改造，先连按两次 Shift+Tab，你会发现返工率断崖式下降。 �升级→验证] D --> E[resume-runner.sh
捕获/持久化 session_id] E --> F{claude -p --resume
dontAsk 模式}

F -->|PreToolUse 拦截危险命令| G[护栏 deny + reason]
F -->|编辑后 PostToolUse| H[asyncRewake 后台跑测试]
H -->|退出码2| F

F -->|瞬时错误| I[api_retry 自动退避]
F -->|整轮失败| J[StopFailure 留痕]
J --> K[写入 待续跑 标记]

F -->|成功| L[生成变更摘要]
L --> M[状态目录 .claude-state]
K --> M
M --> N[失败回收: 二轮 --resume]
N --> D

style G fill:#fde2e2,stroke:#c0392b
style H fill:#e8f5e9,stroke:#27ae60
style J fill:#fff3cd,stroke:#f39c12

```

常见问题速查

• 续跑后模型失忆：检查 --resume 的 session id 是否来自同一目录；--bare 是否误跳了 CLAUDE.md。
• 护栏没生效：matcher 写成纯字母被当精确匹配——MCP 工具要加 .*；硬性规则改用 permissions.deny。
• 批处理卡死：没用 dontAsk，等一个永远没人按的确认。
• 限流风暴：-P 太高，看 api_retry 的 rate_limit 频率，超阈值降并发。
• 后台测试结果丢了：asyncRewake 要求退出码 2 才唤醒；脚本里别用错退出码。

延伸阅读

• 官方 Hooks Reference（事件全集、matcher 求值、prompt/agent hooks）：code.claude.com/docs/en/hooks
• 官方 Programmatic Usage（-p、--resume、output-format 全谱）：code.claude.com/docs/en/headless
• 官方 Permissions（dontAsk / acceptEdits 与 allow/deny 规则）：code.claude.com/docs/en/permissions
• Agent SDK 计费变更说明（2026-06-15 起独立额度）：code.claude.com/docs/en/agent-sdk/plans
• 社区 issue #28489（无人值守的 retry/verification/resume 能力诉求，含官方回应）

训练营适用性评估

参考来源

1. Run Claude Code programmatically — Claude Code Docs — 官方 -p / --resume / --output-format / api_retry 事件权威说明，本文断点续跑与自愈章节的一手依据。
2. Hooks reference — Claude Code Docs — 官方 hooks 全事件参考，含 StopFailure / PermissionDenied / PreToolUse 决策字段与 matcher 求值规则。
3. Configure permissions — Claude Code Docs — dontAsk / acceptEdits 模式与 permissions.allow / deny 规则，护栏红线设计依据。
4. Headless automation: add retry, verification, and resume — GitHub Issue #28489 — 社区对无人值守 retry/session 持久化/有意义退出码的诉求与官方实现进展。
5. Claude Code Hooks: the complete guide to guardrails that actually work — jakubkontra.com — 实践型 hooks 护栏指南，补充 PreToolUse 动态决策的工程模式。

[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。