---
source: ../../../core/reverse-engineering-standards.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-01-19
status: current
---

# 反向工程標準

**版本**: 1.0.0
**最後更新**: 2026-01-19
**適用範圍**: 所有需要將程式碼轉換為規格文件的專案

> **語言**: [English](../../../core/reverse-engineering-standards.md) | [繁體中文](reverse-engineering-standards.md)

---

## 目的

本標準定義將現有程式碼反向工程為結構化規格文件的原則、工作流程和最佳實踐。反向工程是連接舊有系統與現代開發方法論（SDD → BDD → TDD）的橋樑。

**主要效益**：
- 將未文件化的程式碼轉換為可追溯的規格
- 在舊有系統上啟用現代開發實踐
- 在新團隊成員與現有程式碼庫之間建立共同理解
- 為未來增強和重構建立基礎

---

## 反向工程工作流程

```
┌──────────────────────────────────────────────────────────────────────────┐
│                         反向工程工作流程                                   │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌───────────┐  │
│  │  程式碼掃描  │───▶│  測試分析   │───▶│  缺口識別   │───▶│  規格生成  │  │
│  └─────────────┘    └─────────────┘    └─────────────┘    └───────────┘  │
│        │                  │                  │                  │        │
│        │                  │                  │                  ▼        │
│        │                  │                  │         ┌───────────────┐ │
│        │                  │                  │         │   人類審查    │ │
│        │                  │                  │         └───────────────┘ │
│        │                  │                  │                  │        │
│        ▼                  ▼                  ▼                  ▼        │
│    [已確認]            [已確認]            [未知]            [已驗證]      │
│    來自程式碼          來自測試           需人類輸入          規格文件     │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
```

### 工作流程階段

| 階段 | 說明 | 產出物 | 確定性層級 |
|------|------|--------|-----------|
| **程式碼掃描** | 分析程式碼結構、API、資料模型 | 技術清單 | [已確認] |
| **測試分析** | 解析現有測試以取得驗收條件 | 草擬驗收條件 | [已確認]/[推論] |
| **缺口識別** | 列出需要人類輸入的未知項目 | 缺口分析文件 | [未知] 項目 |
| **規格生成** | 生成草擬規格 | 草擬 SPEC-XXX.md | 混合確定性 |
| **人類審查** | 利害關係人驗證與填補缺口 | 已驗證的規格 | [已確認] |

---

## 核心原則

### 1. 確定性框架

所有提取的資訊必須標註確定性層級：

| 標籤 | 定義 | 範例 |
|------|------|------|
| `[已確認]` | 直接從程式碼或測試驗證 | "POST /api/users 端點位於 src/routes/users.ts:15" |
| `[推論]` | 從觀察到的模式進行邏輯推導 | "根據建構子模式，可能使用依賴注入" |
| `[假設]` | 需要驗證的合理假設 | "根據典型模式，session 可能在 24 小時後過期" |
| `[未知]` | 無法從程式碼判斷，需要人類輸入 | "此功能的商業動機" |

**規則**：有疑問時，使用更不確定的標籤，而非過度聲稱。

### 2. 反幻覺合規

本標準嚴格遵循[反幻覺標準](anti-hallucination.md)：

- **基於證據**：僅分析已明確讀取的內容
- **來源歸屬**：每項聲明必須包含 `[來源: 程式碼]` 或 `[來源: 測試]` 並附上 file:line 參考
- **禁止捏造**：未經驗證不得編造 API、配置或需求
- **明確未知**：始終列出無法從程式碼判斷的項目

### 3. 漸進式揭露

分層提取資訊：

1. **系統概覽**：入口點、主要元件、高層架構
2. **元件詳情**：各模組、其職責、介面
3. **實作細節**：演算法、資料流、邊界情況

### 4. 測試對需求映射

現有測試是隱含需求的寶貴來源：

```javascript
// 測試：src/tests/auth.test.ts
describe('Authentication', () => {
  it('should return 401 for invalid credentials', () => {...});
  it('should issue JWT token on successful login', () => {...});
});
```

映射為：

```markdown
## 驗收條件
[已確認] 來自測試分析 (src/tests/auth.test.ts)：
- [ ] 對無效憑證回傳 401 狀態碼 (第 3 行)
- [ ] 登入成功時核發 JWT token (第 4 行)
```

---

## 可提取與不可提取的內容

### 可提取（AI 自動化）

| 面向 | 確定性 | 來源 |
|------|--------|------|
| API 端點 | [已確認] | 路由定義、控制器 |
| 資料模型 | [已確認] | 型別、介面、Schema |
| 函數簽名 | [已確認] | 參數、回傳型別 |
| 測試案例 | [已確認] | 測試檔案 → 驗收條件 |
| 相依性 | [已確認] | 套件引用、匯入 |
| 配置模式 | [已確認] | 配置檔案 |
| 行為模式 | [推論] | 程式碼分析 |

### 不可提取（需要人類輸入）

| 面向 | 原因 | 必要行動 |
|------|------|---------|
| **動機/為什麼** | 歷史脈絡不在程式碼中 | 詢問利害關係人 |
| **商業背景** | 領域知識 | 詢問產品負責人 |
| **風險評估** | 需要領域專家 | 諮詢領域專家 |
| **取捨決策** | 缺少歷史脈絡 | 檢視設計文件（如有） |
| **非功能性需求** | 通常是隱含的 | 與架構師討論 |
| **範圍外決策** | 被明確排除的項目 | 檢視原始需求 |

---

## 與開發方法論整合

### 反向工程流水線

```
┌───────────────────────────────────────────────────────────────────────┐
│                    反向工程 → 前向開發                                  │
├───────────────────────────────────────────────────────────────────────┤
│                                                                       │
│   現有                                                                │
│   程式碼 + 測試                                                        │
│       │                                                               │
│       ▼                                                               │
│   ┌─────────────────────────────────────────────────────────────┐    │
│   │ 反向工程（本標準）                                            │    │
│   │   • 程式碼掃描 → 技術清單                                     │    │
│   │   • 測試分析 → 驗收條件                                       │    │
│   │   • 缺口識別 → [未知] 清單                                    │    │
│   └─────────────────────────────────────────────────────────────┘    │
│       │                                                               │
│       ▼                                                               │
│   ┌─────────────────────────────────────────────────────────────┐    │
│   │ SDD（規格驅動開發）                                           │    │
│   │   • 反向工程規格 = 提案草稿                                   │    │
│   │   • 填寫 [未知] 區塊 → 完整提案                               │    │
│   │   • 正式審查 → 已核准規格                                     │    │
│   └─────────────────────────────────────────────────────────────┘    │
│       │                                                               │
│       ▼                                                               │
│   ┌─────────────────────────────────────────────────────────────┐    │
│   │ BDD（行為驅動開發）                                           │    │
│   │   • 驗收條件 → Gherkin 情境                                   │    │
│   │   • 利害關係人驗證                                            │    │
│   └─────────────────────────────────────────────────────────────┘    │
│       │                                                               │
│       ▼                                                               │
│   ┌─────────────────────────────────────────────────────────────┐    │
│   │ TDD（測試驅動開發）                                           │    │
│   │   • Gherkin → 單元測試需求                                    │    │
│   │   • 缺口分析 → 缺少的測試覆蓋                                 │    │
│   └─────────────────────────────────────────────────────────────┘    │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘
```

### SDD 整合

反向工程的規格直接進入 SDD 工作流程：

1. **產出 = SDD 提案草稿**：生成的規格成為提案
2. **需要人類審查**：所有 `[未知]` 區塊必須由人類填寫
3. **正式核准**：規格必須經過標準 SDD 審查流程
4. **狀態追蹤**：在規格元資料中標記為「反向工程」

### BDD 整合

將驗收條件轉換為 Gherkin 格式：

```markdown
## 驗收條件（來自反向工程）
[已確認] 使用者可將商品加入空購物車
[已確認] 重複商品會增加數量
[推論] 最大數量限制：99 件
```

轉換為：

```gherkin
Feature: 購物車
  # 來源：反向工程自 src/cart/

  Scenario: 將商品加入空購物車
    Given 一個空的購物車
    When 使用者將「小工具」加入購物車
    Then 購物車應包含 1 個「小工具」

  Scenario: 加入重複商品
    Given 購物車中有 1 個「小工具」
    When 使用者再加入一個「小工具」
    Then 購物車應包含 2 個「小工具」

  @needs-confirmation
  Scenario: 最大數量限制
    Given 購物車中有 99 個「小工具」
    When 使用者嘗試再加入一個「小工具」
    Then 應拒絕加入
    # [推論] - 需與利害關係人確認
```

### TDD 整合

使用反向工程的規格來識別測試覆蓋缺口：

1. **映射現有測試**：將測試連結到驗收條件
2. **識別缺口**：找出沒有對應測試的條件
3. **排定優先序**：聚焦於高風險的未測試行為
4. **撰寫測試**：使用 TDD 工作流程補充測試覆蓋

---

## 反向工程規格範本

```markdown
# [SPEC-XXX] [功能名稱] - 反向工程

## 元資料
- **狀態**: 草稿（反向工程）
- **來源**: [目錄或檔案路徑]
- **生成日期**: [日期]
- **審查者**: [待定]

## 摘要
[簡述 - [推論] 或 [已確認]]

## 動機
[未知] - 需要人類輸入
- 為何最初要建立此功能？
- 解決什麼問題？

## 技術設計

### API 端點
[已確認] 來自程式碼分析：
- `POST /api/resource` - [來源: 程式碼] src/routes/resource.ts:15
- `GET /api/resource/:id` - [來源: 程式碼] src/routes/resource.ts:25

### 資料模型
[已確認] 來自型別定義：
- `Resource` 介面 - [來源: 程式碼] src/types/resource.ts:5-20

### 相依性
[已確認] 來自匯入分析：
- 資料庫：PostgreSQL (knex client)
- 快取：Redis

## 驗收條件
[已確認] 來自測試分析 (src/tests/resource.test.ts)：
- [ ] 以有效資料建立資源 (第 10 行)
- [ ] 無效輸入回傳 400 (第 25 行)
- [ ] 不存在的資源回傳 404 (第 40 行)

[未知] 測試未涵蓋：
- [ ] [需確認] 速率限制行為
- [ ] [需確認] 快取失效策略

## 風險
[未知] - 需要領域專家

## 範圍外
[未知] - 需要歷史脈絡

## 來源引用
| 項目 | 檔案 | 行號 | 確定性 |
|------|------|------|--------|
| POST /api/resource | src/routes/resource.ts | 15 | [已確認] |
| Resource 介面 | src/types/resource.ts | 5-20 | [已確認] |
| 400 無效輸入 | src/tests/resource.test.ts | 25 | [已確認] |
```

---

## 應避免的反模式

### 程式碼分析反模式

| 反模式 | 影響 | 正確做法 |
|--------|------|---------|
| **捏造動機** | 誤導性規格 | 標記為 `[未知]` |
| **假設需求** | 虛假信心 | 標記為 `[需確認]` |
| **推測未讀程式碼** | 幻覺 | 只分析已讀取的內容 |
| **將推論呈現為事實** | 破壞信任 | 始終使用適當標籤 |
| **跳過人類審查** | 不完整規格 | 始終要求審查階段 |

### 流程反模式

| 反模式 | 影響 | 正確做法 |
|--------|------|---------|
| **為未讀程式碼生成** | 無效產出 | 先讀取所有相關檔案 |
| **無人類輸入填寫 [未知]** | 無效規格 | 始終取得人類輸入 |
| **跳過測試分析** | 遺漏條件 | 始終分析現有測試 |
| **單次生成** | 淺薄規格 | 使用漸進式揭露 |

---

## 最佳實踐

### 應該做的

- ✅ 在做出任何聲明前讀取所有相關檔案
- ✅ 為每項陳述標註確定性層級
- ✅ 包含來源引用與 file:line 參考
- ✅ 明確列出需要人類輸入的項目
- ✅ 保留原始程式碼註解作為脈絡
- ✅ 將測試映射到驗收條件
- ✅ 使用漸進式揭露（概覽 → 細節）
- ✅ 與利害關係人驗證推論

### 不應該做的

- ❌ 假設動機或商業背景
- ❌ 將推論呈現為已確認事實
- ❌ 跳過來源歸屬
- ❌ 為未讀程式碼生成規格
- ❌ 無人類輸入填寫 `[未知]` 區塊
- ❌ 忽略現有測試
- ❌ 跳過人類審查階段
- ❌ 過度工程化規格

---

## 工具整合

### 命令列工具

| 工具 | 命令 | 用途 |
|------|------|------|
| **Claude Code** | `/reverse-spec` | 從程式碼生成 SDD 規格 |
| **Claude Code** | `/reverse-bdd` | 將 AC 轉換為 Gherkin 情境 |
| **Claude Code** | `/reverse-tdd` | 分析 BDD 的測試覆蓋 |

### 技能參考

- [反向工程技能](../../../skills/reverse-engineer/SKILL.md) - 詳細工作流程實作
- [規格驅動開發技能](../../../skills/spec-driven-dev/SKILL.md) - SDD 整合
- [BDD 助手技能](../../../skills/bdd-assistant/SKILL.md) - Gherkin 撰寫
- [TDD 助手技能](../../../skills/tdd-assistant/SKILL.md) - 測試覆蓋分析

---

## 相關標準

- [反幻覺指南](anti-hallucination.md) - 基於證據的分析要求
- [規格驅動開發](spec-driven-development.md) - 規格工作流程
- [行為驅動開發](../../../core/behavior-driven-development.md) - Given-When-Then 情境
- [測試驅動開發](test-driven-development.md) - 紅-綠-重構循環
- [驗收測試驅動開發](../../../core/acceptance-test-driven-development.md) - 驗收條件
- [程式碼審查清單](code-review-checklist.md) - 審查指南

---

## 版本歷史

| 版本 | 日期 | 變更內容 |
|------|------|----------|
| 1.0.0 | 2026-01-19 | 初始發布 |

---

## 參考資料

- [反幻覺標準](anti-hallucination.md) - 核心合規要求
- [IEEE 830-1998 - 軟體需求規格](https://standards.ieee.org/ieee/830/1222/)
- [SWEBOK v4.0 - 第 9 章：軟體維護](https://www.computer.org/education/bodies-of-knowledge/software-engineering)
- [與舊有程式碼有效協作 - Michael Feathers](https://www.oreilly.com/library/view/working-effectively-with/0131177052/)

---

## 授權

本標準以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。
