AppFuse WebApp 開發方法論

本目錄提供使用 AppFuse 框架開發應用程式的完整方法論與指南，涵蓋從 Prototype 到生產環境的完整流程。

---

文檔定位

┌─────────────────────────────────────────────────────────────────┐
│  appfuse-docs/                                                  │
│                                                                 │
│  docs-methodology/  開發方法論與指南 (本目錄)                      │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  - 提供通用的開發流程指引                                   │  │
│  │  - 提供文檔撰寫規範與範本                                   │  │
│  │  - 可獨立存在，供任何使用框架的團隊參考                      │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              ↓ 實際案例                         │
│  docs-specs/florist/  應用規格（所有模組共用）                     │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  - 花店管理系統的產品規格                                   │  │
│  │  - 展示方法論的具體應用                                     │  │
│  │  - 包含完整的 Epic、User Stories、SBE、API 規格            │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              ↓ 框架文檔                         │
│  docs-web/  前端框架文檔          docs-server/  後端框架文檔      │
│  ┌──────────────────────────┐  ┌──────────────────────────┐   │
│  │  - 元件使用指南            │  │  - 模組使用指南            │   │
│  │  - 設計概念與 ADR          │  │  - 設計指南與 ADR          │   │
│  └──────────────────────────┘  └──────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

---

文檔索引

核心指南

文檔	說明
Skills 即方法論	方法論設計哲學：Skills 組成方法論、完整採用 vs 選擇性採用、品質閘門鏈
開發流程指南	Step 1–4 開發流程、US 四階段追蹤模型
規格撰寫指南	各類文檔（Epic、US、SBE 等）的撰寫規範、範本與建議目錄結構
Claude Code Skills 總覽	22 個 Skill 快速參考索引
AI 協助規格撰寫	蘇格拉底式閉環、AI Skill 使用指南

技術指南

文檔	說明
部署指南	生產環境部署說明
yalc 工作流程	框架本地測試流程（特殊場景用）

決策記錄

ADR	說明
ADR-001: AI 協助規格撰寫策略	採用蘇格拉底式閉環模式的決策與權衡
ADR-002: US 需求變更管理策略	變更後 US 重新進入 Sprint 的管理機制

實際案例

位置	說明
花店管理系統規格	產品規格：Roadmap、Epic、US、SBE、API 規格、ADR
前端框架文檔	元件使用指南、設計概念與 ADR
後端框架文檔	模組使用指南、設計指南與 ADR

---

開發流程總覽

本框架採用 SCRUM + SBE 方法論，分四個階段將功能從 Prototype 推進到生產環境：

1. Step 1 — Prototype 開發（app-office-mockup + MSW Mock API）
2. Step 2 — 程式碼同步（app-office-mockup → app-office）
3. Step 3 — 後端開發 + 漸進式整合（app-office ↔ app-server）
4. Step 4 — 完全整合與生產部署

每個 User Story 在 Sprint 內以 🔲 → P.E2E → P.UAT → I.E2E → ✅ 五個階段追蹤進度。

詳細流程與圖表請參閱 開發流程指南。

---

文檔層級架構

使用本框架開發應用程式時，建議按以下層級建立規格文檔：

Roadmap（為什麼做）
  → Feature List（使用者能做什麼）
    → Domain Model（業務實體與統一語言）
      → Epic（功能群組）
        → User Story（可開發的功能切片）
          → SBE（具體測試場景）
            → API Spec（REST API 合約）

完整的目錄模板與各類文檔的撰寫規範請參閱 規格撰寫指南。

---

新團隊上手指南

以下是新團隊從零開始使用 AppFuse 方法論的完整路徑，分為 6 個階段。每個階段列出要做什麼、用什麼工具、產出什麼。

階段 1：理解方法論

目標：團隊成員了解 AppFuse 的開發流程與文檔體系。

閱讀順序	文檔	重點
1	本頁面	方法論總覽與文檔定位
2	開發流程指南	4-Step 開發流程、US 四階段追蹤模型
3	規格撰寫指南	文檔層級架構、各類範本
4	AI 協助規格撰寫	AI Skill 的使用方式與原則
5	花店管理系統規格	瀏覽實際案例，建立具體印象

階段 2：建立專案

目標：用 Skill 自動建立專案骨架與初始模組。

/scaffold-project → 建立專案目錄結構與 project.json
    ↓
/scaffold-module web-mockup → 前端 Prototype 模組（提案階段）
/scaffold-module docs → 文檔站模組（提案階段）

產出：專案目錄、project.json、前端 Prototype 模組、文檔站。

技術環境設定請參閱 開發環境設定指南。

階段 3：撰寫規格

目標：從產品構想到可開發的 User Story，建立完整的規格文檔鏈。

/roadmap           → 產出 Roadmap + Feature List
    ↓
/domain-model      → 建立領域模型（業務實體、關聯、術語）
    ↓
/epic              → 從 Roadmap 拆分 Epic 文檔
    ↓
/us                → 撰寫 User Story（對話式澄清循環）
    ↓
/sbe               → 從 US 產生 SBE 測試場景
    ↓
/checklist         → 檢核 US 品質（選用）
/analyze           → 跨文件一致性分析（選用）

產出：roadmap.md、feature-list.md、domain-model.md、Epic 文檔、US 文檔、SBE 場景。

規格撰寫採用蘇格拉底式閉環——人提供方向與決策，AI 提供結構與完整性。詳見 AI 協助規格撰寫指南。

階段 4：規劃 Sprint

目標：從可用的 US 庫存中選取 Sprint 範圍，排定工作。

/sprint            → 盤點 US 庫存，選取 Sprint Backlog

產出：progress/sprints/sprint-{N}.md，Feature List 狀態更新為 🚧。

階段 5：開發與追蹤

目標：按 4-Step 流程開發功能，逐步推進 US 階段。

開發步驟	做什麼	完成後
Step 1	在 web-mockup 用 MSW 開發 Prototype	/progress US-NNN P.E2E
PO 驗收	PO 手動驗收 Prototype	/progress US-NNN P.UAT
Step 2-3	同步至 web，開發 server，漸進式整合	/progress US-NNN I.E2E
整合驗收	PO 驗收整合環境	/progress US-NNN ✅

輔助工具：

/e2e               → 從 SBE 產生 Playwright E2E 測試
/test-plan         → 產生手動測試指南
/api-spec          → 產生 API 規格（正向設計或反向萃取）

階段 6：迭代

目標：完成當前 Sprint 後，規劃下一輪。

Sprint N 完成
    ↓
/sprint            → 規劃 Sprint N+1
    ↓
重複階段 5

需求變更時：使用 /us US-NNN 進入變更模式，同一 US 編號帶著版本記錄重新進入新 Sprint。詳見 ADR-002。

---

新團隊檢查清單

用於確認團隊上手進度，逐項完成：

方法論理解

• 團隊成員已閱讀開發流程指南
• 團隊成員已閱讀規格撰寫指南
• 團隊成員已瀏覽花店系統規格範例

專案建立

• 已執行 /scaffold-project 建立專案骨架
• 已執行 /scaffold-module 建立初始模組（至少 web-mockup + docs）
• 開發環境可正常啟動（npm run dev）

規格撰寫

• 已完成 Roadmap（/roadmap）
• 已完成 Feature List（隨 Roadmap 產出或 /feature-list）
• 已完成至少 1 個 Epic（/epic）
• 已完成至少 1 個 US（/us）
• 已完成至少 1 組 SBE 場景（/sbe）

第一個 Sprint

• 已規劃第一個 Sprint（/sprint）
• 至少 1 個 US 推進到 P.E2E（/progress）
• PO 已驗收至少 1 個 Prototype（P.UAT）

---

相關資源

方法論參考

• User Story Mapping - Jeff Patton
• Specification by Example - Gojko Adzic
• INVEST in Good Stories - Bill Wake
• MADR - Markdown Any Decision Records

BDD / Given-When-Then

• Cucumber Documentation
• Gherkin Syntax

---

最後更新: 2026-03-16