| name | blade-plan |
| description | SpringBlade 轻量规划执行工作流。将中等复杂度需求快速拆解为「分析规划 → 逐任务执行 → 完成总结」 三步流程，用 Claude Code 内置任务系统追踪进度，全程无辅助文件。适用于新增中等功能模块、修复跨模块 Bug、 中等规模重构、添加新 Starter 等涉及 5~15 个文件变更的开发任务。 当用户说"帮我做一个XX功能"、"这个改动涉及几个文件"、"帮我重构一下XX"、"帮我加个XX"、 "plan"、"规划一下再做"、"先想清楚再写"、"这个稍微有点复杂"等时触发。也可直接使用 /blade-plan 调用。 不适用于简单单文件修改（直接对话即可），也不适用于需要完整架构设计的复杂系统（建议分阶段拆解为多次会话）。 即使用户没有说"plan"，只要需求涉及多文件改动或需要一定设计思考，也应主动建议使用本工作流。
|
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 修复多租户场景下动态数据源切换时连接池泄漏问题
路由逻辑
收到用户输入后：
- 带
--auto 参数：提取需求描述 → 自动模式（规划后直接执行，不等确认）
- 带需求描述：→ 交互模式（规划后等待用户确认）
- 无参数：提示输入需求描述
工作流
用户需求 → [分析与规划] → 确认 → [逐任务执行] → 完成总结
↑
自动模式跳过
三个步骤，一次确认，全程用 Claude Code 内置任务系统追踪进度。
步骤一：分析与规划
目标：理解需求，摸清现状，制定可执行的任务清单。
执行动作：
-
理解需求：
- 解析用户的需求描述，提炼核心功能点
- 识别隐含需求和边界条件
- 如有歧义，先向用户澄清关键问题再继续
-
扫描现状：
- 阅读 CLAUDE.md 了解项目规范（如有）
- 扫描相关模块现有代码，理解代码结构和风格
- 搜索是否有可复用的类、工具方法或已有实现
- 评估改动对现有功能的影响范围
-
制定方案：
- 确定技术实现策略（用什么方式解决问题）
- 识别需要新增和修改的文件
- 将改动拆解为有序的任务列表（按依赖关系排序）
- 任务粒度：一个任务对应一个逻辑完整的改动单元（通常 1~3 个文件）
-
展示规划，格式如下：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 Blade Plan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
需求：{一句话概述}
方案：
{2~4 句话描述技术方案的核心思路，
包括关键的技术选型和架构决策}
任务清单（共 X 个）：
1. {任务标题} — {涉及的文件或模块}
2. {任务标题} — {涉及的文件或模块}
3. {任务标题} — {涉及的文件或模块}
...
影响范围：
新增 X 个文件 | 修改 Y 个文件
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
等待确认或自动推进：
- 交互模式：追加
请确认方案后开始执行，或提出修改意见。 并等待用户回复
- 自动模式：展示规划后直接进入步骤二
- 用户说"可以"/"没问题"/"开始"等视为确认通过
- 用户提出修改意见则调整方案后重新展示
-
创建任务：确认后，使用 TaskCreate 为每个任务创建跟踪条目，便于用户实时看到进度
步骤二：逐任务执行
目标：按计划逐个完成任务，保持纪律性。
对每个任务执行以下循环：
-
TaskUpdate → 标记当前任务为 in_progress
-
加载上下文（上下文锚定）：
- 重新阅读目标文件及其关联代码——即使刚才读过，也要再看一眼
- 查看前序任务的产出文件，确保接续一致
- 模仿同模块现有代码的风格和模式
-
执行编码：
- 严格遵循项目 CLAUDE.md 编码规范（如有）
- 只做当前任务描述的事，不附带额外改动
- 执行前判断是否可借助其他 Blade 技能加速（见「技能协同」）
-
TaskUpdate → 标记当前任务为 completed
-
继续下一个任务
为什么要逐任务而不是一口气全写完？因为每个任务完成后的代码状态是下一个任务的输入。逐步推进让每一步都建立在稳固的基础上，也让用户能实时看到进度。
构建检查点
每完成一组逻辑相关的任务（或每 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 会更稳。
