跳至主要内容

ADR-002: User Story 需求變更管理策略

ADR 編號: 002 狀態: 已接受 (Accepted) 決策日期: 2026-02-26 決策者: AppFuse Team 範圍: docs-methodology（開發方法論）

摘要​

當已完成的 User Story 因需求變更需要修改規格時，採用「同 US 編號重新進入 Sprint + 變更記錄」的方式管理，保持規格文檔為活文件，同時不破壞 Sprint 歷史記錄。

背景 (Context)​

問題陳述​

AppFuse 的規格文檔（US / SBE）在 Sprint 中完成驗收後，可能因業務需求變化而需要修改。目前方法論未定義此情境的處理流程，導致以下問題：

  • 規格文檔 是否應直接修改？還是保留舊版？
  • Sprint 歷史記錄 中已標記 ✅ 的 US，是否需要回退？
  • 實作進度 如何表達「曾完成但需重做」？

核心張力​

規格文檔作為「活文件」需反映最新需求，但 Sprint 記錄作為「歷史快照」不應被修改。兩者之間需要明確的分界與銜接機制。

限制條件​

  • Sprint 文檔是歷史記錄，修改會破壞可追溯性
  • US 編號是整個文檔鏈（US → SBE → E2E → API Spec）的索引鍵，變更編號的代價高
  • 團隊需要快速判斷一個 US 是全新開發還是變更後重做

考量的方案 (Options Considered)​

方案 A: 同 US 編號重新進入 Sprint + 變更記錄​

說明: US 規格直接更新為最新版本，在 US 文檔中加入變更歷史區段。同一個 US 編號可重新進入新的 Sprint，Sprint Backlog 中標註為變更重做。

優點:

  • ✅ 簡單自然，US 編號不變，文檔鏈完整
  • ✅ 變更歷史提供完整的演進脈絡
  • ✅ Sprint 歷史不被修改

缺點:

  • ❌ 新舊 Sprint 的同一 US 驗收範圍不同，需靠標註區分

評分: 5/5

方案 B: 拆出新 US 描述差異部分​

說明: 保留原 US 為已完成狀態，新增 US（如 US-201a 或 US-213）描述變更的部分。

優點:

  • ✅ 變更範圍明確，歷史清晰
  • ✅ 新舊 US 各自獨立

缺點:

  • ❌ 變更幅度大時拆分不自然（如修改核心驗證規則）
  • ❌ 文檔鏈分裂（SBE、E2E 要跟著拆分）
  • ❌ US 編號管理複雜化

評分: 2/5

方案 C: 建立獨立的變更請求文檔​

說明: 為每次變更建立獨立的 Change Request 文檔，記錄變更內容與影響分析。

優點:

  • ✅ 變更管理最嚴謹
  • ✅ 適合大型團隊與合規需求

缺點:

  • ❌ 流程過重，不適合小團隊
  • ❌ 增加文檔管理負擔
  • ❌ 規格散落在多處，難以了解 US 的最新狀態

評分: 1/5

決策 (Decision)​

選擇方案: A — 同 US 編號重新進入 Sprint + 變更記錄

核心理由:

  1. US 編號是文檔鏈的索引鍵，保持不變可避免連鎖修改
  2. 變更歷史提供足夠的追溯性，不需要獨立的變更請求文檔
  3. Sprint Backlog 的 🔄 標註能清楚區分全新開發與變更重做

權衡分析 (Trade-offs)​

我們獲得什麼 (Gains)​

  • ✅ 規格文檔始終反映最新需求（活文件原則）
  • ✅ Sprint 歷史記錄完整不被篡改
  • ✅ 透過變更歷史可追溯 US 的演進脈絡
  • ✅ 流程簡單，不增加額外文檔管理負擔

我們放棄什麼 (Losses)​

  • ❌ 無法從 US 文檔直接看到「v1 的完整內容」（只有變更摘要）

風險與緩解措施 (Risks & Mitigations)​

風險嚴重性機率緩解措施
變更歷史未維護，失去追溯性中中/us Skill 更新時提示填寫變更歷史
新 Sprint 未標註 🔄，與全新開發混淆低低/sprint Skill 偵測重複 US 時自動標註

實作指南 (Implementation Guidelines)​

1. US 文檔：新增 ## 變更歷史 區段​

在 US 文檔底部（## 相關文檔 之前）加入：

## 變更歷史

| 版本 | 日期 | 說明 | 影響 Sprint |
|------|------|------|------------|
| v1 | 2025-10-15 | 初版 | Sprint 2 |
| v2 | 2026-01-10 | 新增批量匯入功能，調整驗證規則 | Sprint 7 |

規則:

  • 初版標記為 v1，後續依序遞增
  • 說明 欄簡述變更重點，不需完整 diff
  • 影響 Sprint 記錄該版本被哪個 Sprint 納入

2. SBE / E2E / API Spec：同步更新​

US 規格變更後，相關的下游文檔應一併更新：

  • SBE 場景：修改或新增受影響的 scenario
  • E2E 測試：更新對應的測試案例
  • API Spec：更新受影響的端點規格

3. Sprint Backlog：標註變更重做​

變更後的 US 重新進入 Sprint 時，在備註欄標註：

| # | US | 標題 | SP | 目標 | 備註 |
|---|-----|------|----|------|------|
| 1 | US-201 | 創建訂單 | 3 | P.UAT | 🔄 v2 變更 |

規則:

  • 🔄 標記表示此 US 為變更重做，非全新開發
  • 版本號對應 US 文檔中的變更歷史版本
  • Story Points 只估算差異部分的工作量（非整個 US 重估）

4. 舊 Sprint 記錄：不修改​

原 Sprint 中的 ✅ 維持不變，代表「該版本的規格在當時通過驗收」。

影響 (Consequences)​

正面影響​

  • ➕ 方法論補齊了需求變更的處理流程
  • ➕ 規格文檔、Sprint 記錄、實作進度三者的關係更明確

負面影響​

  • ➖ /us 和 /sprint Skill 需要更新以支援變更歷史與 🔄 標註

待辦事項​

  • 更新 /us Skill：支援變更歷史區段
  • 更新 /sprint Skill：偵測重複 US 時自動標註 🔄
  • 更新 US 文檔模板（user-stories/README.md）：加入變更歷史區段

相關文檔 (References)​

內部文檔​

變更歷史 (Change Log)​

日期變更內容變更者
2026-02-26初版AppFuse Team + AI Assistant

文檔維護者: AppFuse Team + AI Assistant 最後審閱: 2026-02-26