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)節


📋 章節目錄

  1. Story 基本資訊
  2. Story 描述與 INVEST 檢查
  3. 驗收條件(Gherkin)
  4. 非功能與安全考量
  5. 審查與驗證

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 msk6 負載測試
稽核申請送出記錄員工編號、天數、結果日誌檢查
個資請假事由屬「機密」,日誌禁止記錄日誌 grep 測試

5. 審查與驗證

本節供審查者使用,也用來檢查 AI 依本範本產出的 User Story 是否正確。

自動檢查

檢查項目方法
Gherkin 可解析npx cucumber-js --dry-run,或以 @cucumber/gherkin 解析
每個步驟都有實作Cucumber --dry-run 不得出現 undefined step
驗收條件數量每個 .feature 至少 2 個場景(正常+例外)

人工審查問題

  1. 「以便」是否寫出真正的業務價值?
  2. 是否有例外與邊界情境?
  3. 「那麼」的結果是否可自動判定?
  4. 權限情境(存取他人資料)是否涵蓋?

AI 常見錯誤

  • 驗收條件只有正常流程。
  • 「那麼」寫成「系統正確處理」等無法判定的句子。
  • 漏寫 功能: 行或 # language: zh-TW 宣告,導致無法解析。

📌 範本使用注意事項

  1. User Story 符合 DoR 才能排入 Sprint(見《DoR/DoD 範本》)
  2. 驗收條件即為自動化驗收測試的規格
  3. 搭配「PRD 範本」「需求追溯矩陣範本」使用