Claude Code 计划模式：以评审为先的重构循环

许多开发者初次使用 Claude Code 的方式都很相似：粘贴任务、让它运行、然后查看 diff。对于小改动这没问题，但一旦涉及多个文件，就开始变得不可靠了。

Claude 每个未经引导的决策大多数时候也许都是对的，听上去还行，但当这些决策叠加时就不妙了：例如，假设每个决策有 80% 的准确率，对于包含 20 个决策点的功能，0.8^20 会把成功概率降到约 1%。

计划模式通过增加只读阶段来改变这种算术。您让 Claude 阅读代码库、提出问题，并在接触任何文件之前产出一份由您审阅的计划。

本教程将以一个凌乱的 FastAPI 博客 API为示例，演练“探索-计划-执行”的循环，介绍用 Ctrl+G 编辑计划，以及如何使用 Agent Teams 扩展到更大规模的重构。

我们的Claude Code 最佳实践教程更深入地讨论了误差叠加问题；如果您需要安装与功能讲解，请参阅Claude Code 2.1 指南。

想了解 Claude Code 背后的模型，请查看关于Claude Sonnet 4.6与Opus 4.6的指南，或参加我们的Claude 模型入门课程。

什么是 Claude Code 计划模式？

计划模式会将 Claude 锁定在只读操作中。它可以读取文件、搜索代码库并向您提问，但任何写文件、编辑代码或运行 Shell 命令的尝试都会被拒绝。试着在计划模式下让它“就快速修一下这个”，它也不会执行。

您可以通过四种方式启用：

• 在输入框中连续按两次 Shift+Tab，在普通、自动接受与计划模式之间循环切换

• 使用 /plan 命令进入计划模式，直到您再次切换

• 用 --permission-mode plan CLI 标志以计划模式启动新会话

• 在 settings.json 的 permissions.defaultMode 下设置计划模式为永久默认值

一旦 Claude 生成计划完成，它会将结果保存为 markdown 文件，位于 ~/.claude/plans/，文件名随机生成（例如 dreamy-orbiting-quokka.md）。

该文件是可审阅的“合同”：它可跨会话保留，不会受 /clear 或上下文压缩影响，且只有在您批准后才会实施。请注意，尽管计划文件本身会持久化，但在发生上下文压缩后，如果不提示它重新阅读计划，Claude 有时会“忘记”该文件。

若您希望将计划存放在项目内以便版本控制，可在 settings.json 中设置 plansDirectory 为项目相对路径，如 ./plans。

项目相对的计划文件能解锁 ~/.claude/plans/ 无法支持的工作流：

• 在有人开始编码之前，于拉取请求中审查计划 diff
• 无需依赖上下文压缩，在会话之间保留注释
• 将该 markdown 文件视为可共同编辑的“活规范”，供多名团队成员直接修改

对于长期重构或多会话工作，受版本控制的计划文件比单靠Ctrl+G更可控。

实施 Claude Code 的“探索-计划-执行”工作流

为了展示三个阶段如何协同，我们将重构一个 fastapi-blog-api 仓库。它没有测试，并且有三个“包揽太多职责”的文件：

• main.py：所有路由、内联鉴权检查、硬编码配置、发送邮件

• models.py：ORM 模型、Pydantic 模式、查询函数、种子数据

• utils.py：密码哈希、JWT 令牌、S3 上传、Markdown 渲染、缓存、限流、CSV 导出

阶段一：在做任何事之前先收集上下文

在计划模式下开始该任务（先在本地克隆GitHub 仓库）。开场提示应说明您的目标，并指示 Claude 阅读相关文件：

I want to refactor this FastAPI blog API into a clean module structure with proper separation of concerns and full test coverage. Read through main.py, models.py, and utils.py first. Map out which functions belong together, flag any shared state or circular dependency risks, and identify what needs testing most.

Claude 会将代码库调研委托给受限于只读工具的内置子代理。它读取了这三个文件，跟踪了它们之间的导入关系，并使用 AskUserQuestion 提出了不明确之处。

这些问题涵盖了几项高层决策：

• 架构深度（扁平路由 vs. 完整服务层）
• 如何处理硬编码配置
• 是否移除或保留无用的工具函数
• 使用哪种测试框架

这些问题至关重要。仅架构方案一项，如果没有人工输入，就可能是“掷硬币”。Claude 会偏向训练数据中最常见的模式，而对于 FastAPI，通常是扁平的路由结构。在这里回答“使用服务层”，省去了后续整整一轮的再次重构。

如果您有与目标架构相匹配的参考项目，请在提示中附上链接。相比抽象描述，Claude 在有可借鉴的真实示例时会产出更好的计划。

在接受任何计划之前要检查的一点：Claude 的问题是否引用了具体函数和行级细节，还是只提到了文件名？如果它问的是“认证系统”，却从未提到 verify_jwt_token 或 main.py 中的中间件链，那就说明它只是扫了一眼而非认真阅读。推动它在进入第二阶段前更仔细地阅读。

阶段二：生成并编辑计划

在您回答完 Claude 的问题后，它会自动生成计划，无需额外提示。计划会保存到 ~/.claude/plans/，并包含：

• 上下文摘要
• 目标目录结构
• 逐步的实施顺序
• 验证部分，包含确认重构成功的命令

在决定如何继续之前，按下Ctrl+G，在您的默认文本编辑器（由 $EDITOR 指定）中打开计划。或者使用 /plan open 直接打开当前计划文件。

计划模式的价值在此步就能体现。您可以为步骤添加行内注释、删除不同意的步骤、调整顺序并保存。返回终端后 Claude 会捕捉到每一处修改。

对于该博客 API 的计划，注释可能如下：

## Step 3: Extract auth module
Move JWT validation and password hashing to auth/
> NOTE: extract auth middleware BEFORE splitting routes,
> otherwise the route files will import from utils.py
> and we'll have to update imports twice
 
## Step 5: Database layer
Create a repository pattern for database operations
> NOTE: keep the SQLAlchemy session factory in a shared
> db.py, don't put it in models.py

对于复杂计划，一次 Ctrl+G 可能不够。先加注释，回来后告诉 Claude “在不实施的前提下，处理计划中的全部注释”，审阅修订版，再次 Ctrl+G。每一轮注释都能消除歧义，否则就会变成错误的实施决策。

当“合同”看起来合适时，Claude 会提供几种选项：

1. 按计划执行并清空上下文（会话已变“陈旧”时很有用），
2. 不清空直接执行（保留会话历史），或
3. 继续就计划进行对话。

根据您已积累的上下文量来选择。如果您已经在长会话中走得很深，清空能给 Claude 一个干净的执行窗口。

阶段三：执行已批准的计划

选择其中一个工作选项，Claude 会按部就班开始实现。它会逐步推进，遇到需要手动干预（如终端中的交互式认证）时暂停，或者在整个计划完成时停止。

留意“偏离”。计划要求首先将认证抽取为独立模块，但 Claude 可能会因为发现“捷径”，同时开始抽取路由与认证逻辑。这样的操作很容易导致“半迁移”的代码库：部分导入指向旧位置，另一部分指向新位置。

其他偏离信号：

• 编辑当前步骤未提及的文件
• 对计划中尚未定论的架构问题悄然做出决定
• 将计划中分开的两个步骤合并执行

一旦出现偏离，按 Shift+Tab 回到计划模式。Claude 会读取当前文件状态，为剩余步骤产出修订后的计划，您再审阅后继续。这并非“救火”措施。大多数多文件重构都要经历 2-3 轮计划修订。

对于无法在单个会话中完成的重构，将工作拆分为连续的多个计划，而不是一个庞然大物。先在一个独立计划下完成认证抽取，再开启新会话并为路由拆分创建新的计划。

使用 /rename 为每个会话命名（例如“blog-api-auth-extraction”），这样就可以通过 /resume 继续上次进度。更小的计划能让上下文窗口更聚焦，并在各阶段之间提供自然的检查点。

Claude Code 计划模式的实用策略

既然我们已经完整走了一遍流程，下面来看一些最佳实践，帮助您最大化利用计划模式。

何时使用计划模式（以及何时可以跳过）

并非所有任务都需要计划。单行修复、错别字更正以及孤立函数的更新，直接执行更快。对机械性改动也同样如此，比如在单个文件内重命名变量。

一个不错的经验法则：如果改动涉及三个或以上文件，或者您无法用一句话完整描述该改动，就先规划。三个文件大致是误差叠加开始发作的门槛，因为每个文件都会带来一组需要 Claude 做对的决策。

总是受益于计划模式的任务：

• 在文件之间移动代码或重命名共享接口的重构
• 触及现有模块的新功能
• 带有破坏性 API 变更的依赖升级
• 当您不确定代码库如何处理某个特定情况的任何任务
• 希望与 Claude 反复打磨方案、且零风险避免过早编辑的头脑风暴

在计划导致代价前识别其薄弱之处

结构看起来“像模像样”的计划并不一定是好计划。在当前的 Claude Code 版本中，杜撰文件引用和含糊的“按需更新”步骤已较为少见。更常见的问题是：计划把所有实施步骤放在前面，最后才补一句“添加测试”。

这种结构的计划往往比您预期的产出更差。没有在实施过程中加入测试，Claude 在会话中途就缺少自我验证的手段。对于该博客 API 的重构，如果计划写着“第 1-6 步：抽取所有模块，第 7 步：编写测试”，那就意味着前六步的代码没有任何反馈回路。

更强的计划会采用测试驱动开发（TDD），在实现中穿插测试：先为 auth/ 编写测试，再抽取认证函数并确认通过；然后为 posts/ 编写测试，再抽出路由。每个通过的测试都会向 Claude 发出明确信号：重构走在正确轨道上。

将 TDD 约定写入项目的 CLAUDE.md 能让 Claude默认包含测试步骤。Claude Code Hooks 可通过运行验证脚本，在批准执行前检查计划质量，从而自动化这类约束。

用 Agent Teams 扩展大型重构

当计划涉及七个或更多文件时，执行阶段的上下文窗口会被填满，计划质量开始下降。该博客 API 的重构一旦将路由、模型、服务、配置、测试与新目录结构都纳入，就会达到这一阈值。

Agent Teams 是一项实验特性，可将此类工作分发到多个 Claude Code 实例中。一个会话充当团队负责人，队友各自拥有独立的上下文窗口。

对于该博客 API，您可以拆分为三个队友：一位负责路由抽取，一位负责数据库与模型层，一位负责测试覆盖。负责人分配任务，队友认领并完成；被阻塞的任务（如“更新导入”依赖于“抽取模块”）会在依赖完成后自动解锁。

同样的拆分也适用于跨仓库：如果您的 API 依赖共享库，一名队友可重构该库，另一名则更新 API 对其的使用。

计划模式的最佳设置是要求队友的计划必须审批。对负责人说：“为该博客 API 重构创建三名队友。在他们进行任何更改之前，必须批准其计划。”

1. 每位队友在只读模式下制定计划
2. 负责人审阅并批准或附反馈拒绝
3. 仅执行已批准的计划

您可以通过设定准则来塑造负责人的判断：“只批准包含测试覆盖的计划”或“拒绝直接修改数据库架构的计划”。通过在 settings.json 的 env 区块中添加 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" 可启用 Agent Teams。

若不使用该实验标志，也可通过 git worktree 实现更简单的并行：在不同分支上分别运行计划模式会话，各自推进自己的计划。

如果长会话发生上下文压缩，请让队友显式重新打开并重读其计划文件以避免偏离。

Claude Code 插件教程还涵盖了管理多阶段工作的其他模式。

结语

计划模式的价值归结为一点：先评审，再执行。您添加的每一轮注释、Claude 提出的每一个问题，都能消除一个本可能出错的决策。

从您下一个涉及多文件的改动开始，先强制 Claude 制定计划，再用 Ctrl+G 编辑该计划，之后再授予写入权限。关于 CLAUDE.md 配置、上下文管理以及基于 Hook 的护栏设置，请查看最佳实践教程，它将承接本教程的内容。

若想从更宏观的层面了解 AI 辅助编程，建议查看我们的AI for Software Engineering技能路径，学习基础概念，并亲手体验 GitHub Copilot、Windsurf、Replit 等类似工具。