/plan

需求分析与方案设计。当开始新功能或大改动时使用。

需求分析与方案设计

步骤

1. 理解需求（按规模分路径） 使用 AskUserQuestion 向用户确认功能行为、边界、是否有类似功能可参考。

   • 小功能（改动 < 3 文件，无新数据模型）：确认需求后直接进入步骤 2
   • 中大功能（跨模块/新数据模型/新 API）：如果已有 spec.md，直接基于它设计方案；如果没有，建议先运行 /spec。若用户选择跳过，追加结构化提问：
     • 目标用户是谁？要解决什么问题？
     • 核心用户故事（3-7 条）
     • In scope / Out of scope
     • 验收标准（每条用户故事的 Given/When/Then）

   判断改动性质（所有规模均需）：

   • 兼容型（新增功能，不改已有接口）→ 正常流程
   • 破坏型（修改现有 API 签名 / 数据结构 / 公共接口）→ 步骤 3 必须先输出接口变更清单，再设计实现方案

2. 检查现有代码 搜索代码库中已有的类似功能或可复用模块。 列出可复用的组件、工具函数、类型定义。

3. 输出实现方案

   基础格式（所有功能）：

   ## 方案概述
   [一句话描述实现思路]
   
   ## 影响范围
   - 新建文件：[列出]
   - 修改文件：[列出，标注改动点]
   - 依赖变更：[列出新增/移除的包]
   
   ## 实现步骤
   1. [步骤1 - 具体到文件和函数级别]
   2. [步骤2]
   ...
   
   ## 风险点
   - [可能出问题的地方及应对措施]

   中大功能额外在方案开头包含：

   • 目标与非目标 + 用户故事与验收标准 + 范围边界（精简 PRD）
   • 当存在 API 变更时，先定义 API 契约（路径、方法、请求/响应 schema）
   • 大功能附加实现顺序：Foundation（数据模型+类型）→ Core（业务逻辑）→ Integration（模块连接）→ Polish（错误处理+日志+文档）

   破坏型改动（步骤 1 标记为破坏型时）额外在方案最前面输出：

   ## 接口变更清单
   | 变更项 | 变更前 | 变更后 | 受影响的调用方 |
   |--------|--------|--------|--------------|
   | [接口/类型/数据结构] | [原签名] | [新签名] | [文件:函数] |

4. 等待确认

5. 持久化方案

   用户确认方案后，将方案写入 docs/plans/{slug}.md。把步骤 3 的"实现步骤"转化为任务清单（- [ ] 复选框）：

   # {方案名称}
   Status: active
   Progress: 0/{N}
   Date: YYYY-MM-DD
   Feature: {ID}                          ← 可选，关联 features.md
   
   ## 目标
   [从步骤 1 提炼]
   
   ## 任务清单
   - [ ] {步骤 1}（`涉及的文件`）
   - [ ] {步骤 2}
   ...
   
   ## 关键决策
   [重大选型摘要，如有对应 ADR 则链接]

   • slug 语义化命名（如 auth-oauth.md、p1a-outside-in.md）
   • Progress 初始为 0/{任务总数}
   • 更新 docs/plans/README.md 索引表
   • 如果 docs/plans/ 目录不存在则创建

IMPORTANT：

• 方案输出后必须等待用户确认，不要自行开始实现。
• 本 Skill 负责需求分析与方案设计（产出方案文档）。代码级实现规划由 Claude Code 内置 Plan Mode 负责。典型流程：/plan → 审批 → Plan Mode → 审批 → 执行。