反向工程成 SDD 規格指南
語言: English | 繁體中文
版本: 1.1.0 最後更新: 2026-01-19 適用範圍: Claude Code Skills
核心規範：此技能實作反向工程標準。任何 AI 工具皆可參考核心規範取得完整方法論文件。
目的
此技能引導您將現有程式碼反向工程成 SDD（規格驅動開發）規格文件，並嚴格遵循反幻覺標準。
快速參考
反向工程工作流程
code
┌─────────────────────────────────────────────────────────────────┐ │ 反向工程工作流程 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1️⃣ 程式碼分析（AI 自動化） │ │ ├─ 掃描程式碼結構、API、資料模型 │ │ ├─ 解析現有測試以提取驗收標準 │ │ └─ 生成初稿規格（帶不確定性標籤） │ │ │ │ 2️⃣ 人類輸入（必要） │ │ ├─ 撰寫動機（為什麼需要此功能） │ │ ├─ 新增風險評估 │ │ └─ 驗證相依性和商業背景 │ │ │ │ 3️⃣ 審查與確認 │ │ ├─ 與利害關係人討論 │ │ └─ 確認 [已確認] / [推斷] / [未知] 標籤 │ │ │ └─────────────────────────────────────────────────────────────────┘
可提取與不可提取的內容
| 面向 | 可提取 | 確定性 | 備註 |
|---|---|---|---|
| API 端點 | ✅ 是 | [已確認] | 路由定義、HTTP 方法 |
| 資料模型 | ✅ 是 | [已確認] | 類型、介面、結構描述 |
| 函數簽名 | ✅ 是 | [已確認] | 參數、回傳類型 |
| 測試案例 | ✅ 是 | [已確認] | → 驗收標準 |
| 相依性 | ✅ 是 | [已確認] | 套件引用 |
| 行為模式 | ⚠️ 部分 | [推斷] | 從程式碼分析推斷 |
| 動機/為什麼 | ❌ 否 | [未知] | 需要人類輸入 |
| 商業背景 | ❌ 否 | [未知] | 需要人類輸入 |
| 風險評估 | ❌ 否 | [未知] | 需要領域專業知識 |
| 權衡決策 | ❌ 否 | [未知] | 缺少歷史背景 |
核心原則
1. 反幻覺合規
關鍵：此技能必須嚴格遵循反幻覺標準。
確定性標籤
| 標籤 | 使用時機 | 範例 |
|---|---|---|
[已確認] | 來自程式碼/測試的直接證據 | src/api/users.ts:15 的 API 端點 |
[推斷] | 從模式合理推斷 | 「根據建構函數模式，可能使用依賴注入」 |
[未知] | 無法從程式碼判斷 | 動機、商業需求 |
[需確認] | 需要人類驗證 | 設計意圖、邊界案例處理 |
來源標註
每個提取的項目必須包含來源標註：
markdown
## 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. 漸進式揭露
從高層級架構開始，然後深入：
- •系統概覽：進入點、主要元件
- •元件詳情：個別模組及其職責
- •實作細節：演算法、資料流程
3. 測試對應需求
從測試提取驗收標準：
javascript
// 測試檔案：src/tests/auth.test.ts
describe('認證', () => {
it('應該對無效憑證回傳 401', () => {...});
it('應該在登入成功時發放 JWT 權杖', () => {...});
it('應該在過期前更新權杖', () => {...});
});
轉換為：
markdown
## 驗收標準 [推斷] 從測試分析（src/tests/auth.test.ts）： - [ ] 對無效憑證回傳 401 狀態碼 - [ ] 登入成功時發放 JWT 權杖 - [ ] 支援過期前的權杖更新
工作流程階段
階段 1：程式碼掃描
輸入：檔案路徑或目錄 輸出：程式碼結構分析
動作：
- •識別進入點（主函數、API 路由、事件處理器）
- •映射模組相依性
- •提取類型定義和介面
- •列出設定來源
階段 2：測試分析
輸入：測試檔案 輸出：驗收標準候選
動作：
- •解析測試案例名稱
- •提取 Given-When-Then 模式（如為 BDD 風格）
- •識別邊界條件
- •記錄覆蓋率缺口
階段 3：缺口識別
輸入：程式碼 + 測試分析 輸出：需要人類輸入的未知項目清單
必要人類輸入：
- • 動機：為什麼要建立此功能？
- • 使用者故事：誰使用這個功能？用於什麼目的？
- • 風險：可能出什麼問題？
- • 權衡：為什麼選擇這個方法而非其他替代方案？
- • 範圍外：明確排除了什麼？
階段 4：規格生成
輸入：所有分析結果 輸出：初稿規格文件
範本：使用 reverse-spec-template.md
階段 5：人類審查
輸入：初稿規格 輸出：經驗證的規格
審查清單：
- • 所有
[已確認]項目驗證準確 - • 所有
[推斷]項目經過驗證或修正 - • 所有
[未知]項目由人類填寫 - • 來源引用已檢查
- • 商業背景已新增
範例
範例 1：API 端點提取
輸入程式碼（src/controllers/UserController.ts）：
typescript
export class UserController {
@Get('/users/:id')
@Authorize('admin', 'user')
async getUser(@Param('id') id: string): Promise<User> {
return this.userService.findById(id);
}
}
提取的規格：
markdown
## API 端點 ### GET /users/:id [已確認] 依 ID 取得使用者 - [來源: 程式碼] src/controllers/UserController.ts:3-7 **授權**：[已確認] 需要 'admin' 或 'user' 角色 - [來源: 程式碼] 第 4 行的 @Authorize 裝飾器 **參數**： - `id`（路徑，必要）：使用者識別碼 [已確認] **回應**：[已確認] 回傳 User 物件 - [來源: 程式碼] 第 5 行的回傳類型 **錯誤處理**：[未知] 錯誤回應無法從程式碼中明確得知
範例 2：測試轉換為標準
輸入測試（src/tests/cart.test.ts）：
typescript
describe('購物車', () => {
it('應該將商品加入空購物車', () => {...});
it('應該對重複商品增加數量', () => {...});
it('不應超過最大數量 99', () => {...});
it('應該計算含稅總額', () => {...});
});
提取的驗收標準：
markdown
## 驗收標準 [推斷] 從測試分析（src/tests/cart.test.ts）： - [ ] 可將商品加入空購物車（第 2 行） - [ ] 對重複商品增加數量（第 3 行） - [ ] 最大數量限制：99 件（第 4 行） - [ ] 總額計算包含稅金（第 5 行） [未知] 稅金計算規則未在測試中指定 [需確認] 購物車超過 99 件時會發生什麼？（拒絕或限制？）
與其他技能的整合
與 /spec（規格驅動開發）
- •使用
/reverse-spec生成反向工程規格 - •審查並填寫
[未知]區塊 - •使用
/spec review驗證完整性 - •繼續正常 SDD 工作流程進行增強
與 /tdd（測試驅動開發）
- •提取現有測試模式
- •識別測試覆蓋率缺口
- •使用
/tdd新增缺失的測試 - •用新的驗收標準更新規格
與 /bdd（行為驅動開發）
- •將提取的驗收標準轉換為 Gherkin 格式
- •使用
/bdd正式化場景 - •與利害關係人驗證場景
完整反向工程管道
反向工程技能支援完整的 SDD → BDD → TDD 管道：
code
┌─────────────────────────────────────────────────────────────────────────┐ │ 完整反向工程管道 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ 程式碼 + 測試 │ │ │ │ │ ▼ │ │ /reverse-spec │ │ │ │ │ └─→ 生成 SPEC-XXX 含驗收標準 │ │ │ │ │ ▼ │ │ /reverse-bdd │ │ │ │ │ ├─→ AC → Gherkin 場景轉換 │ │ ├─→ 條列式自動轉換為 Given-When-Then │ │ └─→ 生成 .feature 檔案 │ │ │ │ │ ▼ │ │ /reverse-tdd │ │ │ │ │ ├─→ 分析現有單元測試 │ │ └─→ 生成覆蓋率報告與缺口 │ │ │ └─────────────────────────────────────────────────────────────────────────┘
管道命令
| 命令 | 輸入 | 輸出 | 目的 |
|---|---|---|---|
/reverse-spec | 程式碼目錄 | SPEC-XXX.md | 從程式碼提取需求 |
/reverse-bdd | SPEC 檔案 | .feature 檔案 | 將 AC 轉換為 Gherkin 場景 |
/reverse-tdd | .feature 檔案 | 覆蓋率報告 | 映射場景到單元測試 |
使用範例
bash
# 步驟 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 覆蓋率分析詳細指南
應避免的反模式
❌ 不要這樣做
- •
捏造動機
- •錯誤：「此功能是為了改善使用者體驗而建立的」
- •正確：「[未知] 動機需要人類輸入」
- •
假設需求
- •錯誤：「系統需要 SSO 支援」
- •正確：「[需確認] 程式碼中發現 SSO 設定 - 這是需求嗎？」
- •
推測未讀取的程式碼
- •錯誤：「PaymentService 處理 Stripe 整合」
- •正確：「[未知] PaymentService 功能 - 需要讀取 src/services/PaymentService.ts」
- •
呈現選項時沒有不確定性標記
- •錯誤：「程式碼使用 Redis 做快取」
- •正確：「[已確認] Redis 客戶端設定於 src/config/cache.ts:5」
最佳實踐
應該做的
- •✅ 在提出聲明前讀取所有相關檔案
- •✅ 為每個陳述標記確定性等級
- •✅ 包含帶有 file:line 的來源引用
- •✅ 清楚列出需要人類輸入的內容
- •✅ 保留原始程式碼註解作為背景
不應該做的
- •❌ 假設動機或商業背景
- •❌ 將推斷呈現為已確認的事實
- •❌ 跳過來源標註
- •❌ 為未讀取的程式碼生成規格
- •❌ 在沒有人類輸入的情況下填寫
[未知]區塊
設定偵測
此技能會自動偵測專案設定：
- •檢查是否存在
specs/目錄 - •檢查 SDD 工具（OpenSpec、Spec Kit）
- •偵測用於提取驗收標準的測試框架
- •識別程式碼模式（MVC、DDD 等）
相關標準
版本歷史
| 版本 | 日期 | 變更 |
|---|---|---|
| 1.1.0 | 2026-01-19 | 新增 BDD/TDD 管道整合 |
| 1.0.0 | 2026-01-19 | 初始發布 |
授權
此技能採用 CC BY 4.0 授權。