docs: update documents

Author: 薛華慶, james.hsueh

README.md

@@ -136,7 +136,7 @@ cd your-project
 
 ## 🔄 工作流程概覽
 
-### 四個階段
+### 核心四階段（必需）
 
 ```
 Phase 1：規格（PM）
@@ -156,16 +156,34 @@ Phase 4：驗證（QA）
     ✅ 驗證結論報告
 ```
 
+### 選用階段：Integration Tests
+
+```
+Phase 2.5：整合測試（選用）
+    ↓
+    在實作前生成 Integration Tests
+    ↓
+    測試先行開發（紅燈 → 綠燈）
+```
+
+**何時使用 `/sdd-integration-test`？**
+- ✅ 團隊實踐 BDD 測試先行
+- ✅ 需要完整的整合測試覆蓋
+- ✅ 複雜的業務邏輯需要驗證
+- ❌ 簡單的 CRUD 功能
+- ❌ 原型開發階段
+- ❌ 時程緊迫的專案
+
 ### 指令
 
-| 指令                    | 用途                             | 何時使用           |
-| ----------------------- | -------------------------------- | ------------------ |
-| `/sdd-auto`             | 自動執行全部 4 個階段            | 快速原型、簡單功能 |
-| `/sdd-spec`             | 生成 Gherkin 規格                | 定義需求           |
-| `/sdd-arch`             | 設計資料模型與介面               | 審查結構           |
-| `/sdd-integration-test` | 生成 Integration Tests（紅燈）   | BDD 測試先行開發   |
-| `/sdd-impl`             | 實作邏輯                         | 撰寫程式碼         |
-| `/sdd-verify`           | 根據規格驗證                     | 測試實作           |
+| 指令                    | 用途                             | 何時使用           | 是否必需 |
+| ----------------------- | -------------------------------- | ------------------ | -------- |
+| `/sdd-auto`             | 自動執行全部 4 個階段            | 快速原型、簡單功能 | -        |
+| `/sdd-spec`             | 生成 Gherkin 規格                | 定義需求           | ✅ 必需  |
+| `/sdd-arch`             | 設計資料模型與介面               | 審查結構           | ✅ 必需  |
+| `/sdd-integration-test` | 生成 Integration Tests（紅燈）   | BDD 測試先行開發   | 🔷 選用  |
+| `/sdd-impl`             | 實作邏輯                         | 撰寫程式碼         | ✅ 必需  |
+| `/sdd-verify`           | 根據規格驗證                     | 測試實作           | ✅ 必需  |
 
 ---
 

docs/COMMANDS.md

@@ -4,15 +4,24 @@
 
 ## 指令概覽
 
+### 核心工作流程（必需）
+
 ```
 /sdd-auto              → 自動模式：自動執行全部 4 個 Phase
 /sdd-spec              → Phase 1：生成 Gherkin 規格
 /sdd-arch              → Phase 2：設計架構（繁中文件）
-/sdd-integration-test  → BDD：生成 Integration Tests（測試先行）
 /sdd-impl              → Phase 3：實作邏輯
 /sdd-verify            → Phase 4：驗證實作
 ```
 
+### 選用指令
+
+```
+/sdd-integration-test  → 🔷 選用：生成 Integration Tests（BDD 測試先行）
+```
+
+> **💡 提示：** `/sdd-integration-test` 適合重視測試先行開發的團隊，在 Phase 2 之後、Phase 3 之前使用。
+
 ---
 
 ## `/sdd-auto` - 自動模式
@@ -110,10 +119,12 @@
 
 ---
 
-## `/sdd-integration-test` - BDD Integration Tests
+## `/sdd-integration-test` - BDD Integration Tests（選用）
 
 **目的：** 從 feature file 和 architecture.md 生成 integration tests（測試先行），測試會失敗（紅燈），等待實作後轉為通過（綠燈）。
 
+> **🔷 此為選用階段**：適合實踐 BDD 測試先行的團隊。如果您的專案不需要測試先行開發，可以跳過此階段直接使用 `/sdd-impl`。
+
 **用法：**
 ```bash
 /sdd-integration-test <feature_file_path>
@@ -142,16 +153,22 @@
 **BDD 工作流程：**
 1. **規格階段**：定義 feature file（`/sdd-spec`）
 2. **架構階段**：設計技術架構（`/sdd-arch`）
-3. **測試階段**（本指令）：生成 integration tests（🔴 紅燈）
+3. **測試階段**（本指令，🔷 選用）：生成 integration tests（🔴 紅燈）
 4. **實作階段**：實作功能（`/sdd-impl`）
 5. **驗證階段**：確認測試通過（`/sdd-verify` → 🟢 綠燈）
 
 **何時使用：**
-- ✅ 完成 `/sdd-spec` 和 `/sdd-arch` 後
-- ✅ 需要先定義測試場景
-- ✅ 確保實作符合業務需求
+- ✅ 團隊實踐 BDD 測試先行開發
+- ✅ 需要完整的整合測試覆蓋
+- ✅ 複雜的業務邏輯需要驗證
 - ✅ 建立整合測試框架
-- ✅ 與 `/sdd-impl` 搭配使用（測試先行開發）
+- ✅ 與 `/sdd-impl` 搭配使用
+
+**何時跳過：**
+- ⏭️ 簡單的 CRUD 功能
+- ⏭️ 快速原型開發
+- ⏭️ 時程緊迫的專案
+- ⏭️ 團隊不熟悉 BDD
 
 **支援框架：**
 - **TypeScript**: Jest/Vitest + Supertest
@@ -218,29 +235,35 @@
 
 ## 工作流程比較
 
-### 自動模式流程
+### 標準工作流程（推薦）
 ```
 使用者需求
      ↓
-/sdd-auto <需求>
+/sdd-spec <需求>
      ↓
-[全部 4 個階段自動執行]
+[審查 Gherkin]
+     ↓
+/sdd-arch features/spec.feature
+     ↓
+[審查結構]
+     ↓
+/sdd-impl features/spec.feature
+     ↓
+[審查實作]
+     ↓
+/sdd-verify features/spec.feature
      ↓
 完整功能
 ```
 
 **優點：**
-- ⚡ 最快獲得可運作程式碼的方式
-- 🎯 單一指令
-- 🔄 適合迭代
-
-**缺點：**
-- 🚫 階段之間無手動審查
-- 🚫 如果複雜可能需要重做
+- 🎯 流程清晰，易於理解
+- ⚡ 開發速度快
+- 📋 適合大多數專案
 
 ---
 
-### 手動模式流程
+### BDD 測試先行工作流程（選用）
 ```
 使用者需求
      ↓
@@ -252,23 +275,51 @@
      ↓
 [審查結構]
      ↓
-/sdd-impl features/spec.feature structure/struct.py
+/sdd-integration-test features/spec.feature  🔷 選用
      ↓
-[審查實作]
+[審查測試 - 紅燈]
+     ↓
+/sdd-impl features/spec.feature
      ↓
-/sdd-verify features/spec.feature implementation/impl.py
+[審查實作 - 綠燈]
+     ↓
+/sdd-verify features/spec.feature
+     ↓
+完整功能 + 完整測試
+```
+
+**優點：**
+- 🎯 測試先行，品質更高
+- 📋 完整的整合測試覆蓋
+- 🔍 更適合複雜業務邏輯
+
+**缺點：**
+- ⏱️ 需要額外時間
+- 🔢 需要更多步驟
+- 📚 團隊需熟悉 BDD
+
+---
+
+### 自動模式流程
+```
+使用者需求
+     ↓
+/sdd-auto <需求>
+     ↓
+[全部 4 個階段自動執行]
      ↓
 完整功能
 ```
 
 **優點：**
-- 🎯 每個階段完全控制
-- 📋 手動審查檢查點
-- 🔍 更適合複雜功能
+- ⚡ 最快獲得可運作程式碼的方式
+- 🎯 單一指令
+- 🔄 適合迭代
 
 **缺點：**
-- ⏱️ 更耗時
-- 🔢 需要多個指令
+- 🚫 階段之間無手動審查
+- 🚫 不包含 integration tests
+- 🚫 如果複雜可能需要重做
 
 ---
 
@@ -277,15 +328,16 @@
 | 情境 | 建議指令 |
 |----------|-------------------|
 | "快速原型展示" | `/sdd-auto` |
-| "需要團隊審查的生產功能" | 手動階段 |
+| "需要團隊審查的生產功能" | 標準工作流程 |
 | "學習 SDD 方法論" | 先使用 `/sdd-auto`，然後嘗試手動 |
 | "API 契約設計" | `/sdd-spec` + `/sdd-arch` |
-| "複雜業務邏輯" | 手動階段 |
+| "複雜業務邏輯" | 標準工作流程 |
 | "測試想法" | `/sdd-auto` |
 | "遷移現有程式碼" | 先使用 `/sdd-spec` |
-| "需要利害關係人批准" | 手動階段 |
-| "BDD 測試先行開發" | `/sdd-integration-test` + `/sdd-impl` |
-| "建立整合測試" | `/sdd-integration-test` |
+| "需要利害關係人批准" | 標準工作流程 |
+| "BDD 測試先行開發" | BDD 測試先行工作流程（含 `/sdd-integration-test`） |
+| "建立整合測試框架" | `/sdd-integration-test` |
+| "簡單 CRUD 功能" | 標準工作流程（跳過 `/sdd-integration-test`） |
 
 ---
 
@@ -374,12 +426,15 @@ pipx run gsi-protocol-installer
 **快速參考卡：**
 
 ```
-快速原型          → /sdd-auto <需求>
-生產程式碼        → /sdd-spec → /sdd-arch → /sdd-impl → /sdd-verify
-BDD 測試先行開發  → /sdd-spec → /sdd-arch → /sdd-integration-test → /sdd-impl → /sdd-verify
-只要規格          → /sdd-spec <需求>
-只要架構          → /sdd-arch <spec.feature>
-只要整合測試      → /sdd-integration-test <spec.feature>
-只要程式碼        → /sdd-impl <spec.feature>
-只要驗證          → /sdd-verify <spec.feature>
+快速原型                → /sdd-auto <需求>
+
+標準工作流程（推薦）    → /sdd-spec → /sdd-arch → /sdd-impl → /sdd-verify
+
+BDD 測試先行（選用）    → /sdd-spec → /sdd-arch → /sdd-integration-test → /sdd-impl → /sdd-verify
+
+只要規格                → /sdd-spec <需求>
+只要架構                → /sdd-arch <spec.feature>
+只要整合測試（選用）    → /sdd-integration-test <spec.feature>
+只要程式碼              → /sdd-impl <spec.feature>
+只要驗證                → /sdd-verify <spec.feature>
 ```