---

name: user-story-writer language: zh-TW description: "撰寫結構良好、帶驗收標準和邊界情況的使用者故事。當被要求寫使用者故事、根據功能說明建任務、把 PRD 轉成故事，或寫驗收標準時使用。產出可以直接估算的標準格式故事，附清楚的驗收標準、邊界情況和完成定義。"

user-story-writer 的繁體中文翻譯，英文版本為規範版本。

使用者故事撰寫

這個技能根據功能說明、PRD 的某一部分或口頭描述，產出可以直接使用的使用者故事。每個故事都遵循標準格式：清楚的誰 / 做什麼 / 為什麼，按 Given / When / Then（假如 / 當 / 那麼）格式寫的行為驗收標準、邊界情況和完成定義。產出可以直接貼上到 Jira、Linear 或你的規劃工具中。

所需輸入

如未提供，請向使用者詢問：

• 要拆成故事的功能或改動：貼上說明、PRD 部分，或描述功能
• 涉及的使用者型別 / 角色（例如管理員、終端使用者、訪客、API 呼叫方）
• 範圍：寫一個故事，還是把一個史詩拆成完整的一組故事？
• 驗收標準格式偏好：Given / When / Then、要點清單，還是兩者都要？
• 技術約束或說明：工程團隊提出的、應當影響故事的任何事項

輸出結構

每個故事：

---

故事：[簡短標題，動詞加名詞，例如"按日期範圍篩選搜尋結果"]

史詩： [所屬史詩名稱，例如"高階搜尋"] 故事編號： [Jira / Linear 編號，還沒建立就留空] 優先順序： [P1 / P2 / P3] 故事點： [留空，由工程團隊估算]

---

使用者故事

作為 [具體的使用者型別，不要寫"使用者"]， 我想要 [他們想採取的具體行動]， 以便 [他們得到的結果：業務價值，而不是功能描述]。

示例：

作為客戶經理， 我想要按最近聯絡日期篩選我的客戶列表， 以便快速找出 30 天以上沒有聯絡過的客戶，並優先跟進。

---

背景

[1 到 3 句使用者故事本身沒有的背景：這個故事什麼時候重要、是什麼觸發了這個需要、它如何融入更大的流程。這能幫助工程師在提問之前就理解為什麼。]

---

驗收標準

格式：Given / When / Then（假如 / 當 / 那麼）

每條標準只測試一個具體行為。每個可觀察的結果寫一條，而不是整個功能只寫一條。

AC1：[這條標準的簡短名稱]

假如 [初始狀態或背景]
當 [使用者行動]
那麼 [可觀察的系統行為]

AC2：[簡短名稱]

假如 [...]
當 [...]
那麼 [...]

AC3：[簡短名稱]

假如 [...]
當 [...]
那麼 [...]

---

邊界情況

[列出不明顯但必須處理的場景。它們會成為額外的驗收標準或給工程團隊的說明。]

• [邊界情況 1]： [例如使用者應用的日期篩選返回 0 條結果：顯示空狀態，附清楚的提示和"清除篩選"操作]
• [邊界情況 2]： [例如使用者有超過 10,000 個客戶：篩選不能讓載入時間增加超過 200 毫秒]
• [邊界情況 3]： [例如日期篩選在重新整理頁面後保留，或者如果決定不保留，就明確寫明不保留]
• [許可權邊界情況]： [例如只讀使用者能看到篩選，但不能儲存篩選預設]

---

不在範圍內

[明確寫出這個故事不包括什麼：防止範圍蔓延，並說明下一個故事從哪裡開始。]

• 儲存和分享篩選預設（另一個故事，見 [故事 X]）
• 對篩選結果的批次操作
• 把篩選後的客戶列表匯出為 CSV

---

完成定義

• 所有驗收標準都透過
• 邊界情況已處理（或已明確推遲並新建了任務）
• 每條驗收標準都有單元測試
• 在移動端視口下可用（如適用）
• 無障礙：可鍵盤操作，相容讀屏軟體
• 錯誤狀態已處理，文案已確認
• 產品和設計已在預發環境審閱
• 生產構建中沒有控制檯錯誤

---

史詩拆解模板

如果使用者提供的是史詩或功能說明，先把它拆成完整的一組故事，再逐個撰寫：

史詩： [名稱] 目標： [完成這個史詩帶來什麼結果？] 故事：

#	故事	說明	依賴
1	[核心正常路徑故事：能交付價值的最簡單版本]
2	[校驗 / 錯誤處理故事]		依賴 #1
3	[邊界情況或高階使用者故事]		依賴 #1
4	[管理員或配置故事]
5	[效能或規模故事，如適用]		依賴 #1

建議的迭代順序： [哪些故事是 MVP 的 P1？哪些可以放到之後的迭代？]

---

常見的故事反模式及修正

在交給工程團隊之前，用這些來審查故事：

反模式	例子	修正
故事裡寫了方案	"作為使用者，我想要一個下拉篩選框"	去掉介面決定："作為使用者，我想要按日期範圍篩選"
含糊的"以便"	"以便更好用"	寫具體："以便我不用逐條開啟記錄就能安排跟進優先順序"
太大	一個故事涵蓋 5 個不同的使用者流程	按流程拆成多個故事
沒有驗收標準	故事只有描述	工程開始前至少加 3 條 Given / When / Then 標準
驗收標準測試方案而不是行為	"假如下拉框已開啟，當我選擇一個選項"	測試結果："假如我應用了日期篩選，當我檢視結果，那麼只顯示在該日期範圍內最近聯絡過的客戶"
缺少空狀態	沒有關於 0 條結果時怎麼辦的標準	加上：空狀態是功能的一部分
缺少錯誤狀態	沒有關於網路失敗或無效輸入的標準	明確加上錯誤處理的驗收標準

---

示例：一個功能的完整故事集

功能說明： "允許使用者把發票歷史匯出為 PDF 或 CSV"

---

故事 1：把發票列表匯出為 CSV

作為財務管理員， 我想要把我的發票歷史匯出為 CSV 檔案， 以便不用手動錄入就能匯入我們的會計軟體。

AC1：匯出成功

假如 我在發票頁面，且至少有一張發票
當 我點選"匯出"並選擇"CSV"
那麼 下載一個 CSV 檔案，包含所有可見發票，列為：發票編號、日期、金額、狀態、客戶名稱

AC2：空狀態

假如 我在發票頁面，且沒有任何發票
當 我點選"匯出"
那麼 匯出按鈕不可用，提示顯示"沒有可匯出的發票"

AC3：篩選後匯出

假如 我已應用日期篩選，只顯示 2026 年 1 月的發票
當 我點選"匯出"並選擇"CSV"
那麼 匯出內容只包含 2026 年 1 月的發票，而不是全部發票

邊界情況：

• 匯出超過 10,000 張發票：必須在 30 秒內完成，或顯示進度指示
• 在移動端觸發匯出：下載到裝置預設的下載位置

不在範圍內： PDF 匯出（故事 2）、定時匯出（未來的史詩）

---

故事 2：把發票列表匯出為 PDF

作為財務管理員， 我想要把我的發票歷史匯出為排版好的 PDF， 以便和會計分享一份專業的彙總。

[……驗收標準按同樣的模式……]

---

延伸材料

這個技能附帶支援檔案，可用時請使用：

• references/acceptance-criteria-craft.md：真正起把關作用的驗收標準。在產出時應用它；它包含上面方法摘要壓縮掉的校準和判斷。
• templates/story-card.md：可填寫的成果模板，品質關卡寫在裡面。當使用者想自己完成文件而不是生成時提供。

評分量表（0 到 40）

交付前給這個技能的任何產出打分；32 分以上才算可以交付。

維度	0	5	10
使用者視角與價值	故事從系統或開發者的角度寫；"以便"缺失或迴圈（"以便更好用"）	角色具體，但部分"以便"描述的是功能而不是使用者得到的結果	每個故事都點出具體的使用者型別，"以便"寫明他們獲得的具體結果：干係人讀了就知道為什麼值得做
驗收標準的可測試性與粒度	沒有驗收標準，或只是沒有透過 / 不透過條件的文字描述	用了 Given / When / Then，但一條標準捆綁了多個行為，或測試的是介面方案而不是可觀察的結果	每個可觀察行為一條，每條都有明確的透過 / 不透過條件，測試結果而不是實現
非正常路徑覆蓋	只有正常路徑：到處都沒有空狀態、錯誤或許可權狀態	列了一些邊界情況，但關鍵失敗模式（空狀態、流程中途失敗、許可權邊界）缺失或含糊	空狀態、錯誤狀態、許可權邊界和已知的技術約束都作為明確的驗收標準或邊界情況出現，並定義了行為
範圍紀律與大小	故事有史詩那麼大、相互依賴，沒有"不在範圍內"部分	有"不在範圍內"，但很籠統；有些故事太大，無法估算或在一個迭代內獨立交付	每個故事都能在一個迭代內完成、可以獨立交付，拆分有記錄的理由，"不在範圍內"寫明下一個故事從哪裡開始

品質檢查

• 每個故事都有具體的使用者型別，而不是"一個使用者"或"系統"
• "以便"解釋了業務價值，而不只是功能描述
• 每條驗收標準只測試一個可觀察的結果，而不是一組行為
• 明確處理了空狀態、錯誤狀態和邊界情況
• 寫明瞭不在範圍內的內容，而不是預設
• 故事相互獨立：可以單獨交付，不依賴未釋出的工作（明確說明的除外）

反模式

• 不要從技術角度寫使用者故事：每個故事都必須從使用者的視角出發，寫明他們的目標
• 不要寫無法測試的驗收標準：每條標準都必須有清楚的透過 / 不透過條件
• 不要寫一個迭代內完成不了的故事：把史詩拆成可估算、可獨立交付的故事
• 不要省略邊界情況：非正常路徑和錯誤狀態是必需的，不是可選的
• 不要跳過完成定義：沒有它，"完成"對不同的人意味著不同的東西

示例觸發語

• “根據這份說明為 [功能] 寫使用者故事”
• “把這部分 PRD 拆成帶驗收標準的使用者故事”
• “把這些功能需求轉成 Jira 任務”
• “為 [功能名稱] 寫使用者故事和驗收標準”
• “把這個史詩拆成可以進入迭代規劃的獨立故事”