User Story 與驗收條件範本(User Story & Acceptance Criteria)#
參照標準:INVEST 原則 / Gherkin(Cucumber)/ ISO/IEC/IEEE 29148:2018 需求品質特性
文件用途:以使用者觀點描述需求,並以可自動化的 Gherkin 驗收條件定義「完成」
適用階段:需求分析與 Sprint 規劃(Backlog Refinement)
範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 3.2、2.4(DoR)節
📋 章節目錄#
- Story 基本資訊
- Story 描述與 INVEST 檢查
- 驗收條件(Gherkin)
- 非功能與安全考量
- 審查與驗證
1. Story 基本資訊#
📝 範本#
| 項目 | 內容 |
|---|
| Story 編號 | {專案代碼}-{序號} |
| 對應需求 | {FR/PRD 功能編號} |
| 優先序 | {Must/Should/Could/Won’t} |
| 估點 | {Story Points,超過 8 點需拆分} |
| 相依項目 | {API、資料表、其他 Story} |
| UI 設計 | {Figma 連結/線框圖} |
📖 使用說明#
- 「相依項目」與「UI 設計」是 DoR(就緒定義)的檢查項目,缺少時不得排入 Sprint
- 估點超過團隊約定上限(例:8 點)時必須拆分
💡 範例#
| 項目 | 內容 |
|---|
| Story 編號 | HRMS-412 |
| 對應需求 | FR-LV-002 |
| 優先序 | Must |
| 估點 | 5 |
| 相依項目 | GET /api/v1/leave-quotas(HRMS-398,已完成) |
| UI 設計 | Figma「請假申請 v3」 |
2. Story 描述與 INVEST 檢查#
📝 範本#
身為 {角色},
我想要 {功能},
以便 {商業價值}。
| 原則 | 檢查問題 | 結果 |
|---|
| Independent 獨立 | 能否單獨交付? | {✅/❌ 說明} |
| Negotiable 可協商 | 描述需求而非規定實作? | {✅/❌} |
| Valuable 有價值 | 使用者或業務能感受到價值? | {✅/❌} |
| Estimable 可估算 | 團隊能估出大小? | {✅/❌} |
| Small 夠小 | 一個 Sprint 內可完成? | {✅/❌} |
| Testable 可測試 | 有明確驗收條件? | {✅/❌} |
📖 使用說明#
- 「以便」寫的是業務價值,不是技術手段(❌「以便呼叫 API」)
- INVEST 任一項 ❌ 時,於 Refinement 會議中修改或拆分
💡 範例#
身為 員工,
我想要 在申請特休時看到剩餘天數,並在額度不足時被擋下,
以便 不必等主管退件才知道申請無效。
| 原則 | 檢查問題 | 結果 |
|---|
| Independent | 能否單獨交付? | ✅ 額度 API 已完成 |
| Negotiable | 描述需求而非實作? | ✅ |
| Valuable | 有業務價值? | ✅ 減少主管退件(每月約 40 件) |
| Estimable | 可估算? | ✅ 5 點 |
| Small | 一個 Sprint 內? | ✅ |
| Testable | 有驗收條件? | ✅ 見第 3 節 |
3. 驗收條件(Gherkin)#
📝 範本#
# language: zh-TW
功能: {功能名稱}({需求編號})
場景: {正常情境}
假設 {前置條件}
當 {使用者動作}
那麼 {可觀察的結果}
場景: {例外情境}
假設 {前置條件}
當 {使用者動作}
那麼 {錯誤處理結果}
📖 使用說明#
- 至少 1 個正常情境與 1 個例外情境;邊界值(剛好等於上限)另列場景
- 「那麼」必須可觀察、可自動判定:寫出畫面訊息、HTTP 狀態碼或資料變化,不寫「系統正常運作」
- 中文關鍵字需在第一行宣告
# language: zh-TW;也可使用英文關鍵字 Feature/Scenario/Given/When/Then - 每個
.feature 檔都必須有 功能:(Feature:)行,否則 Cucumber 無法解析
💡 範例#
# language: zh-TW
功能: 特休額度檢查(FR-LV-002)
場景: 額度足夠時可送出申請
假設 員工 "E20260001" 的特休剩餘 5 天
當 員工申請 3 天特休
那麼 申請狀態為 "pending"
而且 畫面顯示 "申請已送出,剩餘特休 2 天(核准後扣除)"
場景: 額度不足時拒絕申請
假設 員工 "E20260001" 的特休剩餘 2 天
當 員工申請 3 天特休
那麼 API 回應狀態碼 422
而且 畫面顯示 "特休剩餘 2 天,不足申請天數 3 天"
場景: 申請天數剛好等於剩餘額度
假設 員工 "E20260001" 的特休剩餘 3 天
當 員工申請 3 天特休
那麼 申請狀態為 "pending"
4. 非功能與安全考量#
📝 範本#
| 類別 | 要求 | 驗證方式 |
|---|
| 權限 | {誰可以執行、可以存取誰的資料} | {整合測試} |
| 效能 | {量化目標} | {k6/APM} |
| 稽核 | {需記錄的事件} | {日誌檢查} |
| 個資 | {涉及的欄位與分級} | {資料分級對照表} |
📖 使用說明#
- 每個 Story 都要想一次「誰不應該能做這件事」,並寫成測試
- 涉及個資時引用《資料分級對照表範本》的分級
💡 範例#
| 類別 | 要求 | 驗證方式 |
|---|
| 權限 | 員工只能查詢與申請自己的假;主管可查部屬 | 整合測試:以 A 員工 Token 查 B 員工額度 → 403 |
| 效能 | 額度查詢 p95 < 300 ms | k6 負載測試 |
| 稽核 | 申請送出記錄員工編號、天數、結果 | 日誌檢查 |
| 個資 | 請假事由屬「機密」,日誌禁止記錄 | 日誌 grep 測試 |
5. 審查與驗證#
本節供審查者使用,也用來檢查 AI 依本範本產出的 User Story 是否正確。
自動檢查#
| 檢查項目 | 方法 |
|---|
| Gherkin 可解析 | npx cucumber-js --dry-run,或以 @cucumber/gherkin 解析 |
| 每個步驟都有實作 | Cucumber --dry-run 不得出現 undefined step |
| 驗收條件數量 | 每個 .feature 至少 2 個場景(正常+例外) |
人工審查問題#
- 「以便」是否寫出真正的業務價值?
- 是否有例外與邊界情境?
- 「那麼」的結果是否可自動判定?
- 權限情境(存取他人資料)是否涵蓋?
AI 常見錯誤#
- 驗收條件只有正常流程。
- 「那麼」寫成「系統正確處理」等無法判定的句子。
- 漏寫
功能: 行或 # language: zh-TW 宣告,導致無法解析。
📌 範本使用注意事項
- User Story 符合 DoR 才能排入 Sprint(見《DoR/DoD 範本》)
- 驗收條件即為自動化驗收測試的規格
- 搭配「PRD 範本」「需求追溯矩陣範本」使用