需求種子內容
針對 OpenSpec 的指引
本文件描述啟動 OpenSpec 變更提案所需的最小必要資訊。需求種子是觸發規格驅動開發流程的起點。
問題陳述
AI 代理可以協助產生規格、設計與程式碼，但其產出品質取決於輸入品質。常見問題：
| 問題 | 症狀 | 後果 |
|---|---|---|
| 模糊意圖 | 「做一個更好的登入」 | 代理猜測需求，產出偏離期望 |
| 缺乏邊界 | 未定義範圍 | 範圍蔓延，過度工程 |
| 無驗證標準 | 沒有成功定義 | 無法判斷完成與否 |
| 忽略脈絡 | 未參照現有規格 | 與現有系統衝突或重複 |
需求種子是解決這些問題的最小可行輸入。
需求種子的結構
需求種子分為兩個階段填寫：
- PM 輸入：業務脈絡，由 PM 填寫
- 技術細化：可驗證情境，由技術團隊在啟動會議中協作填寫
關於成功標準
未經深思熟慮的 WHEN/THEN 情境比沒有情境更糟糕。非技術 PM 不應該 (SHOULD NOT) 強迫自己寫出技術情境，而應該專注於描述業務脈絡與預期結果。具體的可驗證情境應該 (SHOULD) 在啟動會議中與技術團隊協作產生。
第一部分：PM 輸入（必填）
由 PM 填寫，專注於業務脈絡與商業價值。
1. 問題陳述（Why）
清楚描述要解決的問題或機會。
必要內容 (MUST)：
- 誰遇到問題（角色/使用者類型）
- 什麼情境下發生
- 目前的痛點或限制
- 為何現在要解決
範例：
## 問題陳述
管理員在批次新增裝置時，必須逐一手動輸入，每次匯入 100 台裝置需要 2 小時。
這在大型部署專案中造成顯著的時間成本，且容易因人為輸入產生錯誤。2. 完成定義（Definition of Done）
用白話描述功能完成時的樣子。不需要 (NOT REQUIRED) 使用 WHEN/THEN 格式。
必要內容 (MUST)：
- 使用者能做到什麼
- 預期的結果或改善
範例：
## 完成定義
- 管理員可以上傳 CSV 檔案批次新增裝置
- 系統顯示匯入結果，包含成功與失敗的數量
- 失敗的資料列有清楚的錯誤說明3. 範圍邊界（Scope）
明確界定納入與排除的範圍。
必要內容 (MUST)：
- 納入範圍（In Scope）
- 排除範圍（Out of Scope）
範例：
## 範圍
### 納入範圍
- CSV 檔案格式支援
- 欄位驗證與錯誤報告
- 匯入進度顯示
### 排除範圍
- Excel 格式支援（後續迭代）
- 匯入排程功能
- 與第三方系統的自動同步4. 已知限制（Constraints）
列出 PM 已知的業務或技術限制。
應包含 (SHOULD)：
- 業務限制（時程、預算、客戶要求）
- 已知的技術限制（如有）
範例：
## 已知限制
- 需支援 IE11（企業客戶要求）
- 必須在 Q2 前完成第二部分：技術細化（啟動會議填寫）
由技術團隊在啟動會議中與 PM 協作填寫。此部分將 PM 的完成定義轉換為可驗證的技術情境。
5. 成功標準（Success Criteria）
將完成定義轉換為具體的 WHEN/THEN 情境。
必要內容 (MUST)：
- 至少一個可衡量的驗收標準
- 使用 WHEN/THEN 格式描述預期行為
- 涵蓋正常流程與異常處理
範例：
## 成功標準
#### Scenario: 批次匯入成功
- **WHEN** 管理員上傳包含 100 筆裝置資料的 CSV 檔案
- **THEN** 系統在 30 秒內完成匯入並顯示成功/失敗摘要
#### Scenario: 匯入錯誤處理
- **WHEN** CSV 檔案包含格式錯誤的資料列
- **THEN** 系統標示錯誤列並繼續處理有效資料
#### Scenario: 檔案格式驗證
- **WHEN** 管理員上傳非 CSV 格式的檔案
- **THEN** 系統顯示錯誤訊息並拒絕處理6. 技術限制（Technical Constraints）
補充技術團隊發現的額外限制。
應包含 (SHOULD)：
- 現有架構限制
- 相依性要求
- 效能要求
範例：
## 技術限制
- 必須使用現有的裝置 API 端點
- 單次匯入上限 1000 筆（資料庫交易限制）
- 需考慮現有的驗證邏輯7. 相關脈絡（Context）
參照現有的相關資訊。
應包含 (SHOULD)：
- 相關的現有規格（使用
openspec show確認） - 相關的變更提案（使用
openspec list確認） - 外部參考資料
範例：
## 相關脈絡
- 現有規格：`specs/device-management/spec.md`
- 相關提案：`changes/device-api-v2/`（需等待此提案完成）
- 參考：廠商 API 文件在 `artifacts/vendor-api-notes.md`最小可行種子
若時間緊迫，以下是 PM 必須提供 (MUST) 的絕對最小需求種子：
## 問題
[一句話描述問題]
## 完成定義
- [使用者能做到什麼]
- [預期的結果]
## 範圍
- 納入：[關鍵功能]
- 排除：[明確不做的事]TIP
技術情境（WHEN/THEN）將在啟動會議中由技術團隊補充。
從需求種子到提案
當需求種子準備好後，流程如下：
PM 輸入 → 啟動會議（技術細化） → 完整需求種子
↓
proposal.md (Why, What Changes, Impact)
specs/[capability]/spec.md (ADDED/MODIFIED)
tasks.md (Implementation Checklist)轉換範例
PM 輸入（啟動會議前）：
## 問題
管理員批次新增裝置需要逐一手動輸入，耗時且易錯。
## 完成定義
- 管理員可以上傳 CSV 批次建立裝置
- 系統顯示匯入結果
## 範圍
- 納入：CSV 匯入、錯誤報告
- 排除：Excel、排程啟動會議後補充：
## 成功標準
#### Scenario: 批次匯入成功
- **WHEN** 管理員上傳包含 100 筆裝置資料的 CSV 檔案
- **THEN** 系統在 30 秒內完成匯入並顯示成功/失敗摘要
#### Scenario: 匯入錯誤處理
- **WHEN** CSV 檔案包含格式錯誤的資料列
- **THEN** 系統標示錯誤列並繼續處理有效資料
## 技術限制
- 單次匯入上限 1000 筆（資料庫交易限制）
- 必須使用現有的裝置 API 端點產生的 proposal.md：
## Why
管理員在批次新增裝置時必須逐一手動輸入，在大型部署專案中造成顯著時間成本。
## What Changes
- 新增 CSV 檔案上傳介面
- 新增批次裝置建立 API 端點
- 新增匯入錯誤報告功能
## Impact
- Affected specs: device-management
- Affected code: DeviceController, DeviceService, DeviceImportPage反模式
1. 解決方案偽裝成需求
問題：
## 問題
我們需要一個用 React 實作的 CSV 上傳元件。失敗原因： 這是解決方案，不是問題。限制了設計空間。
替代做法： 描述使用者的痛點，讓設計過程決定實作方式。
2. 強迫撰寫技術情境
問題：
## 成功標準
- **WHEN** 使用者按下按鈕
- **THEN** 系統做一些事情失敗原因： 非技術 PM 強迫自己寫 WHEN/THEN，產出模糊且無法驗證的情境。這比沒有情境更糟糕，因為它給人一種「已經定義好」的錯覺。
替代做法： PM 應該 (SHOULD) 用白話描述完成定義，讓技術團隊在啟動會議中轉換為可驗證的情境。
3. 無法驗證的成功標準
問題：
## 成功標準
- 系統應該更快
- 使用者體驗應該更好失敗原因： 無法客觀判斷是否達成。
替代做法： 使用具體的 WHEN/THEN 情境，包含可衡量的條件。
4. 遺漏排除範圍
問題：
## 範圍
- 批次匯入功能失敗原因： 未明確排除項目，導致範圍無限膨脹。
替代做法： 明確列出「不做什麼」。
相關文件
None. All related documents have been moved to unverified.
參考資料
- OpenSpec - 規格驅動開發框架
- Gherkin 語法 - WHEN/THEN 情境格式參考