CloudyWing/spec-doc

產生開發需求規格文件

將 Clarify Agent 整理的需求摘要轉化為一份正式的需求規格文件，供開發團隊成員閱讀與討論。

前置條件

執行此 Skill 前，需具備需求來源，依以下優先序取用：

1. 對話 context 中 Clarify Agent 剛整理完的需求摘要（含需求背景、程式面/功能面項目、排除範圍、假設清單、驗收方向）。
2. 若對話 context 無 Clarify 整理內容，改讀取 <work-root>/.local/ai-sessions/design.md 的第 1 章「需求摘要」。
3. 若兩者均無，告知使用者需先執行 Clarify Agent 完成需求釐清。

執行步驟

1. 取得需求來源

依前置條件優先序載入需求來源，識別其中的結構化元素：

• 功能目標與使用者故事
• 功能需求清單
• 非功能需求（效能、安全性、可用性等）
• 系統邊界與排除範圍
• 假設與前提條件
• 待解決的開放問題

2. 產生規格文件

依照以下結構輸出，使用 Merge 模式寫入（若目標檔案已存在）：

# 開發需求規格：[功能名稱]

> **文件狀態**：草稿
> **最後更新**：[今日日期 YYYY-MM-DD]

## 1. 背景與目標

[說明此功能的業務背景、解決的問題，以及預期達成的目標。]

## 2. 使用者故事

| 角色 | 行為 | 目的 |
| --- | --- | --- |
| 作為 [角色] | 我想要 [行為] | 以便 [目的] |

## 3. 功能需求

### 3.1 [子功能名稱]

- [需求描述，使用「系統應該...」或「使用者可以...」的格式]
- [可驗證的具體行為描述]

### 3.2 [子功能名稱]

...

## 4. 非功能需求

| 類別 | 需求描述 | 驗收標準 |
| --- | --- | --- |
| 效能 | ... | ... |
| 安全性 | ... | ... |
| 可用性 | ... | ... |

## 5. 系統邊界

**納入範圍：**

- [明確說明此次開發包含的項目]

**排除範圍：**

- [明確說明不在此次開發範圍內的項目]

## 6. 假設與前提條件

- [列出需求成立的假設，如「假設用戶已完成身份驗證」]

## 7. 開放問題

| 問題 | 負責人 | 截止日期 | 狀態 |
| --- | --- | --- | --- |
| [待釐清的問題] | | | 待確認 |

## 8. 驗收標準

[列出整體功能的驗收標準，每條應為可驗證的測試案例]

- 驗收條件 1，描述可觀察的系統行為
- 驗收條件 2，描述可觀察的系統行為

3. 輸出規則

• 文件語言：繁體中文（台灣用語），技術術語保留英文。
• 需求描述：每條需求必須可驗證（有明確的輸入、行為、輸出）。
• 不寫空白欄位：若某章節在需求來源中無對應資訊，略去該章節，不留「待補充」佔位符。
• 開放問題保留：需求來源中標示為「待確認」或假設清單中的項目，必須完整保留在第 7 章。
• 自然語言風格：文件目標讀者為同事，採用自然語言段落描述需求脈絡與行為，避免 AI 結構化清單的機械感。每個功能需求應有 1〜2 句說明段落，解釋「為什麼需要這個行為」，而非僅列點。
• 禁止勾選清單格式：驗收標準（第 8 章）不使用 - [ ] 勾選清單格式。改以條列句子（-）描述驗收條件，每條以可觀察的行為描述結尾（如「系統回傳 200 且資料庫新增一筆紀錄」）。

4. 寫入目標檔案

預設輸出路徑：.local/ai-sessions/spec-doc.md

若 .local/ai-sessions/ 目錄不存在，先建立目錄。

完成後告知使用者檔案位置，並提示可將此文件分享給團隊成員確認。