---
description: |
  将现有代码反向工程成 SDD 规格文档。
  使用时机：分析旧有代码、为未文档化的系统撰写文档、从现有实作提取规格。
  关键字：reverse engineering, legacy code, documentation, spec extraction, code archaeology, 反向工程, 旧有代码, 规格提取。
source: ../../../../skills/reverse-engineer/SKILL.md
source_version: 1.2.0
translation_version: 1.2.0
last_synced: 2026-01-25
status: current
---

# 反向工程成 SDD 规格指南

> **语言**: [English](../../../../skills/reverse-engineer/SKILL.md) | [繁體中文](../../../zh-TW/skills/reverse-engineer/SKILL.md) | 简体中文

**版本**: 1.1.0
**最后更新**: 2026-01-19
**适用范围**: Claude Code Skills

> **核心规范**：此技能实作[反向工程标准](../../../../core/reverse-engineering-standards.md)。任何 AI 工具皆可参考核心规范取得完整方法论文档。

---

## 目的

此技能引导您将现有代码反向工程成 SDD（规格驱动开发）规格文档，并严格遵循反幻觉标准。

## 快速参考

### 反向工程工作流程

```
┌─────────────────────────────────────────────────────────────────┐
│              反向工程工作流程                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1️⃣  代码分析（AI 自动化）                                    │
│      ├─ 扫描代码结构、API、数据模型                           │
│      ├─ 解析现有测试以提取验收标准                              │
│      └─ 生成初稿规格（带不确定性标签）                          │
│                                                                 │
│  2️⃣  人类输入（必要）                                          │
│      ├─ 撰写动机（为什么需要此功能）                            │
│      ├─ 新增风险评估                                            │
│      └─ 验证相依性和商业背景                                    │
│                                                                 │
│  3️⃣  审查与确认                                                 │
│      ├─ 与利害关系人讨论                                        │
│      └─ 确认 [已确认] / [推断] / [未知] 标签                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 可提取与不可提取的内容

| 面向 | 可提取 | 确定性 | 备注 |
|------|--------|--------|------|
| **API 端点** | ✅ 是 | [已确认] | 路由定义、HTTP 方法 |
| **数据模型** | ✅ 是 | [已确认] | 类型、接口、结构描述 |
| **函数签名** | ✅ 是 | [已确认] | 参数、回传类型 |
| **测试案例** | ✅ 是 | [已确认] | → 验收标准 |
| **相依性** | ✅ 是 | [已确认] | 套件引用 |
| **行为模式** | ⚠️ 部分 | [推断] | 从代码分析推断 |
| **动机/为什么** | ❌ 否 | [未知] | 需要人类输入 |
| **商业背景** | ❌ 否 | [未知] | 需要人类输入 |
| **风险评估** | ❌ 否 | [未知] | 需要领域专业知识 |
| **权衡决策** | ❌ 否 | [未知] | 缺少历史背景 |

## 核心原则

### 1. 反幻觉合规

**关键**：此技能必须严格遵循[反幻觉标准](../../../../core/anti-hallucination.md)。

#### 确定性标签

| 标签 | 使用时机 | 范例 |
|------|----------|------|
| `[已确认]` | 来自代码/测试的直接证据 | `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. 渐进式揭露

从高层级架构开始，然后深入：

1. **系统概览**：进入点、主要组件
2. **组件详情**：个别模块及其职责
3. **实作细节**：算法、数据流程

### 3. 测试对应需求

从测试提取验收标准：

```javascript
// 测试文件：src/tests/auth.test.ts
describe('认证', () => {
  it('应该对无效凭证回传 401', () => {...});
  it('应该在登入成功时发放 JWT 令牌', () => {...});
  it('应该在过期前更新令牌', () => {...});
});
```

转换为：

```markdown
## 验收标准
[推断] 从测试分析（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](../../../../templates/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 件时会发生什么？（拒绝或限制？）
```

## 与其他技能的整合

### 与 /sdd（规格驱动开发）

1. 使用 `/reverse-sdd` 生成反向工程规格
2. 审查并填写 `[未知]` 区块
3. 使用 `/sdd review` 验证完整性
4. 继续正常 SDD 工作流程进行增强

### 与 /tdd（测试驱动开发）

1. 提取现有测试模式
2. 识别测试覆盖率缺口
3. 使用 `/tdd` 新增缺失的测试
4. 用新的验收标准更新规格

### 与 /bdd（行为驱动开发）

1. 将提取的验收标准转换为 Gherkin 格式
2. 使用 `/bdd` 正式化场景
3. 与利害关系人验证场景

## 完整反向工程管道

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

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        完整反向工程管道                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   代码 + 测试                                                          │
│        │                                                                │
│        ▼                                                                │
│   /reverse-sdd                                                         │
│        │                                                                │
│        └─→ 生成 SPEC-XXX 含验收标准                                      │
│                │                                                        │
│                ▼                                                        │
│   /reverse-bdd                                                          │
│        │                                                                │
│        ├─→ AC → Gherkin 场景转换                                         │
│        ├─→ 条列式自动转换为 Given-When-Then                              │
│        └─→ 生成 .feature 文件                                           │
│                │                                                        │
│                ▼                                                        │
│   /reverse-tdd                                                          │
│        │                                                                │
│        ├─→ 分析现有单元测试                                              │
│        └─→ 生成覆盖率报告与缺口                                          │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

### 管道命令

| 命令 | 输入 | 输出 | 目的 |
|------|------|------|------|
| `/reverse-sdd` | 代码目录 | SPEC-XXX.md | 从代码提取需求 |
| `/reverse-bdd` | SPEC 文件 | .feature 文件 | 将 AC 转换为 Gherkin 场景 |
| `/reverse-tdd` | .feature 文件 | 覆盖率报告 | 映射场景到单元测试 |

### 使用范例

```bash
# 步骤 1：将代码反向工程成 SDD 规格
/reverse-sdd src/auth/

# 步骤 2：将验收标准转换为 BDD 场景
/reverse-bdd specs/SPEC-AUTH.md

# 步骤 3：分析 BDD 场景的测试覆盖率
/reverse-tdd features/auth.feature
```

### 详细指南

- [BDD 提取工作流程](./bdd-extraction.md) - AC → Gherkin 转换详细指南
- [TDD 分析工作流程](./tdd-analysis.md) - 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 等）

---

## 相关标准

- [规格驱动开发](../../../../core/spec-driven-development.md)
- [反幻觉指南](../../../../core/anti-hallucination.md)
- [代码审查检查清单](../../../../core/code-review-checklist.md)

---

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.1.0 | 2026-01-19 | 新增 BDD/TDD 管道整合 |
| 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)
