在軟體開發過程中，需求的準確理解與表達是成功的關鍵。Specification by Example (SBE) 作為一種協作式的需求探索方法，強調利用具體的範例（Example）來澄清需求，並促使團隊在需求理解上達成共識。

然而，很多人會把範例視為測試案例（Test Case），導致範例設計時的誤解。本文將提醒如何正確地設計範例，確保需求能夠精確且高效地傳達，讓團隊能專注於需求的真實含義。

範例的元素

我們知道要用範例去輔助說明需求，那你知道範例中包含哪些元素嗎?

(1) 上下文
在系統運作前的狀態，需要把重要的前置條件說清楚。
(2) 觸發的行動
可能是用戶、其他系統，或是由定期會運作的程式等來觸發。
(3) 期待結果
當行動被觸發後，我們預期系統會做什麼。
這邊要足夠詳細，讓我們可以照表操課來檢查。

想用範例來說明需求，其實就像在寫一個超精簡的劇本，每個劇本都應包含這三個部分：

(1) 上下文（Context）＝ 系統的當前狀態或先備條件
在寫需求前，要先交代「事情發生前」系統的狀況，就像開發者需要知道環境或前置條件。

一名使用者已經成功登入系統，並且正在瀏覽「API 金鑰管理頁面」。
（這是開發背景，像是登入狀態、進入的頁面、目前角色權限等）

(2) 觸發的行動（Action）＝ 用戶或系統發動的事件
就像觸發一個事件處理器，你要說清楚「誰」做了「什麼」。

使用者點擊「產生新金鑰」按鈕。
（這可能會連動前端 UI 和後端 API，觸發流程）

(3) 預期結果（Expected Outcome）＝ 系統應該展現的具體行為
當前面的動作發生後，我們要讓系統「確實做出該做的事情」，而且這些行為要是可觀察、可確認的，這樣實作起來才不會模糊。

系統應該立即：
顯示一組新產生的 API 金鑰（包含名稱、值與過期時間），清楚呈現在畫面上
出現提示訊息：「金鑰已成功產生」
在背景將金鑰資訊寫入資料庫，並同時產生一筆操作記錄（audit log）

這些就是一個完整動作結束後，使用者看到的反饋 和 系統內部要完成的事情。
這樣的描述方式，也能幫助開發人員拆解工作內容與定義完成的標準。

剛剛是分開解釋每個部分是在做什麼，接下來讓我們把三個部分合起來，讓你看些完整的範例可能長得怎樣：

範例一：重設使用者密碼功能
(1) 上下文（Context）
一名使用者在登入頁面，點選了「忘記密碼」連結。
系統已顯示輸入 Email 的表單畫面。

(2) 觸發的行動（Action）
使用者輸入註冊用的 Email 並按下「送出驗證信」按鈕。

(3) 預期結果（Expected Outcome）
系統立即顯示訊息：「重設密碼的連結已寄送至您的 Email。」

系統背景會：
驗證 Email 是否存在於資料庫中
產生一組時效性 token
寄出含有重設連結的 Email
寫入一筆操作記錄，記錄是哪個 IP 發起的請求

範例二：修改個人資料
(1) 上下文（Context）
使用者已登入系統，並進入「個人資料設定」頁面。

(2) 觸發的行動（Action）
使用者修改了暱稱與聯絡電話，點選「儲存變更」按鈕。

(3) 預期結果（Expected Outcome）
系統立即更新頁面，顯示訊息：「修改成功」
修改後的資料即時反映在畫面上

系統背景會：
將新資料寫入使用者資料表
紀錄這次變更時間與欄位
若聯絡電話變更，觸發簡訊驗證流程

範例三：搜尋訂單紀錄
(1) 上下文（Context）
管理者進入「後台訂單管理系統」，預設畫面尚未顯示任何搜尋結果。

(2) 觸發的行動（Action）
管理者輸入客戶 Email 並選擇日期區間，點選「搜尋」。

(3) 預期結果（Expected Outcome）
系統顯示符合條件的訂單清單（包含訂單編號、狀態、金額等資訊）
若無資料，顯示「查無符合結果」

系統背景會：
對訂單資料庫進行查詢（依 Email 與時間條件）
寫入一筆查詢操作紀錄，用於日後稽核

資料需要準備到多完整？不是越多越好！

當我們要用一個範例來說明系統行為時，最常遇到的問題之一就是：
「是不是所有相關資料都要列出來？會不會漏資料就不能驗證？」

這裡有一個簡單但關鍵的原則：
只有那些會影響你想表達的行為或邏輯的資料，才需要列在範例中。
也就是說，不是「有的資料就都寫上去」，而是「有幫助說明這個情境的資料才需要」。讓我們舉些案例來說明：

案例一：修改送貨地址

(1) 上下文（Context）
團隊正在進行需求範例撰寫的討論，目的是建立一組可協助對齊需求與邏輯的範例資料。
某位團隊成員提出一個範例，要描述「使用者在送貨前修改收件地址」的情境。

但他提供的資料包含了：
 商品明細
 使用者身份證字號
 信用卡資訊
 原始送貨地址
 新的送貨地址
 訂單狀態、訂單時間等等...

這時其他成員開始疑惑：「我們每個範例都要列這麼多資料嗎？」

(2) 觸發的行動（Action）
引導者跳出來說明：「我們來釐清這個範例要表達的行為是什麼。」
接著他請大家回到基本原則：「資料的準備應該根據這個範例要驗證的行為來決定，而不是列出所有可能相關的欄位。」

他重新聚焦問題：「這個範例的重點，是修改地址，而不是驗證身份或處理付款，所以只需要：」
 訂單編號
 新的送貨地址
就足夠了。

(3) 預期結果（Expected Outcome）
團隊理解：在撰寫範例時，只需要提供與情境邏輯有關的資料，不必列出所有欄位。後續產出的範例變得更聚焦、更簡潔。範例更容易轉成驗證步驟、實作依據，減少混淆。減少浪費在準備冗餘資料的時間，也讓討論聚焦在真正需要被驗證的行為上。

案例二：下載訂單 vs 取消訂單 —— 行動不同，資料需求也不同

(1) 上下文（Context）
使用者已登入電商平台，並進入「訂單查詢」頁面，系統已顯示出歷史訂單清單。
每筆訂單右側都有兩個按鈕：「下載發票」與「取消訂單」。

(2) 兩種不同的行為（Action）
行為 A：下載發票（Download Invoice）
使用者點選「下載發票」按鈕，希望下載某筆訂單的電子發票。
a. 所需資料：
訂單編號（系統需知道是哪一筆訂單）
發票號碼（或由後端依訂單編號查出）
b. 不需要的資料：
商品內容
收件地址
付款方式
訂單狀態（除非你有邏輯要求只有已完成訂單才可下載）

行為 B：取消訂單（Cancel Order）
使用者點選「取消訂單」按鈕，想要取消這筆訂單。
a. 所需資料：
訂單編號
訂單狀態（確認是否還能取消，例如已出貨就不能）
取消原因（可選填）
b. 不需要的資料：
發票號碼
下載記錄
商品詳細說明（除非你系統要根據商品類型判斷是否可取消）

(3) 預期結果（Expected Outcome）
這兩個行為展示了：
同樣的背景情境，因為行為不同，範例所需的資料也會有所不同。
「下載發票」需要的是與發票檔案取得有關的資訊
「取消訂單」需要的是與訂單狀態有關的資訊
這讓團隊在討論範例時不再用一套固定格式，而是根據行為去決定資料的最小必要集。

多少範例才算夠？重點不是數量，而是理解

在導入 Specification by Example (SBE) 時，很多人會問：
「我們到底要列出多少範例才算夠？」
「是不是所有可能的情境都要寫出來才安心？」

這背後其實藏著兩種常見的誤解：
 怕遺漏場景，所以想全部列出來
 把此做法當作測試工具，所以覺得要寫成一堆測試案例

但其實這兩個方向都跑偏了。

SBE 的目的不是「測試覆蓋」，而是「釐清需求」。
SBE 的核心是幫助團隊建立共同理解，透過討論範例來探索需求本身的邏輯與邊界。
重點不是「覆蓋多少情境」，而是「你是否已經對這個需求夠清楚了」。

換句話說，當你們透過討論範例已經達到清晰共識，就可以停了。

一旦你發現團隊開始這樣對話：
「欸，如果輸入是空字串呢？」
「那特殊符號呢？」
「長度太長會怎樣？」
「那先加再刪再改呢？」

這時候你可能已經無意間從「需求探索」滑進「測試腦模式」，開始進行驗證邏輯的全覆蓋設計，這就是測試人員會做的事，不是 SBE 要處理的重點。

這時候引導者就該跳出來說：
「我們現在想確認的是這個行為的意圖與邏輯，而不是所有可能的測試輸入。」

範例不是用來寫完所有測試，是用來把模糊的需求變清楚。夠清楚了，就夠了。