---
source: ../../../adoption/DAILY-WORKFLOW-GUIDE.md
source_version: 1.1.0
translation_version: 1.1.0
last_synced: 2026-02-10
status: current
---

# 日常開發工作流程指南

**版本**: 1.1.0
**最後更新**: 2026-02-10

> **語言**: [English](../../../adoption/DAILY-WORKFLOW-GUIDE.md) | 繁體中文

本指南說明在執行 `uds init` 後，如何在日常開發工作流程中使用 Universal Development Standards。

---

## 目錄

- [Phase 0：專案現況評估](#phase-0專案現況評估)
- [核心原則：漸進式採用](#核心原則漸進式採用)
- [根據任務類型選擇工作流程](#根據任務類型選擇工作流程)
- [Greenfield 與 Brownfield 專案](#greenfield-與-brownfield-專案)
- [舊有程式碼採用策略](#舊有程式碼採用策略)
- [場景式工作流程](#場景式工作流程)
- [可用命令快速參考](#可用命令快速參考)
- [品質檢查點](#品質檢查點)
- [何時撰寫完整規格](#何時撰寫完整規格)
- [最佳實踐總結](#最佳實踐總結)
- [相關標準](#相關標準)
- [版本歷史](#版本歷史)
- [授權](#授權)

---

## Phase 0：專案現況評估

> **使用時機**：首次接觸既有程式碼庫，或在不熟悉的模組進行重大變更之前。

在 Brownfield 專案進行程式碼變更之前，先執行 `/discover` 評估現況：

```
1. /discover [area]     → 評估專案健康度、架構、風險
2. /reverse spec        → 反向工程現有程式碼為規格（如有需要）
3. /sdd                 → 撰寫新功能規格
4. 實作                  → 使用 /tdd 或 /bdd 在測試保護下實作
```

### 評估維度

| 維度 | 檢查項目 |
|------|----------|
| **架構** | 模組結構、相依圖、進入點 |
| **相依性** | 過時套件、已知漏洞、授權風險 |
| **測試覆蓋** | 現有測試、覆蓋率缺口、測試品質 |
| **安全性** | `npm audit` 結果、硬編碼密鑰、暴露端點 |
| **技術債** | TODO 標記、程式碼重複、複雜度熱點 |

### 輸出

Discovery Report 提供：
- 整體健康度分數（1-10）
- 各維度分數與關鍵發現
- **結論**：GO / NO-GO / CONDITIONAL
- 優先級排序的建議（HIGH / MED / LOW）

> **下一步**：評估完成後，如需理解現有程式碼請使用 `/reverse`，然後用 `/sdd` 設計新功能。

---

## 核心原則：漸進式採用

### 常見誤解 vs 實際做法

```
┌─────────────────────────────────────────────────────────────────┐
│                    ❌ 誤解 vs ✅ 實際做法                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ❌ 誤解：                                                       │
│  「必須先為所有舊程式碼寫完規格和測試，才能開始任何新開發」        │
│                                                                 │
│  ✅ 實際做法：                                                   │
│  「只在『觸碰』現有程式碼時，才漸進式地添加測試和文件」           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 童子軍原則 (Boy Scout Rule)

> 「離開時比來時乾淨一點」

- 反向工程整個系統是不切實際且價值有限的
- 專注於**增量改善**，而非**一次到位**
- 每次觸碰程式碼時，添加一點保護（測試、文件）

---

## 根據任務類型選擇工作流程

### 決策樹

```
┌─────────────────────────────────────────────────────────────────┐
│                    任務類型 → 工作流程選擇                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  第一次接觸這個程式碼庫？                                        │
│  │                                                              │
│  ├─ 是 → 先執行 /discover（Phase 0 評估）                       │
│  │                                                              │
│  └─ 否（熟悉程式碼庫）                                          │
│                                                                 │
│  這是全新功能嗎？                                                │
│  │                                                              │
│  ├─ 是（Greenfield）                                            │
│  │   └─ 使用完整流程：ATDD → SDD → BDD → TDD                   │
│  │                                                              │
│  └─ 否（Brownfield/Legacy）                                     │
│      │                                                          │
│      ├─ 修改範圍大嗎？（架構級、跨模組）                         │
│      │   │                                                      │
│      │   ├─ 是 → Golden Master + SDD                           │
│      │   │       （需要規格和完整測試保護）                      │
│      │   │                                                      │
│      │   └─ 否 → 只改單一模組/函數                              │
│      │       │                                                  │
│      │       ├─ 有現有測試嗎？                                  │
│      │       │   │                                              │
│      │       │   ├─ 有 → 直接 TDD 循環                          │
│      │       │   │                                              │
│      │       │   └─ 沒有 → 先寫特徵測試                         │
│      │       │                                                  │
│      │       └─ 是 Bug 修復嗎？                                 │
│      │           │                                              │
│      │           ├─ 是 → 寫失敗測試 → 修復                       │
│      │           │                                              │
│      │           └─ 否 → TDD 添加新行為                         │
│      │                                                          │
│      └─ 是純重構（不改變行為）嗎？                              │
│          │                                                      │
│          ├─ 是 → 確保測試覆蓋 → 重構 → 測試通過                 │
│          │                                                      │
│          └─ 否 → 混合：保護現有 + TDD 新功能                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## Greenfield 與 Brownfield 專案

### 定義

| 專案類型 | 描述 | 範例 |
|----------|------|------|
| **Greenfield** | 新專案或功能，沒有現有程式碼 | 新微服務、新模組 |
| **Brownfield** | 現有程式碼庫，有舊有程式碼 | 維護、為現有系統添加功能 |

### 工作流程比較

| 面向 | Greenfield | Brownfield |
|------|------------|------------|
| **規格** | 撰寫完整規格 (SDD) | 只有重大變更才需要 |
| **測試** | 從頭開始 TDD | 先寫特徵測試 |
| **文件** | 邊做邊建立 | 增量添加 |
| **方法論** | 完整 ATDD → SDD → BDD → TDD | 根據範圍簡化 |

---

## 舊有程式碼採用策略

### 策略 1：修改現有程式碼（Bug 修復/小改動）

```
┌────────────────────────────────────────────────────────────────┐
│           舊有程式碼修改（Golden Master 策略）                   │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  1️⃣  理解現有行為（不寫規格，寫測試）                           │
│      ├─ 閱讀程式碼，理解當前行為                               │
│      ├─ 撰寫「特徵測試」(Characterization Test)                │
│      │   捕捉現有行為（不管對錯）                              │
│      └─ 這個測試是你的「安全網」                               │
│                                                                │
│  2️⃣  修改程式碼                                                │
│      ├─ 在測試保護下進行修改                                   │
│      ├─ 如果測試失敗，你知道改壞了什麼                         │
│      └─ Bug 修復：先讓測試失敗，再修復                         │
│                                                                │
│  3️⃣  提交（不需要完整 Spec）                                   │
│      └─ Commit message 描述變更即可                            │
│                                                                │
│  ⚠️  重點：不需要 SPEC 文件，不需要完整 BDD 場景                │
│                                                                │
└────────────────────────────────────────────────────────────────┘
```

**範例：修復驗證 Bug**

```typescript
// 1. 寫特徵測試，捕捉現有行為
test('characterization: login validates email format', () => {
  // 觀察現有程式碼怎麼做，然後記錄下來
  const result = validateEmail('invalid');
  expect(result).toBe(false); // 記錄現有行為
});

// 2. 寫一個會失敗的測試描述 Bug
test('should reject email without domain', () => {
  const result = validateEmail('user@');
  expect(result).toBe(false); // 目前可能是 true（Bug）
});

// 3. 修復 Bug，讓測試通過
// 4. 提交
```

### 策略 2：為現有功能添加新行為

```
┌────────────────────────────────────────────────────────────────┐
│              功能擴展（混合策略）                                │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  1️⃣  保護現有行為                                              │
│      └─ 為將要修改的區域寫特徵測試                             │
│                                                                │
│  2️⃣  定義新行為（簡化版 TDD/BDD）                              │
│      ├─ 寫新功能的測試（TDD）                                  │
│      ├─ 或寫 Given-When-Then 場景（BDD）                       │
│      └─ 不需要完整的 Spec Workshop                             │
│                                                                │
│  3️⃣  實作新功能                                                │
│      └─ 在測試保護下實作                                       │
│                                                                │
│  4️⃣  重構（可選）                                              │
│      └─ 如果有時間，改善觸碰到的舊程式碼                        │
│                                                                │
└────────────────────────────────────────────────────────────────┘
```

### 策略 3：重大重構/架構改動

```
┌────────────────────────────────────────────────────────────────┐
│              重大變更（需要 Spec）                               │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  ⚠️  只有這種情況才需要較完整的流程                             │
│                                                                │
│  0️⃣  評估現況（Discovery + 反向工程）                          │
│      ├─ /discover 評估專案健康度與風險                          │
│      ├─ /reverse spec 反向工程現有程式碼                        │
│      └─ 輸出：Discovery Report + 現有規格                      │
│                                                                │
│  1️⃣  撰寫變更規格（SDD）                                       │
│      ├─ 描述為什麼要重構                                       │
│      ├─ 定義影響範圍                                           │
│      └─ 驗收條件：系統行為不變                                 │
│                                                                │
│  2️⃣  建立 Golden Master 測試                                   │
│      ├─ 記錄系統當前的所有輸出                                 │
│      ├─ 使用 Snapshot Testing / Approval Testing               │
│      └─ 這是你的「正確答案」                                    │
│                                                                │
│  3️⃣  進行重構                                                  │
│      ├─ 每一步都確保 Golden Master 測試通過                    │
│      └─ 如果測試失敗 → 立即回退                                │
│                                                                │
│  4️⃣  逐步將 Golden Master 轉換為正式測試                       │
│      └─ 隨時間改善測試品質                                     │
│                                                                │
└────────────────────────────────────────────────────────────────┘
```

---

## 場景式工作流程

### 場景 A：新功能開發（完整流程）

適用於需要利害關係人驗收的重要新功能：

```
1️⃣  ATDD 階段：定義「完成」標準
    ├─ 舉辦 Specification Workshop
    ├─ PO、開發者、QA 共同定義驗收條件
    └─ 明確定義「範圍外」項目
    💡 命令：/atdd

2️⃣  SDD 階段：討論與撰寫技術規格
    ├─ 討論：捕捉灰色地帶、鎖定範圍、建立 read_first 清單
    ├─ 根據 AC 撰寫技術設計文件
    ├─ 技術審查並獲得批准
    └─ 輸出：SPEC-XXX 文件
    💡 命令：/sdd discuss → /sdd create

3️⃣  BDD 階段：撰寫行為規格
    ├─ Discovery：從 AC 識別場景
    ├─ Formulation：撰寫 Gherkin Given-When-Then 場景
    └─ 輸出：Feature 檔案
    💡 命令：/bdd

4️⃣  TDD 階段：實作
    ├─ 🔴 RED：撰寫失敗測試
    ├─ 🟢 GREEN：最小化實作
    ├─ 🔵 REFACTOR：清理程式碼
    └─ 重複直到所有 BDD 場景通過
    💡 命令：/tdd

5️⃣  驗證與提交
    ├─ 展示給 PO，獲得正式驗收
    ├─ 提交程式碼
    └─ 歸檔規格文件
    💡 命令：/commit
```

### 場景 B：Bug 修復（簡化 TDD 流程）

```
1. 撰寫重現 Bug 的失敗測試
2. 修復 Bug 使測試通過
3. 重構（如有需要）
4. 提交並關聯 Issue

💡 命令：
- /tdd（進入 TDD 模式）
- /commit（自動生成規範的 commit message）
```

### 場景 C：小改動/快速修復

```
1. 如果觸碰沒有測試的現有程式碼：
   └─ 先寫特徵測試
2. 進行修改
3. 驗證測試通過
4. 提交

💡 不需要特別的方法論
```

### 場景 D：程式碼審查/PR

```
1. 使用系統性程式碼審查清單
2. 使用適當的評論前綴：
   - ❗ BLOCKING：必須在合併前修復
   - ⚠️ IMPORTANT：應該修復
   - 💡 SUGGESTION：建議改進
   - ❓ QUESTION：需要澄清

💡 命令：/review
```

---

## 可用命令快速參考

| 命令 | 用途 | 使用時機 |
|------|------|----------|
| `/discover` | 評估專案健康度與風險 | 首次接觸程式碼庫、重大變更前 |
| `/reverse` | 反向工程程式碼為規格/BDD/TDD | 理解現有程式碼 |
| `/tdd` | 啟動 TDD 工作流程 | 寫程式碼時 |
| `/bdd` | 啟動 BDD 工作流程 | 設計行為規格時 |
| `/sdd` | 啟動 SDD 工作流程 | 需要技術規格時 |
| `/atdd` | 啟動 ATDD 工作流程 | 需要正式驗收的功能 |
| `/refactor` | 啟動重構工作流程 | 改善程式碼結構 |
| `/methodology` | 查看/切換當前方法論 | 管理開發流程 |
| `/commit` | 生成規範的 commit message | 提交程式碼 |
| `/review` | 啟動程式碼審查 | 審查 PR |
| `/requirement` | 撰寫需求文件 | 定義 User Story |
| `/checkin` | 提交前品質驗證 | 提交程式碼前 |
| `/changelog` | 生成變更日誌條目 | 準備發布期間 |
| `/coverage` | 分析測試覆蓋率 | 評估測試品質 |
| `/docs` | 管理文件 | 撰寫/更新文件 |
| `/release` | 引導發布流程 | 準備發布 |

---

## 品質檢查點

### 提交前（透過 Git Hooks 自動執行）

```
✅ 所有測試通過
✅ 無 linting 錯誤
✅ 無洩漏的敏感資訊
```

### 建立 PR 前

```
✅ 符合 Check-in Standards
✅ Commit message 符合 Conventional Commits
✅ 測試覆蓋率未下降
```

### 程式碼審查時

```
✅ 程式碼通過 10 類審查清單
✅ 如有 Spec，實作符合規格
✅ 無範圍蔓延
```

---

## 何時撰寫完整規格

### 值得撰寫 Spec 的情況

| 場景 | 原因 |
|------|------|
| ✅ 跨團隊新功能 | 多方利害關係人需要對齊 |
| ✅ 需要 PO/利害關係人簽核的變更 | 需要正式驗收 |
| ✅ 架構級重構 | 高風險，需要文件化 |
| ✅ 外部 API 設計 | 合約定義 |
| ✅ 法規/合規變更 | 需要稽核軌跡 |

### 不需要撰寫 Spec 的情況

| 場景 | 原因 |
|------|------|
| ❌ 小 Bug 修復 | 低複雜度，測試足夠 |
| ❌ 程式碼清理/重構 | 無行為變更 |
| ❌ 內部工具改進 | 低儀式需求 |
| ❌ 效能優化 | 除非影響行為 |
| ❌ 依賴升級 | 例行維護 |

---

## 最佳實踐總結

### 舊專案採用優先順序

| 優先級 | 項目 | 原因 |
|--------|------|------|
| 🔴 高 | Commit Message 規範 | 零成本，立即受益 |
| 🔴 高 | Check-in Standards | 防止問題進入程式碼庫 |
| 🟡 中 | TDD（僅新程式碼） | 新程式碼有測試保護 |
| 🟡 中 | 特徵測試（觸碰的舊程式碼） | 增量添加安全網 |
| 🟢 低 | 完整 BDD/SDD | 只用於重大新功能 |
| 🟢 低 | 反向工程舊 Spec | 通常不值得 |

### 應該做與不應該做

```
┌─────────────────────────────────────────────────────────────────┐
│                    UDS 日常開發最佳實踐                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ✅ 應該做：                                                     │
│  ├─ 根據任務類型選擇方法論                                      │
│  ├─ 使用 /命令 啟動工作流程                                     │
│  ├─ 在實作前定義「完成」標準                                    │
│  ├─ 每次提交都通過品質檢查                                      │
│  └─ 讓 AI 追蹤你的當前階段                                      │
│                                                                 │
│  ❌ 不應該做：                                                   │
│  ├─ 跳過測試直接實作                                            │
│  ├─ 在沒有規格的情況下開發重大功能                              │
│  ├─ 忽略方法論系統的階段提醒                                    │
│  ├─ 提交未通過測試的程式碼                                      │
│  └─ 在開發過程中任意擴展範圍                                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 你不需要做的事

```
┌─────────────────────────────────────────────────────────────────┐
│                    UDS 舊專案採用策略                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ❌ 不需要：                                                     │
│  ├─ 為所有舊程式碼撰寫 Spec                                     │
│  ├─ 為所有舊程式碼撰寫測試                                      │
│  └─ 在開始工作前進行反向工程                                    │
│                                                                 │
│  ✅ 需要：                                                       │
│  ├─ 修改舊程式碼時，為觸碰的部分添加測試                        │
│  ├─ 新功能使用 TDD/BDD                                          │
│  ├─ 只有重大變更才撰寫 Spec                                     │
│  └─ 持續增量改善                                                │
│                                                                 │
│  📈 隨時間推移：                                                 │
│  測試覆蓋率會自然增長，因為你總是                               │
│  「觸碰一點，保護一點」                                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 相關標準

- [採用指南](ADOPTION-GUIDE.md) - 如何安裝 UDS
- [專案現況評估](../../../skills/project-discovery/SKILL.md) - Phase 0 專案評估
- [反向工程標準](../../../core/reverse-engineering-standards.md) - 反向工程工作流程
- [重構標準](../../../core/refactoring-standards.md) - 重構工作流程
- [測試驅動開發](../../../core/test-driven-development.md) - TDD 標準（包含 Golden Master Testing）
- [行為驅動開發](../../../core/behavior-driven-development.md) - BDD 工作流程
- [驗收測試驅動開發](../../../core/acceptance-test-driven-development.md) - ATDD 工作流程
- [規格驅動開發](../../../core/spec-driven-development.md) - SDD 工作流程
- [提交規範](../../../core/checkin-standards.md) - 程式碼提交要求
- [程式碼審查清單](../../../core/code-review-checklist.md) - 審查流程

---

## 版本歷史

| 版本 | 日期 | 變更 |
|------|------|------|
| 1.1.0 | 2026-02-10 | 新增 Phase 0 專案評估、/discover + /reverse + /refactor 命令 |
| 1.0.0 | 2026-01-19 | 初版日常工作流程指南 |

---

## 授權

本指南採用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權釋出。

**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)
