blade-plan

---
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 修复多租户场景下动态数据源切换时连接池泄漏问题
```

## 路由逻辑

收到用户输入后：

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 会更稳。`