Blade Plan — 轻量规划执行工作流

先想清楚，再动手写。用最小的流程开销，获得结构化开发的核心收益。

定位

Blade Plan 面向中等复杂度的开发任务，在"直接对话"和"分阶段设计"之间提供一条中间路径：

复杂度	方式	文件变更量	典型场景
低	直接对话	1~5 个文件	单个 bug 修复、配置调整、工具方法添加
中	Blade Plan	5~15 个文件	新增中等功能、跨模块重构、复杂 bug、新 Starter
高	分阶段执行	15+ 个文件	从零开发完整模块、复杂系统设计、大型架构重构

判断标准不是绝对的文件数，而是：需求是否清晰到可以直接拆任务？改动是否能在一次会话内完成？如果两个答案都是"是"，Blade Plan 就是合适的选择。

核心理念

• 先规划后执行：先把思路理清、任务拆好，再逐个动手——这能避免写到一半发现方向错了
• 上下文锚定：每个任务执行前重读相关代码，防止在对话累积中逐渐偏离
• 最小变更：只做计划中的事，不夹带"顺手优化"
• 构建验证：编译不过的代码等于没写
• 零文件开销：不生成任何辅助文件（无 spec.json、tasks.json、design.md 等），所有规划直接在对话中呈现，进度由 Claude Code 内置 TaskCreate / TaskUpdate 追踪

使用方式

/blade-plan <需求描述>           # 启动规划执行（展示方案后等待确认）
/blade-plan --auto <需求描述>    # 启动规划执行（自动模式，展示方案后直接执行）

示例：

/blade-plan 给 blade-starter-redis 新增分布式限流注解，支持按IP和用户维度限流
/blade-plan --auto 重构 OssTemplate，将各厂商实现拆分为独立策略类
/blade-plan 修复多租户场景下动态数据源切换时连接池泄漏问题

路由逻辑

收到用户输入后：

1. 带 --auto 参数：提取需求描述 → 自动模式（规划后直接执行，不等确认）
2. 带需求描述：→ 交互模式（规划后等待用户确认）
3. 无参数：提示输入需求描述

---

工作流

用户需求 → [分析与规划] → 确认 → [逐任务执行] → 完成总结
                              ↑
                         自动模式跳过

三个步骤，一次确认，全程用 Claude Code 内置任务系统追踪进度。

---

步骤一：分析与规划

目标：理解需求，摸清现状，制定可执行的任务清单。

执行动作：

1. 理解需求：

   • 解析用户的需求描述，提炼核心功能点
   • 识别隐含需求和边界条件
   • 如有歧义，先向用户澄清关键问题再继续

2. 扫描现状：

   • 阅读 CLAUDE.md 了解项目规范（如有）
   • 扫描相关模块现有代码，理解代码结构和风格
   • 搜索是否有可复用的类、工具方法或已有实现
   • 评估改动对现有功能的影响范围

3. 制定方案：

   • 确定技术实现策略（用什么方式解决问题）
   • 识别需要新增和修改的文件
   • 将改动拆解为有序的任务列表（按依赖关系排序）
   • 任务粒度：一个任务对应一个逻辑完整的改动单元（通常 1~3 个文件）

4. 展示规划，格式如下：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  📋 Blade Plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
需求：{一句话概述}

方案：
  {2~4 句话描述技术方案的核心思路，
   包括关键的技术选型和架构决策}

任务清单（共 X 个）：
  1. {任务标题}  — {涉及的文件或模块}
  2. {任务标题}  — {涉及的文件或模块}
  3. {任务标题}  — {涉及的文件或模块}
  ...

影响范围：
  新增 X 个文件 | 修改 Y 个文件
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

5. 等待确认或自动推进：

   • 交互模式：追加 请确认方案后开始执行，或提出修改意见。 并等待用户回复
   • 自动模式：展示规划后直接进入步骤二
   • 用户说"可以"/"没问题"/"开始"等视为确认通过
   • 用户提出修改意见则调整方案后重新展示

6. 创建任务：确认后，使用 TaskCreate 为每个任务创建跟踪条目，便于用户实时看到进度

---

步骤二：逐任务执行

目标：按计划逐个完成任务，保持纪律性。

对每个任务执行以下循环：

1. TaskUpdate → 标记当前任务为 in_progress

2. 加载上下文（上下文锚定）：

   • 重新阅读目标文件及其关联代码——即使刚才读过，也要再看一眼
   • 查看前序任务的产出文件，确保接续一致
   • 模仿同模块现有代码的风格和模式

3. 执行编码：

   • 严格遵循项目 CLAUDE.md 编码规范（如有）
   • 只做当前任务描述的事，不附带额外改动
   • 执行前判断是否可借助其他 Blade 技能加速（见「技能协同」）

4. TaskUpdate → 标记当前任务为 completed

5. 继续下一个任务

为什么要逐任务而不是一口气全写完？因为每个任务完成后的代码状态是下一个任务的输入。逐步推进让每一步都建立在稳固的基础上，也让用户能实时看到进度。

构建检查点

每完成一组逻辑相关的任务（或每 3~4 个任务），执行构建验证：

• Maven 项目：mvn clean compile -DskipTests
• Gradle 项目：gradle compileJava
• Node.js 项目：npm run build 或 tsc --noEmit
• 其他项目：根据项目构建配置自动识别

构建失败则立即修复后再继续，不跳过，不拖延。

技能协同

执行任务时，识别任务类型并借助对应技能提升效率：

任务特征	推荐技能	说明
后端 CRUD 全套（Entity → Mapper → Service → Controller）	/blade-design	生成骨架代码，再根据实际需求补充业务逻辑
Avue 组件前端页面	/avue-design	生成配置化的 Avue 前端代码

协同原则：技能生成的代码是起点而非终点——生成后必须根据实际需求调整，并通过构建验证。

关于代码提交：/blade-commit 绝不自动执行。完成总结后将提交作为后续建议告知用户，由用户自行决定何时提交。仅当用户明确要求"帮我提交"时才执行。

---

步骤三：完成总结

所有任务完成后，输出总结报告：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ Blade Plan 执行完毕
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
任务: X/X 完成

新增文件:
  + path/to/NewFile.java
  + path/to/AnotherFile.java

修改文件:
  ~ path/to/ExistingFile.java

后续建议:
  1. 功能测试（交由用户执行）
  2. 确认无误后可使用 /blade-commit 提交代码
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

关键原则

上下文锚定

每个任务执行前，重新阅读相关代码。哪怕觉得"刚才看过了"，也要再扫一眼。中等任务的对话虽不如大型任务长，但 5~6 个任务执行下来，上下文已经积累了不少内容，记忆会产生微妙偏差。花几秒重读比花几分钟修偏划算得多。

遵守项目规范

先看同模块现有代码怎么写的，再动手。代码风格、命名习惯、继承关系、分层结构——模仿现有代码是最可靠的规范来源。如有 CLAUDE.md，严格遵循其中的编码规范。在 SpringBlade 体系中，Boot 和 Cloud 共享统一分层：Controller → Service → Mapper → Wrapper → Entity，差异仅在包路径和路由前缀（Boot 通过 AppConstant.APPLICATION_XXX_NAME 手动拼前缀，Cloud 由网关按服务名自动路由）。

最小变更原则

每个任务只做计划中描述的事。发现"顺手可以优化"的地方，记下来在总结中告诉用户，但不自行改动。未计划的改动是 bug 的温床。

复用优先

编写新代码前，先在项目中搜索是否已有可复用的工具类、基类或配置。尤其在 SpringBlade 体系中，blade-core-tool 和各 Starter 模块提供了大量基础设施，重复造轮子不仅浪费时间，还会引入风格不一致。

构建验证

代码变更后主动执行构建验证。编译不过就立即修，不要想着"后面一起修"——错误会像雪球一样越滚越大。

---

何时降级为直接对话

如果分析后发现：

• 只涉及 1~5 个文件的简单改动
• 不需要拆解任务，直接改就行

主动提示：这个改动比较简单，不需要走规划流程，直接帮你改。 然后直接执行。

何时建议分阶段拆解

如果在规划阶段发现以下信号，建议用户把需求拆成多次会话分阶段推进：

• 任务数量超过 15 个，工作量超出一次会话的合理范围
• 涉及复杂的数据库表结构设计（多表关联、索引策略），需要先单独设计数据模型
• 需要跨多个服务的 API 协调，应当先固定契约再逐服务落地
• 需求本身还不清晰，应先通过对话澄清、对齐理解后再进入 Plan 流程

主动提示：这个需求的复杂度较高，建议先拆成几个独立阶段（如：设计数据模型 → 落地后端 → 补全前端），每个阶段单独走一次 /blade-plan 会更稳。