# Claude Code 规划与执行分离工作流：交互式确认的工程实践 > 在 CLI 代理中分离规划与执行阶段，通过 Plan Mode 与人工确认机制降低 LLM 自主操作的风险与 token 消耗。 ## 元数据 - 路径: /posts/2026/02/22/claude-code-planning-execution-separation-workflow/ - 发布时间: 2026-02-22T10:47:26+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 站点: https://blog.hotdry.top ## 正文 在 Claude Code 的官方工作流文档中，规划与执行分离是一个被反复强调的核心设计原则。这一原则的底层逻辑与软件工程中「先设计后实现」的传统方法论一脉相承，但其实现方式因 LLM 的 token 消耗特性和自主操作风险而具有了新的工程意义。当我们将 Claude Code 作为 CLI 代理运行时，规划阶段的只读探索与执行阶段的代码修改如果缺乏明确边界，往往会导致代理在理解不足的情况下过早进入实现，进而产生大量的上下文回溯和不必要的 token 消耗。分离这两个阶段并引入交互式确认机制，本质上是用结构化的人类审查来替换模型的无约束试错。 ## Plan Mode 的设计意图与工作机制 Claude Code 内置的 Plan Mode 是实现规划与执行分离的技术基础。当代理处于 Plan Mode 状态下时，系统会明确指示其不得进行任何写操作——包括代码编辑、配置文件修改，甚至不允许运行非只读的工具。这一约束不是简单的行为建议，而是通过系统提示词层面的指令来强制执行。代理在 Plan Mode 中只能读取文件、搜索代码库、询问澄清问题，并将分析结果输出到指定的计划文件中。 这种模式的设计意图可以从两个维度理解。从 token 经济性角度来看，规划阶段的产物——一份结构化的实现计划——可以被缓存并重复使用。当执行阶段因为某些原因需要中断或回滚时，我们无需重新进行完整的代码探索，只需基于已有的计划文件恢复上下文即可。从风险控制角度来看，Plan Mode 将 LLM 的自主决策边界限制在「提出方案」这一层面，任何涉及代码库实际变更的操作都必须等待人类的明确批准。 在实际使用中，一个典型的工作流是这样的：首先进入 Plan Mode，让代理分析现有代码结构、理解需求、识别受影响的文件和潜在的边界情况；代理会生成一份包含目标、约束、影响范围和分步骤实现 outline 的计划文件；人类开发者阅读这份计划，必要时手动修改或补充，然后给出「确认执行」的明确指令；只有在这一步完成后，代理才退出 Plan Mode 并开始实际的代码修改。 ## 文件结构与契约设计 要让规划与执行两个阶段真正解耦，仅靠 Claude Code 的模式切换是不够的。我们需要在文件系统层面建立一套可被代理识别的契约结构，使得执行阶段的代理只能基于已批准的计划行事，而不能凭空发明新的任务。 一个经过实践验证的文件结构包括以下几个核心组件。`specs/` 目录存放架构和模块级别的规格说明，这些文件相对稳定，只有在系统架构发生重大变化时才需要更新。`plans/` 目录存放具体的实施计划，建议按日期或功能命名，例如 `plans/2026-02-21-auth-revamp.md`，这样可以追踪每个计划的产生时间和关联功能。`status.md` 作为项目状态的「指针」，始终指向当前活跃的计划和项目所处阶段。`project_status.md` 则是运行的日志，记录已完成的工作和待处理事项的进展。 以一个具体的 `status.md` 为例，它应当包含当前激活的计划引用、当前所处的阶段编号（例如 Phase 1/3）、本次工作的核心焦点（例如「替换遗留的会话 cookie 为基于 token 的认证」）以及最后更新时间。这种结构化设计使得任何一个代理在启动时都能通过读取 `status.md` 立即了解项目的整体状态和当前任务，而无需重新探索整个代码库。 ## 确认机制的工程化参数 将规划与执行分离仅仅是万里长征的第一步，真正让这一模式产生工程价值的是确认机制的具体参数设计。我们需要回答几个关键问题：计划需要细化到什么程度才能进入执行阶段？人类审查的具体检查清单是什么？执行过程中的哪些操作需要额外的二次确认？ 从实践中总结出的参数建议如下。计划粒度方面，每个阶段的任务应当足够小，以保证在 30 分钟以内可以完成一个检查项。这种粒度设计有两层考量：一方面，小粒度的任务更容易被准确评估和确认；另一方面，当执行出现偏差需要回滚时，小粒度的任务划分可以将损失控制在最小范围。 确认清单方面，人类在批准计划进入执行阶段前，应当逐一检查以下项目：计划中列出的每个检查项是否都有明确的验收标准；受影响文件的范围是否与计划声明的范围一致；是否存在被忽视的依赖项或潜在的系统兼容性问题；计划中是否预留了回滚或功能开关的策略。这些检查项可以通过一个结构化的确认模板来固化，确保每次批准决策都是经过系统化思考的。 二次确认阈值方面，建议对以下几类操作设置更高一级的人工确认要求：任何涉及生产数据库的迁移脚本；任何修改认证、授权或加密相关的代码；任何删除或重命名文件的操作；任何引入外部依赖或改变构建配置的操作。这些操作的风险较高，即使计划中已经列出，也应当在实际执行前要求人类再次确认。 ## 工作流脚本化的实践路径 将上述设计整合到一个可重复执行的工作流中，需要借助 Claude Code 的 CLI 能力和自定义脚本来实现。以下是一套经过简化的命令模式，可以直接用于日常开发。 首先是规划阶段的命令模式。运行规划代理时，应当明确指定其只读范围和写入目标：`ai plan --read specs auth/ app/ project_status.md --write plans/2026-02-21-auth-revamp.md status.md project_status.md --goal "Plan auth revamp in 3–5 phases, no code edits."`。这个命令的核心在于通过 `--read` 和 `--write` 的明确分离来强化规划阶段的职责边界。规划代理被限制为只能读取指定的规格和代码目录，只能写入计划文件和状态文件，不得触碰实际的业务代码。 然后是执行阶段的命令模式。在人类批准计划并退出 Plan Mode 后，运行实施代理：`ai code --read status.md plans/2026-02-21-auth-revamp.md specs/auth.md --read app/ config/ tests/ --goal "Implement Phase 1 in the plan exactly; no out-of-scope changes." --write app/ config/ tests/ impl_notes.md`。注意这里同样通过 `--write` 参数限制了实施代理的文件修改权限，使其只能修改应用代码和测试代码，而不能修改计划文件本身。 为了进一步强化隔离效果，建议在执行阶段使用 Git worktree 创建一个独立的分支或工作树。具体的操作流程是：首先从主分支创建一个新的 worktree，例如 `git worktree add ../auth-revamp feature/auth-revamp`；然后在这个隔离的工作树中运行实施代理；最后在所有修改完成后，通过 Pull Request 的方式将变更合并回主分支。这种隔离策略的好处在于，即使实施代理在执行过程中出现了严重的偏差或错误，原始代码库也不会受到任何影响。 ## 风险边界与适用场景评估 尽管规划与执行分离的工作流设计在理论上具有显著优势，但我们也需要清醒地认识到其适用边界。对于小型、探索性的代码修改或概念验证项目，强制性的规划-执行分离可能带来过重的流程负担。在这些场景下，让 Claude Code 快速探索并即时修改往往能更快地验证想法的可行性。 对于需要长期维护的生产系统、涉及多人协作的复杂功能开发、以及对代码质量有较高要求的项目，规划与执行分离的工作流设计则能够显著降低风险。特别是在需要审计追溯的场景下，计划文件本身就是一份有价值的设计文档，可以帮助后续的维护者理解当时的决策上下文。 从 token 消耗的角度来看，分离工作流的收益在于避免了规划阶段的上下文在执行阶段被反复重建。传统的无分离模式下，代理可能需要在每次代码修改时重新理解整个代码库；而在分离模式下，规划阶段的分析结果作为结构化计划被持久化，执行阶段的代理可以直接基于计划行动，显著减少了重复探索带来的 token 浪费。 --- **资料来源**：本文参考了 Claude Code 官方工作流文档中关于 Plan Mode 的设计说明，以及 Hacker News 讨论区中开发者分享的 CLI 代理规划-执行分离实践。 ## 同分类近期文章 ### [NVIDIA PersonaPlex 双重条件提示工程与全双工架构解析](/posts/2026/04/09/nvidia-personaplex-dual-conditioning-architecture/) - 日期: 2026-04-09T03:04:25+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 NVIDIA PersonaPlex 的双流架构设计、文本提示与语音提示的双重条件机制，以及如何在单模型中实现实时全双工对话与角色切换。 ### [ai-hedge-fund：多代理AI对冲基金的架构设计与信号聚合机制](/posts/2026/04/09/multi-agent-ai-hedge-fund-architecture/) - 日期: 2026-04-09T01:49:57+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析GitHub Trending项目ai-hedge-fund的多代理架构，探讨19个专业角色分工、信号生成管线与风控自动化的工程实现。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation-framework/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [LiteRT-LM C++ 推理运行时：边缘设备的量化、算子融合与内存管理实践](/posts/2026/04/08/litert-lm-cpp-inference-runtime-quantization-fusion-memory/) - 日期: 2026-04-08T21:52:31+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 LiteRT-LM 在边缘设备上的 C++ 推理运行时，聚焦量化策略配置、算子融合模式与内存管理的工程化实践参数。