reverse-engineer

反向工程成 SDD 規格指南

語言: English | 繁體中文

版本: 1.1.0 最後更新: 2026-01-19 適用範圍: Claude Code Skills

核心規範：此技能實作反向工程標準。任何 AI 工具皆可參考核心規範取得完整方法論文件。

目的

此技能引導您將現有程式碼反向工程成 SDD（規格驅動開發）規格文件，並嚴格遵循反幻覺標準。

快速參考

反向工程工作流程

┌─────────────────────────────────────────────────────────────────┐
│              反向工程工作流程                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1️⃣  程式碼分析（AI 自動化）                                    │
│      ├─ 掃描程式碼結構、API、資料模型                           │
│      ├─ 解析現有測試以提取驗收標準                              │
│      └─ 生成初稿規格（帶不確定性標籤）                          │
│                                                                 │
│  2️⃣  人類輸入（必要）                                          │
│      ├─ 撰寫動機（為什麼需要此功能）                            │
│      ├─ 新增風險評估                                            │
│      └─ 驗證相依性和商業背景                                    │
│                                                                 │
│  3️⃣  審查與確認                                                 │
│      ├─ 與利害關係人討論                                        │
│      └─ 確認 [已確認] / [推斷] / [未知] 標籤                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

可提取與不可提取的內容

核心原則

1. 反幻覺合規

關鍵：此技能必須嚴格遵循反幻覺標準。

確定性標籤

來源標註

每個提取的項目必須包含來源標註：

## API 設計

### 使用者認證
[已確認] POST /api/auth/login 端點接受電子郵件和密碼
- [來源: 程式碼] src/controllers/AuthController.ts:25-45
- [來源: 程式碼] src/routes/auth.ts:8

### 工作階段管理
[推斷] 根據 JWT 過期設定，工作階段在 24 小時後過期
- [來源: 程式碼] src/config/auth.ts:12 - TOKEN_EXPIRY=86400
- [來源: 知識] 標準 JWT 過期解釋（⚠️ 請驗證意圖）

2. 漸進式揭露

從高層級架構開始，然後深入：

1. 系統概覽：進入點、主要元件
2. 元件詳情：個別模組及其職責
3. 實作細節：演算法、資料流程

3. 測試對應需求

從測試提取驗收標準：

// 測試檔案：src/tests/auth.test.ts
describe('認證', () => {
  it('應該對無效憑證回傳 401', () => {...});
  it('應該在登入成功時發放 JWT 權杖', () => {...});
  it('應該在過期前更新權杖', () => {...});
});

轉換為：

## 驗收標準
[推斷] 從測試分析（src/tests/auth.test.ts）：
- [ ] 對無效憑證回傳 401 狀態碼
- [ ] 登入成功時發放 JWT 權杖
- [ ] 支援過期前的權杖更新

工作流程階段

階段 1：程式碼掃描

輸入：檔案路徑或目錄 輸出：程式碼結構分析

動作：

1. 識別進入點（主函數、API 路由、事件處理器）
2. 映射模組相依性
3. 提取類型定義和介面
4. 列出設定來源

階段 2：測試分析

輸入：測試檔案 輸出：驗收標準候選

動作：

1. 解析測試案例名稱
2. 提取 Given-When-Then 模式（如為 BDD 風格）
3. 識別邊界條件
4. 記錄覆蓋率缺口

階段 3：缺口識別

輸入：程式碼 + 測試分析 輸出：需要人類輸入的未知項目清單

必要人類輸入：

• 動機：為什麼要建立此功能？
• 使用者故事：誰使用這個功能？用於什麼目的？
• 風險：可能出什麼問題？
• 權衡：為什麼選擇這個方法而非其他替代方案？
• 範圍外：明確排除了什麼？

階段 4：規格生成

輸入：所有分析結果 輸出：初稿規格文件

範本：使用 reverse-spec-template.md

階段 5：人類審查

輸入：初稿規格 輸出：經驗證的規格

審查清單：

• 所有 [已確認] 項目驗證準確
• 所有 [推斷] 項目經過驗證或修正
• 所有 [未知] 項目由人類填寫
• 來源引用已檢查
• 商業背景已新增

範例

範例 1：API 端點提取

輸入程式碼（src/controllers/UserController.ts）：

export class UserController {
  @Get('/users/:id')
  @Authorize('admin', 'user')
  async getUser(@Param('id') id: string): Promise<User> {
    return this.userService.findById(id);
  }
}

提取的規格：

## API 端點

### GET /users/:id
[已確認] 依 ID 取得使用者
- [來源: 程式碼] src/controllers/UserController.ts:3-7

**授權**：[已確認] 需要 'admin' 或 'user' 角色
- [來源: 程式碼] 第 4 行的 @Authorize 裝飾器

**參數**：
- `id`（路徑，必要）：使用者識別碼 [已確認]

**回應**：[已確認] 回傳 User 物件
- [來源: 程式碼] 第 5 行的回傳類型

**錯誤處理**：[未知] 錯誤回應無法從程式碼中明確得知

範例 2：測試轉換為標準

輸入測試（src/tests/cart.test.ts）：

describe('購物車', () => {
  it('應該將商品加入空購物車', () => {...});
  it('應該對重複商品增加數量', () => {...});
  it('不應超過最大數量 99', () => {...});
  it('應該計算含稅總額', () => {...});
});

提取的驗收標準：

## 驗收標準

[推斷] 從測試分析（src/tests/cart.test.ts）：
- [ ] 可將商品加入空購物車（第 2 行）
- [ ] 對重複商品增加數量（第 3 行）
- [ ] 最大數量限制：99 件（第 4 行）
- [ ] 總額計算包含稅金（第 5 行）

[未知] 稅金計算規則未在測試中指定
[需確認] 購物車超過 99 件時會發生什麼？（拒絕或限制？）

與其他技能的整合

與 /spec（規格驅動開發）

1. 使用 /reverse-spec 生成反向工程規格
2. 審查並填寫 [未知] 區塊
3. 使用 /spec review 驗證完整性
4. 繼續正常 SDD 工作流程進行增強

與 /tdd（測試驅動開發）

1. 提取現有測試模式
2. 識別測試覆蓋率缺口
3. 使用 /tdd 新增缺失的測試
4. 用新的驗收標準更新規格

與 /bdd（行為驅動開發）

1. 將提取的驗收標準轉換為 Gherkin 格式
2. 使用 /bdd 正式化場景
3. 與利害關係人驗證場景

完整反向工程管道

反向工程技能支援完整的 SDD → BDD → TDD 管道：

┌─────────────────────────────────────────────────────────────────────────┐
│                        完整反向工程管道                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   程式碼 + 測試                                                          │
│        │                                                                │
│        ▼                                                                │
│   /reverse-spec                                                         │
│        │                                                                │
│        └─→ 生成 SPEC-XXX 含驗收標準                                      │
│                │                                                        │
│                ▼                                                        │
│   /reverse-bdd                                                          │
│        │                                                                │
│        ├─→ AC → Gherkin 場景轉換                                         │
│        ├─→ 條列式自動轉換為 Given-When-Then                              │
│        └─→ 生成 .feature 檔案                                           │
│                │                                                        │
│                ▼                                                        │
│   /reverse-tdd                                                          │
│        │                                                                │
│        ├─→ 分析現有單元測試                                              │
│        └─→ 生成覆蓋率報告與缺口                                          │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

管道命令

使用範例

# 步驟 1：將程式碼反向工程成 SDD 規格
/reverse-spec src/auth/

# 步驟 2：將驗收標準轉換為 BDD 場景
/reverse-bdd specs/SPEC-AUTH.md

# 步驟 3：分析 BDD 場景的測試覆蓋率
/reverse-tdd features/auth.feature

詳細指南

• BDD 提取工作流程 - AC → Gherkin 轉換詳細指南
• TDD 分析工作流程 - BDD → TDD 覆蓋率分析詳細指南

應避免的反模式

❌ 不要這樣做

1. 捏造動機

   • 錯誤：「此功能是為了改善使用者體驗而建立的」
   • 正確：「[未知] 動機需要人類輸入」

2. 假設需求

   • 錯誤：「系統需要 SSO 支援」
   • 正確：「[需確認] 程式碼中發現 SSO 設定 - 這是需求嗎？」

3. 推測未讀取的程式碼

   • 錯誤：「PaymentService 處理 Stripe 整合」
   • 正確：「[未知] PaymentService 功能 - 需要讀取 src/services/PaymentService.ts」

4. 呈現選項時沒有不確定性標記

   • 錯誤：「程式碼使用 Redis 做快取」
   • 正確：「[已確認] Redis 客戶端設定於 src/config/cache.ts:5」

最佳實踐

應該做的

• ✅ 在提出聲明前讀取所有相關檔案
• ✅ 為每個陳述標記確定性等級
• ✅ 包含帶有 file:line 的來源引用
• ✅ 清楚列出需要人類輸入的內容
• ✅ 保留原始程式碼註解作為背景

不應該做的

• ❌ 假設動機或商業背景
• ❌ 將推斷呈現為已確認的事實
• ❌ 跳過來源標註
• ❌ 為未讀取的程式碼生成規格
• ❌ 在沒有人類輸入的情況下填寫 [未知] 區塊

設定偵測

此技能會自動偵測專案設定：

1. 檢查是否存在 specs/ 目錄
2. 檢查 SDD 工具（OpenSpec、Spec Kit）
3. 偵測用於提取驗收標準的測試框架
4. 識別程式碼模式（MVC、DDD 等）

相關標準

• 規格驅動開發
• 反幻覺指南
• 程式碼審查檢查清單

版本歷史

授權

此技能採用 CC BY 4.0 授權。

來源: universal-dev-standards