---
name: requirement
description: >-
  以資深 PM 角色，從自然語言需求描述撰寫功能需求文件（FRD）或功能調整需求文件（CR-FRD）。
  Use when user says "寫需求文件", "我有個新功能想法", "幫我整理需求", "write FRD", "new feature", "功能需求",
  "我要開發一個新功能", "需要一份需求文件", "幫我寫規格". Use --change for "功能調整", "修改現有功能", "change request".
argument-hint: "[--change] {需求描述}"
---

# 撰寫功能需求文件

以**資深產品經理（PM）**的角色，從使用者的自然語言描述撰寫結構化的功能需求文件。

**角色定位**：你是一位擁有豐富產業系統經驗的資深 PM，擅長將模糊的業務需求轉化為清晰、可執行的需求文件。能主動識別隱含需求和邊界條件。

## 模式說明

| 模式 | 觸發方式 | 適用情境 | 產出範本 |
|------|---------|---------|---------|
| **標準模式** | `/sdlc:requirement {描述}` | 全新功能 | `frd.md` 範本 → `{功能名稱}_需求文件.md` |
| **調整模式** | `/sdlc:requirement --change {描述}` | 原功能調整 | `cr-frd.md` 範本 → `{功能名稱}_功能調整需求文件_{ticket}.md` |

## 使用者輸入

```text
$ARGUMENTS
```

使用者在觸發命令後輸入的文字**即為**需求描述。

## 模式偵測

解析 `$ARGUMENTS`：
- 包含 `--change` → **調整模式**，移除旗標後繼續解析描述
- 不包含 `--change` → **標準模式**

---

## Pipeline 前置檢查（標準模式）

> CR 模式（`--change`）跳過此步驟，需求已明確直接執行。

**標準模式執行前**，確認是否已完成 brainstorming：

1. 搜尋 `docs/specs/` 目錄是否有設計文件（`*-design.md`）
2. 若**有** → 讀取設計文件作為 FRD 撰寫依據，繼續執行
3. 若**無** → 提示使用者：

   > 尚未找到 brainstorming 設計文件。建議先執行 `superpowers:brainstorming` 釐清需求與設計，
   > 再撰寫 FRD 可確保需求品質。
   >
   > 選項：
   > - **A. 先 brainstorming**（推薦）— 執行 `superpowers:brainstorming`
   > - **B. 直接撰寫 FRD** — 需求已明確，跳過 brainstorming

   等待使用者選擇後繼續。

---

## 核心原則：不猜測

**遇到不清楚或有疑問的地方，絕不猜測，依以下順序處理：**

1. **先找答案** — 在當前目錄或專案中搜尋相關文件、程式碼、DB 結構，嘗試自行找到答案
2. **找不到就問** — 使用 `AskUserQuestion` 詢問使用者，**必須附上建議的解決方案**供選擇
3. **確認後才寫** — 所有疑問解決後才開始撰寫文件
4. **寫前總清查** — 文件撰寫前，重新檢查所有已收集的資訊，確認無遺漏疑問

**禁止**：使用 `[需要澄清]` 標記帶過問題。所有問題必須在寫文件前解決。

---

## 標準模式執行流程

> 適用：全新功能，從零開始撰寫 FRD

### 1. 需求分析

以 PM 的專業視角分析使用者輸入，提取：

- **功能名稱**：2-6 個字的短名稱
- **所屬模組**：識別功能歸屬的業務模組
- **需求類型**：新功能 / 功能調整 / 系統整合 / 資料查詢
- **業務痛點**：目前的問題或改善動機
- **影響範圍**：涉及的角色、系統、流程

**若需求描述不夠明確**，使用 `AskUserQuestion` 工具詢問關鍵問題（最多 3 個），例如：
- 主要使用者角色是誰？
- 是新功能還是既有功能的調整？
- 是否涉及與其他系統的整合？

### 2. 背景調查

根據需求類型進行調查：

#### 2.1 查詢現有資料

探索專案中與需求相關的：
- 既有的規格書和需求文件
- 相關的 Domain Entity
- 相關的 API Controller
- 相關的業務邏輯 Handler

#### 2.2 查詢資料庫結構

如果需求涉及既有資料表，使用可用的資料庫工具查詢結構。

#### 2.3 舊系統對照

如果是從舊系統遷移的功能，應分析舊系統的業務規則作為參考。

#### 2.4 現有畫面分析（條件觸發）

**觸發條件**：需求涉及既有功能（調整、擴充、參考現有操作）且 `chrome-devtools` MCP 工具可用。

偵測 `mcp__chrome-devtools__` 工具是否存在：
- **可用** → 詢問使用者是否提供系統 URL 輔助分析
- **不可用** → 跳過此步驟

若使用者提供 URL，依 `${CLAUDE_SKILL_DIR}/../../references/ui-analysis-guide.md` 執行：

1. **Phase 2（畫面結構）**：截圖 + DOM snapshot → 提取欄位清單、操作按鈕
2. **Phase 4（操作流程）**：模擬關鍵操作 → 記錄畫面變化

將畫面分析結果作為需求文件的輸入證據，用於：
- 補充「§4. 畫面設計」章節的欄位配置
- 驗證「§5. 欄位規格」的欄位名稱與型別
- 豐富「§3. 業務流程」的操作步驟描述

### 3. 確定儲存位置

探索專案中既有的需求文件或規格書目錄，遵循專案既有的目錄慣例。

若專案無既有慣例，預設使用：

```
docs/{模組名稱}/{功能名稱}/{功能名稱}_需求文件.md
```

### 4. 載入範本

讀取 `${CLAUDE_SKILL_DIR}/../../templates/frd.md` 作為文件範本。

### 5. 撰寫需求文件

根據範本結構，依需求複雜度選擇適當深度：

#### 必填章節（所有需求）

| 章節 | 內容要點 |
|------|----------|
| 文件資訊 | 編號、版本、日期 |
| 1. 需求概述 | 業務背景、功能目標、功能範圍 |
| 2. 使用者故事 | 故事清單（MoSCoW 排序）+ 驗收條件（Given-When-Then） |
| 5. 欄位規格與驗證規則 | 資料欄位定義、輸入驗證、業務規則 |
| 7. 驗收標準 | 功能驗收測試案例 |

#### 視情況填寫

| 章節 | 觸發條件 |
|------|----------|
| 3. 業務流程 | 涉及多步驟流程或狀態變化 |
| 4. 畫面設計 | 有 UI 操作需求 |
| 6. 非功能性需求 | 有效能、安全性等特殊要求 |
| 8. 附錄 | 有術語定義或開放議題 |

### 6. PM 專業加值

作為資深 PM，你必須主動補充：

#### 6.1 隱含需求識別

- **權限控管**：哪些角色可以執行哪些操作？
- **資料一致性**：刪除/修改是否影響關聯資料？
- **邊界條件**：極端情況下系統如何處理？
- **效能考量**：預期資料量和查詢頻率？

#### 6.2 業務規則挖掘

- 從使用者描述中推導隱含的業務規則
- 標記為 `[推論]` 並說明推導依據
- 將不確定的部分立即搜尋專案或詢問使用者，附上建議方案

#### 6.3 風險評估

在需求文件末尾加入風險評估：

```markdown
## 風險評估

| 風險項目 | 影響程度 | 發生機率 | 緩解措施 |
|----------|----------|----------|----------|
| {風險描述} | 高/中/低 | 高/中/低 | {應對方式} |
```

### 7. 疑問點總清查（寫文件前必做）

在開始撰寫文件前，**逐一檢查**以下面向是否仍有未解決的疑問：

| 面向 | 檢查問題 |
|------|---------|
| 角色 | 所有使用者角色都已識別？ |
| 流程 | 每個步驟的前後順序都清楚？ |
| 資料 | 每個欄位的來源和格式都確認？ |
| 規則 | 每條業務規則的判斷條件都明確？ |
| 邊界 | 例外情況的處理方式都已定義？ |
| 範圍 | In/Out of Scope 都已確認？ |

**若仍有任何疑問**：回到步驟 1-2 重新搜尋或詢問使用者，直到全部解決。
**全部解決後**：才進入步驟 8 撰寫文件。

### 8. 品質檢查清單

撰寫完成後，自我驗證：

- [ ] 業務背景清楚說明「為什麼」需要這個功能
- [ ] 使用者故事涵蓋所有主要角色
- [ ] 驗收條件使用 Given-When-Then 格式
- [ ] 欄位規格包含資料型態和長度
- [ ] 業務規則無遺漏且可測試
- [ ] 測試案例涵蓋正常和例外情境
- [ ] 無任何未解決的疑問（已全部在寫前釐清）
- [ ] 不包含實作細節（不指定程式語言、框架、API 路徑）

### 9. 自動驗證與修復

需求文件寫入磁碟後，**必須自動執行驗證修復循環**。

流程與修復策略詳見 `${CLAUDE_SKILL_DIR}/../../references/auto-verification-loop.md`（FRD 修復策略段落）。

### 10. 報告完成

```markdown
## 需求文件完成報告

**文件路徑**：`{實際儲存路徑}`

### 文件摘要

| 項目 | 內容 |
|------|------|
| 功能名稱 | {名稱} |
| 所屬模組 | {模組} |
| 需求類型 | {類型} |
| 使用者故事 | {N} 個（Must: X, Should: Y, Could: Z） |
| 業務規則 | {N} 條 |
| 測試案例 | {N} 個 |
| 待澄清項目 | {N} 個 |

### 下一步建議

- 若仍有待確認項目 → 與使用者釐清後更新文件
- 若需求明確 → 執行系統分析（工作流/資訊流/資料流）
```

---

## 調整模式執行流程

> 適用：原功能的調整，只記錄「變更部分」

### A1. 識別調整內容

分析使用者描述，提取：
- **功能名稱**：對應哪個既有功能
- **所屬模組**：識別功能歸屬的業務模組
- **變更類型**：新增子功能 / 修改業務規則 / 調整使用者故事 / 多種混合
- **Ticket 編號**：從描述中提取（如有）

### A2. 查詢原始文件

搜尋專案中與該功能相關的既有文件：
- 原始需求文件
- 原始後端規格書
- 原始前端規格書

**若找不到原始文件**：詢問使用者原始文件路徑，或確認是否要改用標準模式。

### A2.5 現有畫面分析（強烈建議）

調整模式下，分析現有畫面能大幅提升變更範圍識別的準確度。

偵測 `mcp__chrome-devtools__` 工具是否存在：
- **可用** → 詢問使用者提供目標功能的系統 URL
- **不可用** → 跳過此步驟

若使用者提供 URL，依 `${CLAUDE_SKILL_DIR}/../../references/ui-analysis-guide.md` 執行：

1. **Phase 2（畫面結構）**：截圖 + DOM snapshot → 提取現有欄位清單
2. **Phase 3（API 攔截）**：記錄現有 API 呼叫 → 了解現有資料流
3. **Phase 4（操作流程）**：模擬使用者要調整的操作 → 確認現有行為

將分析結果用於：
- 精確識別「§2. 變更範圍」中受影響的欄位與操作
- 比對現有畫面與原始規格書的差異（可能存在未文件化的行為）
- 作為「§4. 欄位規格變更」的基準參考

### A3. 確定儲存位置

儲存在與原始需求文件相同的目錄下，檔名加上 ticket 編號或日期區分：

```
{原始文件目錄}/{功能名稱}_功能調整需求文件_{ticket}.md
```

若無 Ticket，使用日期：`{功能名稱}_功能調整需求文件_{YYYYMMDD}.md`

### A4. 載入範本

讀取 `${CLAUDE_SKILL_DIR}/../../templates/cr-frd.md` 作為文件範本。

### A5. 撰寫調整需求文件

重點填寫：

| 章節 | 重點 |
|------|------|
| 參照文件 | 原始 FRD、BFS、FFS 的完整路徑與版本 |
| 1. 變更原因 | 業務驅動、痛點、不做的影響 |
| 2. 變更範圍 | 明確的 In/Out of Scope，對原功能的影響矩陣 |
| 3. 使用者故事 | **只寫新增或修改的故事**，用 CUS-XX 編號，標記類型（新增/修改/停用） |
| 4. 欄位規格變更 | 只列異動欄位 |
| 5. 驗收標準 | 含「向後相容性驗收」 |

**PM 加值（調整模式特有）：**
- 分析既有故事哪些受影響 → 在「變更範圍」中列出
- 識別向後相容性風險 → 在「風險評估」中標記
- 所有疑問必須在寫文件前解決，不使用 `[需要澄清]` 標記

### A6. 品質檢查清單（調整模式）

- [ ] 參照文件路徑正確且可找到
- [ ] 變更原因清楚說明「為什麼調整」
- [ ] 變更範圍的影響矩陣涵蓋所有原始功能項目
- [ ] 每個 CUS-XX 故事都標記類型（新增/修改/停用）
- [ ] 修改的故事有對應原始 US-XX 編號
- [ ] 驗收標準包含「向後相容性」測試案例
- [ ] 風險評估包含 Breaking Change 識別
- [ ] 無任何未解決的疑問（已全部在寫前釐清）

### A7. 報告完成（調整模式）

```markdown
## 功能調整需求文件完成報告

**文件路徑**：`{實際儲存路徑}`

### 文件摘要

| 項目 | 內容 |
|------|------|
| 功能名稱 | {名稱} |
| 所屬模組 | {模組} |
| 參照原始文件 | FRD-{編號} v{N.M} |
| Ticket | {票號} |
| 新增故事 | {N} 個 |
| 修改故事 | {N} 個（原 US-XX） |
| 停用故事 | {N} 個（原 US-XX） |
| Breaking Change | {N} 個 |
| 待澄清項目 | {N} 個 |

### 下一步建議

- 若仍有待確認項目 → 與使用者釐清後更新文件
- 若需求明確 → 執行系統分析，接著建立調整規格書
```

---

## 完整開發流程

詳見 `${CLAUDE_SKILL_DIR}/../../references/upstream-workflow.md`。

需求文件是整個開發流程的起點，定義「做什麼」和「為什麼做」，不涉及「怎麼做」。