一、传统 AI 助手的困境
想象一个熟悉的场景：
你正在开发一个功能，对 AI 助手说：“帮我实现一个购物车，支持增删改查和结算”。AI 开始工作了，它创建了一个文件，写了一些代码，然后它创建了另一个文件，又写了一些代码。
十分钟后，你发现：
·数据结构设计得很奇怪，和你现有的用户系统对不上
·状态管理用了一个你从没用过的库
·有三个文件的命名风格完全不一致
·你专属于自己的 MCP、Skill、SubAgent 等没有在你的预期内使用
·最关键的是，它漏掉了优惠券功能
问题的根源是什么？ AI 收到指令就立即动手，没有先对齐需求、拆解任务、确认方向：缺少一个关键环节：规划。
二、Plan Mode 的核心优势：
1. 规划准确性：通过渐进式澄清对话，确保 AI 真正理解你的需求
2. 方案全面性：输出包含需求分析、技术架构、视觉设计、任务拆解的完整方案
3. 执行可控性：在代码生成前可以审阅和调整方案，避免后期重构
4. 扩展协同性：智能编排 MCP、Skill、SubAgent 等扩展能力，生成专属方案
5. 知识复用性：完成的 Plan 保存为 Markdown，可作为项目知识库复用
三、Plan Mode 的解法
CodeBuddy 在“理解”和“执行”之间插入了“规划”环节：在执行前先想清楚要做什么、怎么做、分几步做。
| 痛点 | 传统模式 | Plan Mode |
| 执行偏差 | AI 的实现方向与用户预期不符 | 需求澄清环节对齐预期 |
| 不可控性 | 用户无法预知 AI 会做什么 | 方案预览，执行前可审阅 |
| 修正成本高 | 每次修改都可能引入新问题 | 完整规划，避免反复 |
| 上下文丢失 | 长对话中 AI 逐渐“忘记”初衷 | 计划持久化，状态可追溯 |
四、Plan Mode vs Craft Mode：什么时候用哪个？
Plan 和 Craft 不是非此即彼的选择，而是针对不同场景的两种协作模式。理解它们的差异，能让你的开发效率翻倍。
| 维度 | Plan Mode | Craft Mode |
| 工作方式 | 先规划后执行，在编码前明确方案 | 直接执行，快速响应指令 |
| 适用场景 | 复杂功能、架构设计、多文件协同 | 局部修改、单文件优化、Bug 修复 |
| 输出形式 | 完整方案（需求+技术+设计+任务） | 直接代码结果 |
| 可控性 | 高，执行前可审阅和调整方案 | 中，边执行边调整 |
| 扩展能力 | 智能编排 MCP/Skill/SubAgent | 按需调用扩展 |
| 典型场景 | 新功能从零实现：需要明确技术选型、架构设计和实现路径多文件协同修改：涉及多个模块，需要统一的技术方案指导UI/UX 设计与实现：需要先设计视觉风格和交互逻辑再编码存量项目改造：需要理解现有架构，确保新功能符合项目规范复杂任务拆解：需要将大型需求分解为可执行的步骤 | 快速 Bug 修复：问题明确，需要快速定位和修复单文件局部调整：改动范围小，直接执行更高效代码重构优化：针对已有代码进行改进代码解释理解：需要理解某段代码的作用 |
五、开启 Plan Mode
1. 打开侧栏，在对话框左下角工作模式中选择 Plan Mode。
2. 若已有项目计划，可直接在编辑器内打开，未完成的计划会保留上下文与执行进度。
Plan 将一次协同过程拆分为五个阶段，每个阶段都支持人机协作与图片提示，帮助你在 IDE 内完成从想法到落地的闭环。
flowchart LR A[需求澄清] –> B[方案制定] B –> C[方案编辑/确认] C –> D[方案实施] D –> E[方案完成] style A fill:#e6f3ff style B fill:#fff3e6 style C fill:#e6ffe6 style D fill:#ffe6e6 style E fill:#f3e6ff
六、第一步：需求澄清（Prepare 状态）
在这一阶段，AI 会通过渐进式对话帮你明确需求边界，确保双方对任务的理解一致。
具体操作：
1. 描述需求：在输入框中描述你的目标或粘贴需求文档
2. 回答澄清问题：AI 会提出1 – 2个关键问题，确认技术栈、功能范围、限制条件等
3. 确认需求：回答完所有问题后，AI 会生成需求总结，确认后进入下一步
注意：小贴士：
七、第二步：方案制定（Prepare 状态）
需求确认后，AI 会生成完整的方案草稿。这是 Plan Mode 的核心，在执行前就把所有事情想清楚。
方案生成过程：
Plan 会根据你提供的任务要求，先给出实施大纲，再在已有的项目中搜索相关的代码、设计、文档等，生成方案草稿。
方案包含的内容：
| 模块 | 说明 |
| 需求分析 | 提炼核心价值、功能边界和预期输出 |
| 技术方案 | 技术选型、架构设计、关键组件和数据流 |
| 视觉设计 | UI 风格、交互逻辑、配色方案（如适用） |
| 任务列表 | 可执行的步骤清单，标明依赖关系和优先级 |
| 扩展能力 | 推荐使用的 MCP/Skill/SubAgent 及其用途 |
AI 会智能编排你的扩展能力：
·分析任务需求，自动匹配合适的 MCP、Skill、SubAgent
·在方案中说明每个扩展的作用和预期产出
·避免幻觉调用，只使用你已配置的扩展
八、第三步：方案编辑/确认（Ready 状态）
生成方案后，你可以审阅、编辑并确认。这是执行前可预见的关键环节：在代码生成前修正方向，避免后期重构。
可以编辑的内容：
| 编辑类型 | 操作 |
| 正文内容 | 调整描述、补充约束、添加参考链接 |
| 技术方案 | 修改技术选型、调整架构设计 |
| 任务列表 | 插入/删除/重排任务，补充执行细节 |
| 扩展能力 | 增删插件或智能体以适配新场景 |
| Markdown 编辑 | 更新任务列表 |
| | |
| 设计配置编辑 | 方案扩展配置 |
| | |
确认执行前检查：
·技术方案是否符合项目现有架构？
·任务拆解是否完整，依赖顺序是否正确？
·设计规范是否与现有 UI 风格一致？
·扩展能力选择是否合理？
九、第四步：方案实施（Building 状态）
点击开始执行后，计划进入执行阶段。AI 会按照任务列表逐步执行，并实时反馈进度。
执行过程：
1. 状态切换：计划状态变为 Building，任务按序执行
2. 进度反馈：AI 每完成一个任务会标记状态，你可以实时查看进度
3. 中断处理：执行中可以随时暂停，提出新需求或调整方向
4. 深度调用扩展：AI 会按照方案中的规划，深度调用 MCP、Skill 等扩展能力
| 执行状态 | 过程结果 |
| | |
执行中的调整：
·微调方案：可以在编辑区修改正文，diff 会高亮显示变化
·切换 Craft：对于局部问题，切换到 Craft Mode 快速修复更高效
·中断恢复：遇到新需求时，AI 会暂停当前计划，处理完后再恢复
十、第五步：方案完成（Finished 状态）
全部任务完成后，计划进入完成状态。
完成后的操作：
| 操作 | 说明 |
| 查看成果 | 在编辑器中查看生成的代码和修改的文件 |
| 归档计划 | 计划自动保存为 Markdown 文件，位于 .codebuddy/plans/ |
| 导出分享 | 可下载计划文件，与团队共享或继续迭代 |
| 复用知识 | 历史计划可作为上下文引用，帮助 AI 快速理解项目背景 |
| 完成与保存 | 下载计划 |
| | |
十一、任务粒度控制
| 做法 | 原因 | 风险 |
| 单一 Plan 聚焦单一功能模块 | AI 在有限上下文内保持一致性更强 | 过大的 Plan 会导致命名不一致、接口风格混乱、状态管理冲突 |
| 功能模块完成后再开始下一个 | 可验证的中间产物便于问题定位 | 多个未完成的 Plan 并行会增加上下文混乱 |
| 复杂需求由 AI 自行拆分 | AI 能基于技术依赖关系合理划分边界 | 人工强制拆分可能破坏模块间的自然耦合 |
十二、Preview 阶段的审阅价值
在方案生成后、执行前认真审阅，是避免后期重构的关键环节。
| 审阅维度 | 检查要点 | 修正成本对比 |
| 技术方案 | 是否符合项目现有架构、技术栈选择是否合理 | Preview 修改：几乎为零 / 代码完成后修改：可能需要重构 |
| 任务拆解 | 是否遗漏关键步骤、依赖顺序是否正确 | Preview 修改：调整文字 / 执行中发现：需要中断并重新规划 |
| 设计规范 | 是否与现有 UI 风格一致、命名是否符合规范 | Preview 修改：补充约束 / 代码完成后：批量重命名 |
核心原则：在代码生成前修正方向，避免后期重构。
十三、扩展能力的协同作用
扩展能力（Skills、MCP、SubAgents、Integration）不是独立的工具，而是与 Plan Mode 形成协同矩阵：
| 扩展类型 | 作用机制 | 典型应用 |
| Skills | 注入领域知识和最佳实践到规划上下文 | frontend-design 提升 UI 设计质量 |
| MCP | 连接外部服务，获取实时数据和最新文档 | Context7 获取框架最新 API 文档 |
| SubAgents | 处理特定类型的复杂子任务 | debug-with-logger 系统化问题诊断 |
| Integration | 打通部署和数据库等基础设施 | CloudBase/CloudStudio 一键部署 |
扩展能力在 Plan 生成阶段被注入上下文，AI 会根据任务需求智能选择并在 todolist 中显式引用。
十四、Plan 的复用价值
完成的 Plan 保存在 .codebuddy/plans 目录下，具有以下复用价值：
·上下文传递：新任务可引用历史 Plan，快速建立项目背景理解
·Token 节省：避免重复描述已有的架构和规范
·知识沉淀：形成项目级的决策记录和技术方案库
使用建议：
·在新对话中引用历史 Plan，帮助 AI 快速了解项目背景
·将成功的架构设计和技术选型保存为模板，供后续类似功能复用