---
name: "requirements-analysis"
description: >
  This skill should be used when the user or game-dev agent needs to "design a technical plan",
  "write a tech design document", "analyze requirements", "do requirements analysis",
  "做需求分析", "设计技术方案", "写技术设计文档", or "分析需求".
  Provides an 8-step structured requirements analysis workflow that produces a comprehensive
  technical design document from an execution document for UE5 game systems.
---

# 需求分析 Skill

8 步结构化需求分析工作流，从执行文档（执行案）到技术设计文档。为 UE5 游戏系统的程序设计（步骤④）提供系统化的分析方法论。

## 触发条件

- **步骤④自动触发**：game-dev agent 进入程序设计阶段时自动使用此 skill
- **用户手动触发**：用户说"做需求分析"、"设计技术方案"、"写技术设计文档"等时触发

## 输入

按序阅读以下文档，获取完整的上下文信息：

1. **执行文档** (`docs/design/<stage>/<系统名>-执行案.md`) — 行为规则细节（主要输入）
2. **系统设计文档** (`docs/design/<stage>/<系统名>.md`) — 全局上下文
3. **配置表** (`GameConfig/`) — 可调参数
4. **概念文档** (`docs/design/概念草案.md`) — 方向参考（需要理解设计意图时查阅）

---

## 8 步分析工作流

### 步骤①：需求功能点罗列

从执行文档中提取每个行为规则作为功能点，按实现方式分为两大类：

**UE 内置功能**：使用 UE5 引擎原生能力即可覆盖的功能点。典型包括：
- Enhanced Input 输入映射与回调
- SpringArm 摄像机跟随、碰撞处理、Camera Lag
- CMC（CharacterMovementComponent）移动参数配置
- SetViewTargetWithBlend 摄像机切换
- 碰撞检测（SphereComponent / BoxComponent Overlap）
- UMG Widget 生命周期管理
- DataAsset / DataTable 数据配置

**自定义实现**：需要编写 C++ 或蓝图代码的功能点。包括：
- 自定义状态机与状态转换逻辑
- 跨系统协调与事件分发
- 自定义 UI 交互逻辑
- 特殊的游戏规则判定

以表格形式输出，每个功能点标注对应的执行案条目编号。分类原则：UE 内置能力覆盖 80% 以上需求且行为一致 → UE 内置；否则 → 自定义实现。

### 步骤②：功能领域图

识别当前系统由哪些功能模块组成，以及模块之间的交互关系。

**关键约束**：只关注功能领域和领域之间的关系，不细分到类级别。这是自顶向下的模块级设计，在深入类设计之前先建立全局视图。

使用 Mermaid `flowchart` 绘制：
- 使用 `subgraph` 划分层（如输入层、核心层、数据层、表现层）
- 实线 `-->` 表示主数据流 / 同步调用
- 虚线 `-.->` 表示事件通知 / 异步通信
- 配合模块职责说明表格

### 步骤③：类设计图

将功能领域图细化为具体的类设计。展示每个类的关键数据成员和关键接口，以及类之间的关系。

使用 Mermaid `classDiagram` 绘制，必须明确标注关系类型：

| 关系 | 箭头 | UE5 典型场景 |
|------|------|-------------|
| 继承 | `<\|--` | `ACharacter` 的子类 |
| 实现 | `..\|>` | `UInterface` 的实现类 |
| 组合 | `*--` | Character 持有 Component（生命周期绑定） |
| 聚合 | `o--` | 引用其他 Actor/Component（非拥有） |
| 依赖 | `..>` | 方法参数、临时引用 |

同时提供新增类表格、修改类表格、新增蓝图表格。类命名遵循 UE5 前缀规范（`A`/`U`/`I`/`F`/`E`）。

### 步骤④：时序图（条件性）

> ⚠️ 仅当特性满足以下任一条件时绘制：涉及 3+ 个系统协调、有条件分支或循环流程、跨层级通信（UI ↔ 逻辑 ↔ 数据）。简单特性跳过。

使用 Mermaid `sequenceDiagram` 追踪复杂特性的跨系统调用流程：
- 从玩家输入或系统入口开始
- 经过哪些系统的哪些接口
- 到最终完成或返回
- 使用 `activate`/`deactivate` 展示调用栈深度
- 标注关键判断分支

### 步骤⑤：核心数据结构

定义系统所需的枚举、结构体、配置数据。

以 UE5 C++ 头文件风格书写：
- 使用 `UENUM(BlueprintType)` 标记枚举
- 使用 `USTRUCT(BlueprintType)` 标记结构体
- 使用 `UPROPERTY(EditAnywhere, ...)` 标记可配置属性
- 每个字段提供中文注释说明和合理的默认值
- 区分"配置参数"和"运行时状态"

### 步骤⑥：复杂接口描述（条件性）

> ⚠️ 仅当接口有 5+ 个决策分支或协调多个子系统状态时需要。简单接口（纯数据查询、简单赋值）跳过。

对复杂接口，选择最适合的方式描述其执行逻辑：
- **流程图**（Mermaid `flowchart`）：适合有多条件分支和并行路径的逻辑
- **伪代码**：适合有明确顺序步骤、需要展示具体判断条件的逻辑
- **鲁棒图**：适合展示边界/控制/数据三种元素的交互

描述时必须包含：前置检查（快速失败）→ 核心逻辑 → 异步操作标注 → 边界情况处理。

### 步骤⑦：技术难点/风险

识别并评估实现过程中可能遇到的技术难点和风险：

- 按等级分类：🔴 高（可能导致方案不可行）、🟡 中（需要额外工作但可控）、🟢 低（已知解法）
- 每个风险包含：风险描述、详细说明、缓解措施
- 特别关注：UE5 限制、性能瓶颈、跨系统时序问题、数据一致性

### 步骤⑧：工期预估

给出工作量和实现拆分建议：

- **总工期**：以天为单位（X-Y 天范围）
- **代码量**：新增/修改的 C++ 行数 + 蓝图数量
- **实现拆分**：推荐按系统/模块/功能点拆分为可独立验证的子任务，每个子任务标注预估时间、依赖关系、验证方式

拆分原则：每个子任务可在半天到一天内完成，有明确的验证标准，子任务之间依赖关系清晰。

---

## 输出

最终产出为技术设计文档，保存到 `docs/technical/<系统名>-技术方案.md`。

文档必须遵循 `references/output-template.md` 中定义的标准模板结构。8 步分析的结果整合到模板的对应章节中，同时保留现有的必要章节（美术资源需求、数据流、可调参数汇总、文件结构）。

**阶段适配**：
- 原型阶段：步骤②④⑥可适度简化，允许占位描述
- 批量生产阶段：所有步骤必须完整、详细

---

## 条件步骤判定速查

| 步骤 | 激活条件 | 跳过条件 |
|------|---------|---------|
| ④ 时序图 | 3+ 系统协调 / 有分支循环 / 跨层级通信 | 单系统内部 / 纯配置 |
| ⑥ 复杂接口描述 | 5+ 决策分支 / 协调多子系统 / 有异步等待 | 简单查询 / 2-4 分支简单逻辑 |

详细判定启发式参见 `references/diagram-guide.md` 第 3 节。

---

## 参考文件

| 文件 | 内容 | 何时查阅 |
|------|------|---------|
| `references/diagram-guide.md` | Mermaid 语法速查、项目约定、复杂度判定 | 绘制任何图表前查阅 |
| `references/output-template.md` | 完整技术设计文档模板 | 开始写文档前查阅，确保结构完整 |
| `references/examples.md` | 各步骤的注释示例（来自现有技术文档） | 需要参考输出效果时查阅 |