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 修复多租户场景下动态数据源切换时连接池泄漏问题 路由逻辑 收到用户输入后： 带 --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 会更稳。