HS Req Facilitator Skill

智能需求分析助手 | Intelligent Requirements Facilitator

🤖 开源项目: hs-req-facilitator-skill v2.0.4
👤 苏州核朔智能科技有限公司 | 📧 limian@norkern.com
🌐 www.norkern.com | 📖 文档: README.md

启动流程：激活技能后立即开始执行工作流程

🚀 启动步骤

工作流检查点：按以下顺序执行每个步骤，完成验证后进入下一步

执行规范：

• 执行启动流程：不要只显示”技能已启动”或”等待指令”等消息
• 立即开始：技能激活后立即开始工作流程，避免停顿等待
• 执行顺序：按照步骤顺序执行，确保每步完成并验证

启动后立即执行：

1. 执行步骤0检查（确认工作流规则）
2. 执行步骤1：扫描代码和文档
3. 根据扫描结果决定流程并继续执行

步骤0：工作流检查（首先执行）

执行前检查：确认以下工作流规则

1. Stage 2（需求分析）：完成以下4个子步骤（按顺序执行）：

   • 步骤2.1：读取需求文档和代码文件
   • 步骤2.2：理解项目功能（输出功能概述）
   • 步骤2.3：分析问题和缺失信息（输出模糊点、缺失信息、不一致性）
   • 步骤2.4：列出功能需求清单并展示给用户

2. Stage 3（交互澄清）：执行用户交互

   • Stage 2完成后，立即进入Stage 3
   • 与用户交互（获取补充信息）
   • 即使没有发现问题，也至少进行一次用户交互

3. 用户交互要求：

   • 使用AskUserQuestion：必须使用 AskUserQuestion 工具调用
   • 等待回答：等待用户回答后再继续，不要直接进入下一步
   • 确保交互：在提问后实际等待用户回答

4. Stage 2 验证要求（全部满足）：

   • 步骤2.2输出：项目功能概述、每个需求的实际功能、代码与需求一致性分析
   • 步骤2.3输出：模糊点识别结果、缺失信息识别结果、不一致性识别结果（每个类别至少1个或明确说明”无“）
   • 输出具体分析结果：不要只是说”已理解”或”未发现问题”
   • 步骤2.4输出完整的功能需求清单并展示给用户

步骤1：扫描代码和文档（第一步）

执行步骤：技能启动后立即执行此步骤

立即执行以下命令并查看结果：

# 1. 扫描需求文档
find . -type f \( -name "requirements.md" -o -name "*requirement*.md" -o -name "需求*.md" \) | grep -v node_modules | grep -v ".git"

# 2. 扫描代码文件
find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.java" -o -name "*.go" -o -name "*.rs" \) | grep -v node_modules | grep -v ".git" | head -50

统计结果：

• 需求文档数量：[X]
• 代码文件数量：[Y]

📋 Stage 1: 根据扫描结果决定流程

选择流程：根据扫描结果决定执行哪个流程

• 空项目（没有需求文档）：

  • 使用 AskUserQuestion 询问用户是否要创建需求文档
  • 详细指南：参见项目文档中的空项目引导相关章节

• 多个需求文档：

  • 使用 AskUserQuestion 询问用户是否要合并需求文档
  • 如果用户同意，进入Stage 5（需求文档合并）
  • 详细指南：参见项目文档中的文档合并相关章节

• 有需求文档（常规流程）：

  • 直接进入Stage 2（需求分析），不需要先询问用户
  • 完成Stage 2后，再进入Stage 3（交互澄清）

📋 Stage 2: 需求分析（在交互澄清之前完成）

执行顺序：按以下顺序执行每个步骤

1. 读取需求文档和代码文件
2. 理解项目功能
3. 分析问题和缺失信息（在列出功能需求清单之前完成）
4. 列出功能需求清单（在分析完成后列出并展示给用户）

完成阶段2后，进入阶段3（交互澄清）

流程检查点：

• ✅ Stage 2完成后 → 进入Stage 3（交互澄清）
• ✅ Stage 3完成后 → 进入Stage 4（需求完善）
• 跳过禁止：Stage 2 → 直接进入Stage 4（跳过Stage 3）

📋 使用场景

Use this skill when:

• User asks to “analyze requirements” or “review specifications”
• User mentions “unclear requirements” or “ambiguous specifications”
• User wants to “consolidate multiple requirement documents”
• User needs to “identify missing information” in requirements
• User says “improve requirements quality” or “enhance specifications”
• Working with requirements files (*requirements.md, requirement.md)
• Queries contain keywords: “requirements”, “specs”, “needs analysis”, “clarify”

典型触发场景：

• “完善需求”
• “分析需求文档”
• “澄清不明确的需求”
• “合并需求文档”
• “识别缺失信息”
• “提升需求质量”

🔄 工作流程

📊 工作流程图

┌─────────────────────────────────────────────────────────────────────────────┐
│                          HS-REQ-FACILITATOR 工作流程                          │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────┐
│   Stage 0       │ ◄─── 工作流检查（首先执行）
│  工作流检查      │
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│   Stage 1       │ ◄─── 扫描代码和文档（必需，第一步）
│    扫描          │
│  ├─需求文档      │
│  └─代码文件      │
└───────┬─────────┘
        │
        ▼
┌─────────────────┐
│   决策点 1       │ ◄─── 根据扫描结果决定流程
│  (Scan Results) │
└───────┬─────────┘
        │
        ├─────────────────────────────┬─────────────────────────────┐
        │                             │                             │
        ▼                             ▼                             ▼
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  空项目流程      │         │  多文档流程      │         │  常规流程        │
│  (Empty Project)│         │  (Multi-Docs)   │         │  (Regular)      │
└───────┬─────────┘         └───────┬─────────┘         └───────┬─────────┘
        │                         │                             │
        ▼                         ▼                             ▼
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  AskUserQuestion│         │  AskUserQuestion│         │  直接进入        │
│  "创建需求文档?" │         │  "合并需求文档?" │         │  Stage 2        │
│  ↓             │         │  ↓             │         │                 │
│  [EMPTY-PROJECT]│        │  [同意] ───────→│         │  需求分析        │
│                 │         │  Stage 5       │         │  (MANDATORY)    │
│                 │         │  文档合并       │         │                 │
└─────────────────┘         │                 │         │  ┌─────────────┐
                            └─────────────────┘         │  │ Stage 2.1   │
                                                          │  ├─读取文档    │
                                                          │  └─读取代码    │
                                                          │
                                                          │  ┌─────────────┐
                                                          │  │ Stage 2.2   │
                                                          │  ├─理解功能    │ ◄─── 必须输出项目概述
                                                          │  └─需求分析    │
                                                          │
                                                          │  ┌─────────────┐
                                                          │  │ Stage 2.3   │
                                                          │  ├─模糊点识别  │ ◄─── 必须输出分析结果
                                                          │  ├─缺失信息    │
                                                          │  └─不一致性    │
                                                          │
                                                          │  ┌─────────────┐
                                                          │  │ Stage 2.4   │
                                                          │  ├─需求清单    │ ◄─── 必须展示给用户
                                                          │  └─需求分类    │
                                                          │
                                                          └────────┬────────┘
                                                                   │
                                                                   ▼
                                                          ┌─────────────────┐
                                                          │   Stage 3       │ ◄─── 关键检查点（不能跳过！）
                                                          │  交互澄清        │
                                                          │                  │
                                                          │  🔴 关键阶段     │ ◄─── 不能跳过！
                                                          │                  │
                                                          └────────┬─────────┘
                                                                   │
                                                                   ▼
                                                          ┌─────────────────┐
                                                          │ AskUserQuestion │ ◄─── 必须使用AskUserQuestion工具
                                                          │     工具        │
                                                          │                  │
                                                          │ ├─检测工具可用性 │
                                                          │ ├─生成澄清问题   │
                                                          │ ├─等待用户回答   │ ◄─── 必须等待用户回答！
                                                          │ └─收集回答       │
                                                          └────────┬─────────┘
                                                                   │
                                ┌────────────────────────────────────┘
                                │
                                ▼
                      ┌─────────────────┐
                      │  错误处理流程     │
                      │  (Error Handler) │
                      │                  │
                      │ ├─工具不可用      │ ◄─── 降级到对话方式
                      │   ↓              │
                      │ └─❓ 格式交互     │
                      │                  │
                      │ ├─无响应         │ ◄─── 继续重试
                      │   ↓              │
                      │ └─再次询问       │
                      └────────┬─────────┘
                               │
                               ▼
                      ┌─────────────────┐
                      │   Stage 3       │
                      │   继续执行       │
                      │                  │
                      │ ├─调整问题       │
                      │ ├─持续交互       │ ◄─── 至少一次交互
                      │ └─完成澄清       │
                      └────────┬─────────┘
                               │
                               ▼
                      ┌─────────────────┐
                      │   Stage 4       │ ◄─── 条件：Stage 3完成后
                      │  需求完善        │
                      │  (Optional)     │
                      └────────┬─────────┘
                               │
                               ▼
                      ┌─────────────────┐
                      │ Spec-Workflow   │
                      │   集成          │
                      │                  │
                      │ ├─检测项目结构    │
                      │ ├─生成需求文档    │
                      │ └─更新规格       │
                      └─────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                              流程说明                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  🔴 关键阶段: Stage 3 是关键阶段，不能跳过                            │
│                                                                             │
│  🔵 AskUserQuestion: 必须使用 AskUserQuestion 工具与用户交互                 │
│     - 如果工具可用：使用 AskUserQuestion 工具                               │
│     - 如果工具不可用：降级到对话方式（❓ 格式）                              │
│                                                                             │
│  ✓ 检查点: 关键检查点，等待用户回答后才能继续                      │
│                                                                             │
│  📋 DECISION POINTS:                                                       │
│     1. 扫描结果 → 空项目/多文档/常规流程                                    │
│     2. Stage 2 → 必须完成所有4个子步骤                                      │
│     3. Stage 3 → 交互澄清（至少一次交互）                                │
│     4. Stage 4 → 必须在Stage 3完成后执行                                    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Stage 1: 根据扫描结果决定流程

根据步骤1的扫描结果，决定执行哪个流程：

• 空项目（没有需求文档）：

  • 使用 AskUserQuestion 询问用户是否要创建需求文档
  • 详细指南：参见项目文档中的空项目引导相关章节

• 多个需求文档：

  • 使用 AskUserQuestion 询问用户是否要合并需求文档
  • 如果用户同意，进入阶段5（需求文档合并）
  • 详细指南：参见项目文档中的文档合并相关章节

• 常规流程（有需求文档）：

  • 直接进入Stage 2（需求分析），不需要先询问用户
  • 完成Stage 2后，再进入Stage 3（交互澄清）

Stage 2: 需求分析（必须在交互澄清之前完成）

执行要求：此阶段按以下顺序执行，每个步骤输出明确结果，完成后进入Stage 3（交互澄清）！

执行前检查：在开始Stage 2之前，确认已执行步骤1（扫描代码和文档）并获得扫描结果！

步骤2.1：读取需求文档和代码文件（必须执行）

执行要求：实际读取文件，不能跳过：

1. 查找并读取需求文档：

   # 必须执行：查找需求文档
   find . -type f \( -name "requirements.md" -o -name "*requirement*.md" -o -name "需求*.md" \) | grep -v node_modules | grep -v ".git"
   
   # 必须执行：读取找到的需求文档
   # 使用 Read 工具读取每个找到的需求文档
   

2. 读取关键代码文件：

   # 必须执行：查找代码文件
   find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.java" -o -name "*.go" -o -name "*.rs" \) | grep -v node_modules | grep -v ".git" | head -20
   
   # 必须执行：读取关键代码文件（至少5-10个文件）
   # 使用 Read 工具读取主要业务逻辑文件
   

3. 如果项目使用 spec-workflow，获取上下文：

   • 尝试使用 spec-workflow MCP 工具获取模板和上下文
   • 如果MCP不可用，使用 spec-workflow CLI 或直接生成标准格式

验证点：实际读取文件内容，不能只是列出文件名！

步骤2.2：理解项目功能（关键步骤，不能跳过）

重要步骤：先理解项目的实际功能，再分析缺失信息！

⚠️ 执行前检查：

• 步骤2.1已完成（已读取需求文档和代码文件）
• 已准备好开始理解项目功能

📌 核心要求：此步骤必须向用户展示项目功能概述！

⚠️ 重要：用户启动技能后，需要知道被分析的项目是什么、解决什么问题、主要功能和技术栈，这样才能理解后续的需求分析。

必须输出以下内容（每个部分都必须有具体输出并展示给用户，不能为空）：

1. 项目整体功能描述（必须输出并展示给用户，不能只是说”已理解”）：

   ## 项目功能概述
   
   基于读取的代码和文档，分析并回答：
   
   ### 1. 项目是什么？
   [明确说明：这个项目是什么？它的核心功能是什么？]
   
   ### 2. 项目解决的问题
   [明确说明：这个项目解决什么问题？为谁服务？]
   
   ### 3. 主要功能模块
   [列出主要功能模块，每个模块说明其功能]
   - 模块1：[功能描述]
   - 模块2：[功能描述]
   ...
   
   ### 4. 项目技术栈
   [列出项目使用的主要技术栈]
   

   重要要求：

   • ✅ 必须向用户展示这个项目功能概述，让用户了解被分析的软件是干什么的
   • ✅ 输出明确的项目功能描述，不能只是说”已理解”
   • ✅ 确保用户能够理解项目的基本情况后再继续分析

2. 每个需求的实际功能（必须输出，必须分析每个需求）：

   ## 需求功能分析
   
   基于对项目的理解，分析每个需求：
   
   ### 需求1: [需求标题或编号]
   - **需求描述**：[需求文档中的原始描述]
   - **实际功能**：[这个需求对应的实际功能是什么]
   - **功能行为**：[这个功能做什么、怎么做、具体行为是什么]
   - **输入输出**：[输入是什么、输出是什么、参数格式]
   - **代码实现情况**：[代码中是否已实现、如何实现的、代码位置]
   - **实现状态**：[已实现/未实现/部分实现]
   
   ### 需求2: [需求标题或编号]
   ...
   
   **执行要求：分析所有需求，不能跳过任何需求！**
   

3. 代码与需求的一致性（必须输出，必须对比代码和文档）：

   ## 代码与需求一致性分析
   
   对比代码实现和需求文档：
   
   ### 代码中已实现但需求文档中未描述的功能
   - 功能1：[功能名称]
     * 代码位置：[文件路径和行号]
     * 功能描述：[功能做什么]
     * 建议：[是否应该在需求文档中补充]
   
   ### 需求文档中描述但代码中未实现的功能
   - 功能1：[功能名称]
     * 需求位置：[需求文档中的位置]
     * 功能描述：[需求描述的功能]
     * 状态：[计划实现/已废弃/待实现]
   
   ### 代码和需求一致的功能
   - 功能1：[功能名称]
     * 需求位置：[需求文档中的位置]
     * 代码位置：[代码中的位置]
     * 一致性说明：[说明为什么一致]
   

   验证点：输出明确的对比结果，不能只是说”已对比”！

扩展2.2.1：代码注释分析（自动提取隐含需求）

执行位置：在步骤2.2完成后，步骤2.3之前执行

功能说明：从代码注释中提取隐含的业务需求、技术约束、设计决策等文档中未明确说明的信息。

执行步骤：

步骤A：扫描代码注释

• 扫描所有支持的代码文件（.js, .ts, .py, .java, .go, .rs, .cpp, .c#）
• 提取所有注释内容（行内注释、块注释、文档注释）
• 识别注释中的关键词和模式

步骤B：分析注释内容 使用AI分析注释，提取以下类型的信息：

• TODO/FIXME注释：未完成的功能或需要修复的问题
• 业务逻辑注释：解释为什么这样做的业务原因
• 技术决策注释：为什么选择特定技术或架构
• 约束说明注释：性能、安全、兼容性等约束
• 设计模式注释：使用的设计模式和意图
• 边缘情况注释：特殊处理逻辑和原因

步骤C：映射到需求类型 将提取的信息映射到标准需求类型：

• 功能需求：未实现的功能、预期行为
• 非功能需求：性能、安全、可靠性要求
• 约束条件：技术约束、业务规则
• 假设条件：隐含的假设和前置条件

输出格式：

## 代码注释分析结果

### 从代码注释提取的隐含需求

#### 功能相关注释
1. **[文件名:行号]** [注释摘录]
   - **提取的需求**：[描述]
   - **需求类型**：[功能/非功能/约束]
   - **优先级**：[P0/P1/P2]
   - **实现状态**：[已实现/未实现/部分实现]
   - **代码位置**：[具体位置]

#### 技术约束注释
1. **[文件名:行号]** [注释摘录]
   - **约束类型**：[性能/安全/兼容/其他]
   - **约束描述**：[具体要求]
   - **影响范围**：[影响的模块或功能]
   - **建议**：[如何处理]

#### 设计决策注释
1. **[文件名:行号]** [注释摘录]
   - **决策内容**：[做了什么决策]
   - **决策原因**：[为什么这样做]
   - **替代方案**：[考虑过的其他方案]
   - **影响**：[对系统的影响]

#### 待办事项注释
1. **[文件名:行号]** TODO: [内容]
   - **任务描述**：[需要做什么]
   - **优先级**：[高/中/低]
   - **预计工作量**：[大/中/小]
   - **关联功能**：[与哪个功能相关]

### 统计摘要
- 总注释数：[X]
- 发现隐含需求数：[Y]
- 其中功能需求：[A]个
- 其中非功能需求：[B]个
- 其中技术约束：[C]个
- 待办事项：[D]个

提示词模板：

你是一个需求分析专家。请分析以下代码注释，提取其中的隐含需求。

代码文件：{file_path}
注释内容：
{comment_text}

请从以下维度分析：
1. 业务需求：注释中暗示的用户需求或业务规则
2. 功能需求：需要实现但未文档化的功能
3. 非功能需求：性能、安全、可靠性等要求
4. 技术约束：技术选择的原因和限制
5. 设计决策：架构或实现决策的理由
6. 待办事项：TODO、FIXME、HACK等标记

请以JSON格式返回：
{
  "implied_requirements": [
    {
      "type": "functional|non-functional|constraint",
      "category": "业务需求|功能需求|性能|安全|约束|决策|待办",
      "description": "需求描述",
      "priority": "P0|P1|P2",
      "rationale": "提取依据",
      "code_location": "文件:行号",
      "implementation_status": "已实现|未实现|部分实现"
    }
  ],
  "statistics": {
    "total_comments": 0,
    "implied_requirements_count": 0,
    "functional_count": 0,
    "non_functional_count": 0,
    "constraints_count": 0,
    "todo_count": 0
  }
}

步骤2.3：分析问题和缺失信息（必需，必须在列出功能需求清单之前完成）

执行要求：此步骤不能跳过！必须基于步骤2.2的功能理解来分析问题！

⚠️ 执行前检查：

• 步骤2.1已完成（已读取需求文档和代码文件）
• 步骤2.2已完成（已理解项目功能并输出功能概述）
• 已准备好开始分析问题和缺失信息

必须输出以下内容（每个部分都必须有具体输出，不能为空）：

1. 模糊点识别（必须输出，至少列出1个或明确说明”无“）：

   ## 模糊点识别结果
   
   基于功能理解，识别以下模糊点：
   
   模糊点1：[具体描述]
   - 位置：[需求文档中的位置，如：requirements.md 第X行]
   - 问题：[为什么模糊、缺失什么信息]
   - 是否为误报：[代码实现是否已经说明了这部分信息]
   - 如何修复：[需要什么信息来修复]
   
   模糊点2：[具体描述]
   ...
   
   如果未发现模糊点，必须明确说明：
   "经过详细分析，未发现模糊点。代码实现和需求文档都清晰明确。"
   

2. 缺失信息识别（必须输出，至少列出1个或明确说明”无“）：

   ## 缺失信息识别结果
   
   基于功能理解，识别以下缺失信息：
   
   缺失信息1：[缺少什么，如：验收标准、输入输出定义、错误处理等]
   - 关联需求：[哪个需求缺少，引用具体需求名称或编号]
   - 为什么是问题：[为什么需要这个信息，对功能理解的影响]
   - 是否为误报：[代码实现是否已经说明了，如果是误报请说明原因]
   - 如何修复：[需要什么信息来修复]
   
   缺失信息2：[缺少什么]
   ...
   
   如果未发现缺失信息，必须明确说明：
   "经过详细分析，未发现缺失信息。所有功能需求都有完整的信息。"
   

3. 不一致性识别（必须输出，至少列出1个或明确说明”无“）：

   ## 不一致性识别结果
   
   对比代码和文档，识别以下不一致：
   
   不一致1：[描述不一致的地方]
   - 代码中：[代码中如何实现的，引用具体代码位置]
   - 文档中：[文档中如何描述的，引用具体文档位置]
   - 影响：[这种不一致对功能理解的影响]
   - 建议：[如何修复，建议保留代码实现还是文档描述]
   
   不一致2：[描述不一致的地方]
   ...
   
   如果未发现不一致，必须明确说明：
   "经过详细对比，未发现不一致。代码实现与需求文档完全一致。"
   

验证点（全部满足）：

• ✅ 必须输出具体的模糊点、缺失信息和不一致性（每个类别至少1个或明确说明”无“）
• ✅ 不能只是说”没有发现问题”，必须对每个类别明确说明
• ✅ 每个识别到的问题都必须包含：位置、问题描述、是否为误报、如何修复
• ✅ 如果没有发现问题，必须明确说明：”经过分析，未发现模糊点、缺失信息或不一致性。”
• ✅ 输出格式必须清晰，便于后续生成澄清问题

常见错误示例（避免）：

• ❌ “未发现问题”（太笼统，必须分类说明）
• ❌ “需求文档很完善”（必须明确说明每个类别的情况）
• ❌ 跳过此步骤直接进入步骤2.4（禁止）

步骤2.4：列出功能需求清单（必需，必须在分析完成后列出并展示给用户）

执行条件：完成步骤2.2和2.3后，才能执行此步骤！

必须输出以下内容：

## 功能需求清单

### 核心功能需求（P0）
1. [功能名称]
   - 功能描述：[这个功能做什么]
   - 功能行为：[这个功能怎么做]
   - 输入输出：[输入是什么、输出是什么]
   - 代码实现情况：[已实现/未实现/部分实现]
   - 需求文档位置：[文档中的位置]

2. [功能名称]
   ...

### 重要功能需求（P1）
...

### 一般功能需求（P2）
...

### 非功能性需求
- 性能需求：[列出]
- 安全需求：[列出]
- 可靠性需求：[列出]

验证点：输出完整的功能需求清单，包含所有功能需求和分类！

关键检查点：Stage 2完成后，必须进入Stage 3（交互澄清），不能跳过！

详细指南：参见项目文档中的需求分析相关章节

Stage 3: 交互澄清（通过AskUserQuestion与用户交互补充需求）

重要阶段，不能跳过！

重要：

• ✅ 必须在Stage 2完成后才能进入此阶段
• ✅ 不能在Stage 2之后直接进入Stage 4（需求完善）
• ✅ 必须通过 AskUserQuestion 工具与用户交互，补充缺失的需求信息
• ✅ 基于Stage 2的分析结果（功能需求清单和问题分析）生成澄清问题
• ✅ 必须至少进行一次 AskUserQuestion 交互，即使分析结果很完善

执行检查清单：

• Stage 2已完成（步骤2.1-2.4全部完成）
  • 步骤2.1：已读取需求文档和代码文件
  • 步骤2.2：已理解项目功能并输出功能概述
  • 步骤2.3：已分析问题和缺失信息（模糊点、缺失信息、不一致性）
  • 步骤2.4：已列出功能需求清单并展示给用户
• 基于Stage 2的分析结果生成了澄清问题
• 使用 AskUserQuestion 工具与用户交互
• 收集了用户回答（必须等待用户回答，不能直接继续）
• 基于用户回答调整了后续问题（如需要）
• 持续交互直到所有关键问题都得到回答

注意：完成Stage 3的所有交互后，才能进入Stage 4（需求完善）！

1. 基于AI分析结果生成澄清问题：

   • 先理解每个需求的实际功能（基于功能概述）
   • 针对具体功能问问题，而不是通用的检查清单
   • 问题应该基于功能的实际行为，而不是模板化的问题
   • 针对功能需求清单中缺失的信息生成问题

2. 使用 AskUserQuestion 工具与用户交互（必需，不能跳过）：

   执行要求：必须与用户交互，不能跳过此步骤！

   AskUserQuestion 工具调用方式：

   必须使用 AskUserQuestion 工具调用，格式：
     AskUserQuestion({
       questions: [
         {
           header: "澄清问题",
           question: "[具体问题]",
           options: [
             {label: "[选项1]", description: "[描述]"},
             {label: "[选项2]", description: "[描述]"},
             {label: "[选项3]", description: "[描述]"},
             {label: "[选项4]", description: "[描述]"}
           ],
           multiSelect: false
         }
       ]
     })
   
     然后必须等待用户回答后再继续。
   

   重要说明：

   • 使用 questions 数组（单元素数组）
   • 每个问题必须有 header（简短标签，≤12字符）
   • 提供2-4个 options（选项列表）
   • 设置 multiSelect 为false（单选）或true（多选）
   • 等待用户回答，不能跳过

   ⚠️ 交互要求：

   • 如果有问题（步骤2.3中识别到模糊点、缺失信息或不一致性）：

     • 必须基于功能需求清单和问题分析结果，生成澄清问题
     • 必须逐个询问缺失的信息，补充需求
     • 必须至少询问3-5个关键问题
     • 必须等待用户回答每个问题后再继续

   • 如果没有问题（步骤2.3中未发现任何问题）：

     • 必须明确告知用户：”经过分析，未发现模糊点、缺失信息或不一致性。”
     • 然后必须询问：”是否要添加新需求？或直接进入下一步？”
     • 必须等待用户回答

   注意：无论是否有问题，都至少进行一次用户交互！

   交互后记录用户回答，基于回答调整后续问题或进入下一步！

3. 收集用户回答，调整后续问题：

   • 记录用户回答
   • 基于用户回答调整后续问题
   • 持续交互直到所有关键问题都得到回答

详细指南：参见项目文档中的问题生成相关章节

Stage 4: 需求完善（集成到spec-workflow）

执行条件：Stage 3（交互澄清）完成后才能进入此阶段！

重要：无论项目是否使用 spec-workflow，都按照 spec-workflow 格式处理需求文档。

1. 整合信息：结合原始需求文档、用户澄清回答、代码实现情况、功能需求清单

2. 生成完善后的需求：

   • 明确用户故事格式（As a [role], I want [feature], so that [benefit]）
   • 补充详细的验收标准（EARS 格式：WHEN [condition] THEN [system] SHALL [response]）
   • 添加业务价值说明
   • 按照 spec-workflow 格式生成需求文档（无论项目是否使用 spec-workflow）

3. 检测和处理 spec-workflow 集成：

   • 检测项目是否使用 spec-workflow（检查 .spec-workflow 目录）
   • 如果项目使用 spec-workflow：
     • 尝试使用 spec-workflow MCP 工具获取模板和上下文
     • 如果MCP不可用，使用 spec-workflow CLI 或直接生成标准格式
     • 更新 .spec-workflow/specs/*/requirements.md
   • 如果项目未使用 spec-workflow：
     • 自动按照 spec-workflow 格式生成需求文档
     • 自动创建 .spec-workflow/specs/[feature-name]/requirements.md

扩展4.1：需求自动分类（智能分类与优先级评估）

执行位置：Stage 4中的可选增强功能，在生成完善需求后执行

功能说明：自动对需求进行智能分类、评估优先级、识别依赖关系、生成标签，提升需求管理效率。

执行步骤：

步骤4.1.1：智能分类

• 分析每个需求的语义内容
• 分类需求类型：功能需求/非功能需求/业务需求/技术需求
• 细分功能类别：用户交互/业务逻辑/数据处理/系统集成/其他
• 评估业务价值（1-10分）
• 评估技术复杂度（1-10分）

步骤4.1.2：优先级评估 基于多维度计算综合优先级：

• 业务价值权重：40%
• 技术复杂度权重：25%（复杂度越低分越高）
• 资源投入权重：20%（投入越少分越高）
• 紧急程度权重：15%
• 综合评分 = (业务价值×0.4 + (10-复杂度)×0.25 + (10-投入)×0.2 + 紧急度×0.15) × 10
• 优先级分级：
  • P0（80-100分）：关键需求，必须立即处理
  • P1（60-79分）：重要需求，近期需要处理
  • P2（40-59分）：一般需求，中期规划
  • P3（0-39分）：低优先级，长期规划

步骤4.1.3：模块映射 将需求映射到功能模块：

• 用户管理模块
• 内容管理模块
• 交易模块
• 数据分析模块
• 系统管理模块
• 其他自定义模块

步骤4.1.4：依赖关系识别 识别需求间的依赖关系：

• 前置依赖：A需求必须在B需求之前完成
• 后续依赖：A需求依赖B需求的完成
• 并行依赖：A和B可以同时进行
• 互斥依赖：A和B不能同时存在

步骤4.1.5：标签生成 为每个需求生成标签：

• 技术标签：基于使用的技术栈
• 业务标签：基于业务领域
• 特性标签：新增功能/改进/修复
• 状态标签：已计划/进行中/已完成/已放弃

输出格式：

## 需求自动分类结果

### 需求分类概览
- 总需求数：[X]个
- 功能需求：[A]个（[B]%）
- 非功能需求：[C]个（[D]%）
- 业务需求：[E]个（[F]%）
- 技术需求：[G]个（[H]%]

### 优先级分布
- P0（关键）：[X]个需求
- P1（重要）：[Y]个需求
- P2（一般）：[Z]个需求
- P3（低优先级）：[W]个需求

### 详细分类结果

#### 需求 REQ-[编号]: [需求标题]
- **分类信息**：
  - 类型：[功能/非功能/业务/技术]
  - 类别：[用户交互/业务逻辑/数据处理/系统集成]
  - 模块归属：[模块名称] (置信度：[X]%)

- **优先级评估**：
  - 综合评分：[X]/100
  - 优先级：[P0/P1/P2/P3]
  - 评估因子：
    * 业务价值：[X]/10
    * 技术复杂度：[X]/10
    * 资源投入：[X]/10
    * 紧急程度：[X]/10

- **依赖关系**：
  - 前置依赖：[REQ-XXX, REQ-YYY]
  - 后续依赖：[REQ-ZZZ]
  - 并行依赖：[REQ-AAA]
  - 互斥依赖：[REQ-BBB]

- **标签**：
  - 技术标签：[标签1, 标签2]
  - 业务标签：[标签3, 标签4]
  - 特性标签：[新增功能/改进/修复]
  - 状态标签：[已计划]

### 模块依赖图

[模块A] → [模块B] → [模块C] ↓ ↓ [模块D] → [模块E]

### 优先级矩阵

高价值低复杂度 │ 高价值高复杂度 ──────────────┼────────────── P0 │ P1 ──────────────┼────────────── 低价值低复杂度 │ 低价值高复杂度 P2 │ P3

提示词模板：

你是一个需求分类专家。请分析以下需求，进行智能分类和优先级评估。

需求描述：
{requirement_text}

请从以下维度分析：
1. 需求类型：功能需求/非功能需求/业务需求/技术需求
2. 功能类别：用户交互/业务逻辑/数据处理/系统集成/其他
3. 业务价值：1-10分（10分最高）
4. 技术复杂度：1-10分（10分最复杂）
5. 资源投入：1-10分（10分投入最多）
6. 紧急程度：1-10分（10分最紧急）

请以JSON格式返回：
{
  "classification": {
    "type": "functional|non-functional|business|technical",
    "category": "用户交互|业务逻辑|数据处理|系统集成|其他",
    "module": "模块名称",
    "module_confidence": 0.0-1.0
  },
  "priority": {
    "business_value": 1-10,
    "tech_complexity": 1-10,
    "resource_cost": 1-10,
    "urgency": 1-10,
    "overall_score": 0-100,
    "priority_level": "P0|P1|P2|P3",
    "reasoning": "评估理由"
  },
  "dependencies": {
    "prerequisites": ["REQ-XXX"],
    "dependents": ["REQ-YYY"],
    "parallel": ["REQ-ZZZ"],
    "mutual_exclusive": ["REQ-AAA"]
  },
  "tags": {
    "technology": ["标签"],
    "business": ["标签"],
    "feature": "新增功能|改进|修复",
    "status": "已计划|进行中|已完成|已放弃"
  }
}

Stage 5: 需求文档合并（多个需求文档时）

触发条件：在Stage 1（根据扫描结果决定流程）中，如果检测到多个需求文档，进入此阶段。

重要：

• ✅ 必须在用户确认后才执行合并
• ✅ 合并后的文档必须保存到 spec-workflow 格式的需求文档中
• ✅ 删除所有已合并的需求文档，只保留合并后的文档，保证只有一份文档
• ✅ 删除文档前必须向用户确认要删除的文档列表

执行流程：

1. 识别需要合并的文档：

   • 查找所有需求文档（.spec-workflow/specs/*/requirements.md、根目录的 requirements.md、docs/ 目录下的需求文档等）
   • 使用 AI 分析文档内容，识别重复、冲突和互补的需求

2. 生成合并方案：

   • 基于文档分析结果，生成合并方案
   • 建议合并到哪个文档（优先建议 spec-workflow 格式的需求文档）
   • 如何处理重复需求、冲突需求

3. 使用 AskUserQuestion 确认合并（必需）：

   • 询问用户是否要合并多个需求文档
   • 确认合并方案
   • 确认如何处理重复和冲突的需求
   • 确认合并后的文档保存位置

4. 执行合并：

   • 基于用户确认的合并方案，执行合并
   • 保留所有重要信息，去除重复内容
   • 解决冲突需求（基于用户选择）

5. 保存合并后的文档并删除其他文档（必需）：

   • 按照 spec-workflow 格式生成合并后的文档（无论项目是否使用 spec-workflow）
   • 保存到 spec-workflow 格式的需求文档：
     • 如果项目使用 spec-workflow：保存到 .spec-workflow/specs/[feature-name]/requirements.md 或 .spec-workflow/requirements.md
     • 如果项目未使用 spec-workflow：自动创建 .spec-workflow/specs/[feature-name]/requirements.md
   • 删除所有已合并的需求文档（删除前向用户确认要删除的文档列表）
   • 只保留合并后的文档，保证只有一份文档

详细指南：参见项目文档中的文档合并相关章节

Stage 8: 用户画像分析（理解目标用户）

执行位置：Stage 4（需求完善）完成后可选执行，或作为独立分析功能

功能说明：从需求文档中自动提取和分析用户角色、特征、场景、目标和痛点，生成结构化用户画像，帮助团队更好地理解目标用户。

执行步骤：

步骤8.1：用户角色提取

• 扫描需求文档中的角色关键词
• 识别角色类型：最终用户/管理员/运营人员/客服人员/财务人员/开发人员/测试人员
• 判断用户层级：高级用户/普通用户/初级用户/游客
• 估算用户占比

步骤8.2：用户特征分析 分析每个角色的特征：

• 人口统计特征：年龄段、性别倾向、地域分布、职业背景
• 行为特征：使用频率、使用时长、使用场景、技术熟练度
• 需求特征：功能需求、性能需求、安全需求、体验需求

步骤8.3：用户场景分析

• 识别主要场景（核心使用流程）
• 识别次要场景（辅助功能）
• 识别边缘场景（异常处理）
• 每个场景包含：目标、前置条件、操作流程、期望结果、使用频率、重要程度

步骤8.4：用户目标提取 提取三类目标：

• 业务目标：与工作/业务相关的目标
• 体验目标：与使用体验相关的目标
• 个人目标：与个人价值相关的目标

步骤8.5：用户痛点识别 识别三类痛点：

• 效率痛点：操作繁琐、流程冗长等
• 体验痛点：界面不友好、响应慢等
• 业务痛点：成本高、维护困难等
• 评估痛点严重程度（高/中/低）

步骤8.6：生成用户画像 整合所有信息，生成结构化用户画像文档

输出格式：

## 用户画像分析结果

### 用户角色概览
- 识别用户角色：[X]种
- 主要角色：[角色1] ([占比]%), [角色2] ([占比]%)
- 用户层级分布：高级用户[X]%, 普通用户[Y]%, 初级用户[Z]%

### 详细用户画像

#### 用户画像 1: [角色名称]
**基本信息**：
- 用户角色：[类型]
- 用户层级：[层级]
- 用户占比：[X]%
- 主要部门：[部门]

**特征描述**：
- **人口统计特征**：
  - 年龄段：[青年/中年/老年]
  - 性别倾向：[男性/女性/中性]
  - 地域分布：[一线/二线/三线/海外]
  - 职业背景：[职业描述]

- **行为特征**：
  - 使用频率：[高频/中频/低频]
  - 使用时长：[长时间/短时间/碎片化]
  - 使用场景：[工作/生活/学习/娱乐]
  - 技术熟练度：[专家/熟练/一般/新手]

- **需求特征**：
  - 功能需求：[需求列表]
  - 性能需求：[需求列表]
  - 安全需求：[需求列表]
  - 体验需求：[需求列表]

**使用场景**：
1. **场景1: [场景名称]**
   - 目标：[想要达成什么]
   - 前置条件：[使用前需要什么]
   - 操作流程：[具体步骤]
   - 期望结果：[预期得到什么]
   - 使用频率：[高/中/低]
   - 重要程度：[P0/P1/P2]

**用户目标**：
- **业务目标**：
  - [目标1]
  - [目标2]

- **体验目标**：
  - [目标1]
  - [目标2]

- **个人目标**：
  - [目标1]
  - [目标2]

**用户痛点**：
- **效率痛点**：
  - [痛点1]
  - [痛点2]

- **体验痛点**：
  - [痛点1]
  - [痛点2]

- **业务痛点**：
  - [痛点1]
  - [痛点2]

- **严重程度**：[高/中/低]

**需求优先级**：
- **P0 (核心需求)**：
  - [需求1]
  - [需求2]

- **P1 (重要需求)**：
  - [需求1]
  - [需求2]

- **P2 (一般需求)**：
  - [需求1]
  - [需求2]

### 用户画像可视化

#### 角色分布

[角色1] ████████████████████ 70% [角色2] ████████ 20% [角色3] ██ 10%

#### 特征雷达图（ASCII）

技术熟练度 /
/
使用频率/ \访问时段 /
/ \

提示词模板：

你是一个用户画像分析专家。请分析以下需求文档，提取用户画像信息。

需求文档内容：
{requirements_text}

请从以下维度分析：

1. 用户角色提取：
   - 识别所有用户角色
   - 判断用户层级
   - 估算用户占比

2. 用户特征分析：
   - 人口统计特征
   - 行为特征
   - 需求特征

3. 用户场景分析：
   - 主要场景（3-5个）
   - 每个场景的详细信息

4. 用户目标提取：
   - 业务目标
   - 体验目标
   - 个人目标

5. 用户痛点识别：
   - 效率痛点
   - 体验痛点
   - 业务痛点

请以JSON格式返回：
{
  "personas": [
    {
      "basic_info": {
        "name": "角色名称",
        "role_type": "end_user|admin|operator|cs|finance|developer|tester",
        "user_level": "power|regular|novice|guest",
        "department": "部门",
        "percentage": 0.0-100.0
      },
      "characteristics": {
        "demographics": {
          "age_group": "young|middle_aged|elderly",
          "gender_tendency": "male|female|neutral",
          "region": "tier1|tier2|tier3|overseas",
          "profession": "职业描述"
        },
        "behavioral": {
          "frequency": "high|medium|low",
          "duration": "long|short|fragmented",
          "scenario": "work|life|study|entertainment",
          "tech_proficiency": "expert|proficient|average|novice"
        },
        "needs": {
          "functional": ["需求"],
          "performance": ["需求"],
          "security": ["需求"],
          "experience": ["需求"]
        }
      },
      "scenarios": [
        {
          "name": "场景名称",
          "goal": "目标",
          "prerequisites": ["条件"],
          "steps": ["步骤"],
          "expected_result": "期望结果",
          "frequency": "high|medium|low",
          "importance": "P0|P1|P2"
        }
      ],
      "goals": {
        "business": ["目标"],
        "experience": ["目标"],
        "personal": ["目标"]
      },
      "pain_points": {
        "efficiency": ["痛点"],
        "experience": ["痛点"],
        "business": ["痛点"],
        "severity": "high|medium|low"
      },
      "requirements": {
        "p0": ["需求"],
        "p1": ["需求"],
        "p2": ["需求"]
      }
    }
  ],
  "statistics": {
    "total_personas": 0,
    "total_scenarios": 0,
    "total_pain_points": 0
  }
}

📋 重要原则

1. 先扫描，后分析：技能启动时先扫描项目的代码和文档（步骤1），然后根据扫描结果决定流程
2. 先分析，后交互：对于常规流程，必须先完成阶段2（需求分析：分析问题和缺失信息 + 列出功能需求清单），然后才能进入阶段3（交互澄清）
3. 交互澄清不可跳过：阶段3（交互澄清）是必需阶段，必须在阶段2完成后执行，不能在阶段2之后直接进入阶段4
4. 分析完成后列出功能需求清单：阶段2必须先分析问题和缺失信息，然后在分析完成后列出功能需求清单并展示给用户
5. 通过AskUserQuestion交互补充需求：阶段3必须通过 AskUserQuestion 工具与用户交互，补充缺失的需求信息
6. 集成到spec-workflow：无论项目是否使用 spec-workflow，都按照 spec-workflow 格式处理需求文档
7. 必须使用 AskUserQuestion 工具：所有用户交互都必须通过 AskUserQuestion 工具进行，不能只是输出文本
8. 严格按照顺序执行：不能跳过步骤1（扫描）、阶段2（需求分析）或阶段3（交互澄清）
9. 完全AI驱动：不使用正则表达式，完全依赖 Claude 的 AI 理解能力
10. 分析代码和文档：不仅要分析需求文档，还要分析代码文件，理解已实现的功能

🛠️ 使用的工具

• Read: 读取需求文档和代码文件
• Bash: 查找文件、执行命令
• AskUserQuestion: 与用户交互，澄清需求（必需）
• Write: 更新和完善需求文档
• spec-workflow MCP 或 CLI: 访问spec-workflow模板和上下文（如果可用），否则直接生成标准格式

📚 详细指南

• 空项目引导: 参见项目文档中的空项目引导相关章节
• 需求分析: 参见项目文档中的需求分析相关章节
• 问题生成: 参见项目文档中的问题生成相关章节
• 需求完善: 参见项目文档中的需求完善相关章节
• 需求文档合并: 参见项目文档中的文档合并相关章节
• Spec-Workflow 集成: 参见项目文档中的集成相关章节

📝 执行示例

示例: 合并需求文档

用户: "合并需求文档" 或使用技能

ä½ :

智能需求分析助手 | Intelligent Requirements Facilitator

👤 作者: 苏州核朔智能科技有限公司
📖 文档: README.md | 🤝 贡献: CONTRIBUTING.md
📧 limian@norkern.com | 🌐 www.norker.com
🐛 Issues: [GitHub Issues](https://github.com/damienCronw/hs-req-facilitator-skill/issues)

⚡ 版本: v2.0.2

🚀 开始执行需求文档合并流程...

📂 步骤1: 扫描代码和文档（必需）...

[必须执行 find 命令扫描文档和代码]
[统计结果：发现3个需求文档和150个代码文件]

📋 步骤2: 根据扫描结果决定流程...

[检测到多个需求文档：requirements.md, docs/user-requirements.md, docs/api-requirements.md]

AskUserQuestion: "我发现项目中有3个需求文档，内容有重复。建议合并为1个文档。是否要开始合并？"

用户: "是的，合并"

📋 阶段5: 需求文档合并...

步骤1: 识别需要合并的文档
  - requirements.md
  - docs/user-requirements.md
  - docs/api-requirements.md

步骤2: 分析文档内容（AI分析）
  - 识别重复需求：5个
  - 识别冲突需求：2个
  - 识别互补需求：10个

步骤3: 生成合并方案
  - 建议合并到：.spec-workflow/specs/main/requirements.md
  - 重复需求处理：保留最详细的版本
  - 冲突需求处理：询问用户选择

AskUserQuestion: "合并方案：将3个需求文档合并到 .spec-workflow/specs/main/requirements.md。是否同意？"

用户: "同意"

AskUserQuestion: "合并完成后，我将删除以下需求文档，只保留合并后的文档：
- requirements.md
- docs/user-requirements.md
- docs/api-requirements.md

合并后的文档将保存到：.spec-workflow/specs/main/requirements.md

是否同意删除上述文档？"

用户: "同意"

步骤4: 执行合并
  - 合并重复需求（保留最详细的版本）
  - 解决冲突需求（基于用户选择）
  - 合并互补需求

步骤5: 保存合并后的文档并删除其他文档
  - 按照 spec-workflow 格式生成合并后的文档
  - 保存到 .spec-workflow/specs/main/requirements.md
  - 删除 requirements.md
  - 删除 docs/user-requirements.md
  - 删除 docs/api-requirements.md
  - ✅ 只保留一份需求文档

用户: "完善需求" 或使用技能

你: 🚀 开始执行需求完善流程...

📂 步骤1: 扫描代码和文档（必需）...

[必须执行 find 命令扫描文档和代码]
[统计结果：发现2个需求文档和150个代码文件]

📋 步骤2: 根据扫描结果决定流程...

[检测到有需求文档，进入常规流程]

📋 阶段2: 需求分析（必须在交互澄清之前完成）...

步骤1: 读取需求文档和代码文件
步骤2: 理解项目功能
步骤3: 分析问题和缺失信息（必需，必须在列出功能需求清单之前完成）
  - 问题1: [缺失什么、为什么是问题、是否为误报、如何修复]
  - 问题2: [缺失什么、为什么是问题、是否为误报、如何修复]
  ...

步骤4: 列出功能需求清单（必需，必须在分析完成后列出并展示给用户）
  - 功能需求1: [功能名称]
    * 功能描述：[这个功能做什么]
    * 功能行为：[这个功能怎么做]
    * 代码实现：[代码中是否已实现]
  - 功能需求2: [功能名称]
    ...
  - 非功能性需求：[性能需求、安全需求、可靠性需求等]

阶段2已完成，现在进入阶段3（交互澄清），不能跳过！

📋 阶段3: 交互澄清（通过AskUserQuestion与用户交互补充需求）...

[重要阶段，不能跳过！使用 AskUserQuestion 工具与用户交互]

[基于阶段2的分析结果，生成澄清问题]

如果有问题：
AskUserQuestion: "我看到功能需求清单中，功能需求1缺少验收标准。请告诉我：如何验证这个功能是否成功实现？"

用户: [回答]

AskUserQuestion: "功能需求2的输入输出还不明确。请告诉我：这个功能的输入是什么？输出是什么？"

用户: [回答]

...继续交互直到所有关键问题都得到回答...

如果没有问题：
AskUserQuestion: "没有发现问题需要澄清。是否要添加新需求？或直接进入下一步？"

用户: [回答]

✅ 阶段3已完成，现在可以进入阶段4（需求完善）！

📋 阶段4: 需求完善（集成到spec-workflow）...

[检测项目是否使用 spec-workflow]
[按照 spec-workflow 格式生成需求文档]
[如果项目使用 spec-workflow，更新 .spec-workflow/specs/*/requirements.md]
[如果项目未使用 spec-workflow，自动创建 .spec-workflow 目录结构]

🔗 相关资源

• Claude Code Skills 文档
• Spec-Workflow 文档