---
source: ../../../../skills/reverse-engineer/workflow.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](../../../../skills/reverse-engineer/workflow.md) | [繁體中文](../../../zh-TW/skills/reverse-engineer/workflow.md) | 简体中文

本指南提供将代码反向工程成 SDD 规格的详细工作流程。

---

## 概览

反向工程将现有实作转换为结构化的规格文档。与正向工程（规格 → 代码）不同，反向工程从代码中提取知识，同时承认这种方法的固有限制。

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        反向工程管道                                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐        │
│  │  代码   │──▶│   测试    │──▶│   设定    │──▶│   文档    │        │
│  │   分析    │   │   分析    │   │   分析    │   │   分析    │        │
│  └─────┬─────┘   └─────┬─────┘   └─────┬─────┘   └─────┬─────┘        │
│        │               │               │               │               │
│        └───────────────┴───────────────┴───────────────┘               │
│                               │                                         │
│                               ▼                                         │
│                    ┌───────────────────┐                               │
│                    │    初稿规格       │                               │
│                    │    带有标签       │                               │
│                    └─────────┬─────────┘                               │
│                              │                                         │
│                              ▼                                         │
│                    ┌───────────────────┐                               │
│                    │    人类审查       │                               │
│                    │    与完成        │                               │
│                    └─────────┬─────────┘                               │
│                              │                                         │
│                              ▼                                         │
│                    ┌───────────────────┐                               │
│                    │   最终规格        │                               │
│                    │    文档          │                               │
│                    └───────────────────┘                               │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 阶段 1：代码扫描

### 1.1 识别进入点

扫描应用程式进入点：

| 进入点类型 | 常见模式 | 要检查的文件 |
|------------|----------|-------------|
| **API 路由** | Express 路由、FastAPI 端点 | `routes/`、`controllers/`、`api/` |
| **主函数** | `main()`、`__main__`、`index.ts` | 根目录文件、`src/index.*` |
| **事件处理器** | 讯息队列、webhooks | `handlers/`、`events/`、`listeners/` |
| **CLI 命令** | 参数解析器、命令定义 | `commands/`、`cli/`、`bin/` |
| **排程任务** | Cron 任务、背景任务 | `jobs/`、`tasks/`、`workers/` |

### 1.2 映射模块结构

建立相依性图：

```
src/
├── controllers/        # 进入点
│   ├── UserController.ts  → 相依于 → UserService, UserDTO
│   └── AuthController.ts  → 相依于 → AuthService, TokenService
├── services/          # 商业逻辑
│   ├── UserService.ts     → 相依于 → UserRepository
│   └── AuthService.ts     → 相依于 → UserService, TokenService
├── repositories/      # 数据存取
│   └── UserRepository.ts  → 相依于 → Database, User 实体
└── models/            # 数据结构
    └── User.ts            → 无相依性
```

### 1.3 提取类型定义

记录所有数据结构：

```markdown
## 数据模型

### 用户实体
[已确认] 用户数据模型定义于 src/models/User.ts:5-25
- [来源: 代码] src/models/User.ts:5-25

| 栏位 | 类型 | 必要 | 备注 |
|------|------|------|------|
| id | string (UUID) | 是 | 主键 |
| email | string | 是 | 唯一约束 |
| password | string | 是 | 使用 BCrypt 杂凑 |
| createdAt | Date | 是 | 自动生成 |

[推断] 根据栏位名称和验证，密码似乎有做杂凑处理
[需确认] 使用什么杂凑算法？
```

### 1.4 设定发现

识别设定来源：

```markdown
## 设定

### 环境变数
[已确认] 发现于 src/config/env.ts:1-30
- [来源: 代码] src/config/env.ts

| 变数 | 预设值 | 必要 | 用途 |
|------|--------|------|------|
| DATABASE_URL | - | 是 | PostgreSQL 连线 |
| JWT_SECRET | - | 是 | 令牌签名 |
| NODE_ENV | development | 否 | 环境模式 |

### 应用程式设定
[已确认] 发现于 src/config/app.ts:1-20
- [来源: 代码] src/config/app.ts

| 设定 | 值 | 备注 |
|------|-----|------|
| sessionTimeout | 3600 | 1 小时（秒） |
| maxLoginAttempts | 5 | [未知] 达到 5 次后会发生什么？ |
```

---

## 阶段 2：测试分析

### 2.1 解析测试结构

提取测试组织：

```markdown
## 测试覆盖率分析

### 已扫描的测试文件
- src/tests/unit/UserService.test.ts（15 个测试）
- src/tests/unit/AuthService.test.ts（12 个测试）
- src/tests/integration/api.test.ts（8 个测试）
- src/tests/e2e/login.spec.ts（5 个测试）

### 按模块覆盖率
| 模块 | 单元测试 | 整合测试 | E2E |
|------|----------|----------|-----|
| UserService | 15 ✅ | 3 | 2 |
| AuthService | 12 ✅ | 5 | 3 |
| PaymentService | 0 ⚠️ | 0 | 0 |
```

### 2.2 提取验收标准

将测试案例转换为标准：

**从单元测试**：
```typescript
// src/tests/unit/UserService.test.ts
describe('UserService', () => {
  describe('createUser', () => {
    it('应该使用有效电子邮件建立用户', async () => {...});
    it('应该拒绝重复的电子邮件', async () => {...});
    it('应该在储存前杂凑密码', async () => {...});
  });
});
```

**转换为验收标准**：
```markdown
## 验收标准

### 用户建立
[推断] 从测试于 src/tests/unit/UserService.test.ts:5-20

**正常路径**：
- [ ] 使用有效电子邮件地址建立用户
- [ ] 储存到数据库前杂凑密码

**错误处理**：
- [ ] 以适当错误拒绝重复的电子邮件

[未知] 什么构成「有效」的电子邮件？（验证规则不在测试中）
[需确认] 重复电子邮件的错误讯息/代码是什么？
```

### 2.3 识别覆盖率缺口

记录缺失的测试覆盖率：

```markdown
## 测试覆盖率缺口

### 关键缺口（未发现测试）
| 功能 | 风险等级 | 建议 |
|------|----------|------|
| PaymentService | 🔴 高 | 变更前新增测试 |
| AuthController 中的错误处理 | 🟡 中 | 新增边界案例测试 |

### 部分覆盖
| 功能 | 已覆盖 | 缺失 |
|------|--------|------|
| 用户 CRUD | 建立、读取 | 更新、删除 |
| 认证 | 登入 | 登出、更新 |

[未知] 这些是刻意排除还是遗漏？
```

---

## 阶段 3：缺口识别

### 3.1 分类未知项目

建立结构化的缺口清单：

```markdown
## 需要人类输入的资讯缺口

### 类别：商业背景
| 问题 | 影响 | 谁能回答 |
|------|------|---------|
| 为什么为此应用程式实作 OAuth？ | 设计理解 | 产品负责人 |
| 此功能解决什么用户问题？ | 动机区块 | 产品负责人 |
| 目标用户人物志是什么？ | 用户故事 | UX/产品 |

### 类别：技术决策
| 问题 | 影响 | 谁能回答 |
|------|------|---------|
| 为什么密码用 BCrypt 而不是 Argon2？ | 安全性评估 | 原始开发者 |
| 为什么用 PostgreSQL 而不是 MongoDB？ | 架构理解 | 技术主管 |
| 是什么驱动了微服务的决定？ | 设计理由 | 架构师 |

### 类别：风险评估
| 问题 | 影响 | 谁能回答 |
|------|------|---------|
| 支付的故障模式是什么？ | 风险文档 | 领域专家 |
| 数据保留要求？ | 合规 | 法务/合规 |
| 安全威胁模型？ | 安全区块 | 安全团队 |
```

### 3.2 标记信心等级

为每个提取的项目分配信心度：

| 信心度 | 标签 | 所需证据 |
|--------|------|---------|
| 100% | `[已确认]` | 直接代码引用带行号 |
| 70-99% | `[推断]` | 基于模式的推断 + 推理 |
| 30-69% | `[假设]` | 常见做法，需要验证 |
| 0-29% | `[未知]` | 无法从代码判断 |

---

## 阶段 4：规格生成

### 4.1 使用范本

套用 [reverse-spec-template.md](../../../../templates/reverse-spec-template.md)：

```markdown
# [SPEC-XXX] 功能名称（反向工程）

> ⚠️ 此规格由现有代码反向工程而来
> 最后分析日期：YYYY-MM-DD
> 来源：path/to/analyzed/code

## 摘要
[已确认] {从代码分析提取的摘要}
- [来源: 代码] {primary_file}:{lines}

## 动机
[未知] 需要人类输入
- 为什么要建立此功能？
- 它解决什么问题？
- 谁请求了此功能？

## 详细设计
...
```

### 4.2 逐区块指南

| 区块 | 来源 | 确定性 |
|------|------|--------|
| 摘要 | 代码结构 + 进入点 | [已确认] |
| 动机 | 无法从代码提取 | [未知] |
| 详细设计 | 代码 + 架构分析 | [已确认/推断] |
| 验收标准 | 测试文件 | [推断] |
| 相依性 | package.json、imports | [已确认] |
| 风险 | 无法判断 | [未知] |
| 范围外 | 无法判断 | [未知] |

---

## 阶段 5：人类审查

### 5.1 审查清单

```markdown
## 人类审查清单

### 准确性验证
- [ ] 所有 `[已确认]` 项目已对照实际代码验证
- [ ] 来源引用正确（file:line）
- [ ] 没有捏造的 API 或设定

### 推断验证
- [ ] 所有 `[推断]` 项目已审查准确性
- [ ] 不正确的推断已更正或移除
- [ ] 已考虑边界案例

### 缺口完成
- [ ] 动机区块已填写
- [ ] 风险评估已新增
- [ ] 用户故事已记录
- [ ] 权衡决策已记录

### 最终验证
- [ ] 原始开发者已审查（如果可用）
- [ ] 已取得利害关系人签核
- [ ] 所有 `[未知]` 标签已解决或确认
```

### 5.2 利害关系人审查范本

```markdown
## 审查请求

**规格**: [SPEC-XXX] 功能名称
**生成日期**: YYYY-MM-DD
**审查截止日期**: YYYY-MM-DD

### 给利害关系人的问题

1. **给产品负责人**：
   - 记录的行为正确吗？
   - 原始动机是什么？
   - 有未记录的需求吗？

2. **给原始开发者**：
   - 技术推断准确吗？
   - 做了什么权衡？
   - 有已知问题或技术债吗？

3. **给领域专家**：
   - 商业规则完整吗？
   - 应记录什么风险？
   - 存在什么边界案例？
```

---

## 处理旧有代码挑战

### 挑战 1：没有测试

当测试不存在时：

1. 清楚记录缺口
2. 从代码注解推断行为（如果有）
3. 将所有验收标准标记为 `[假设]`
4. 建议将撰写测试作为下一步

### 挑战 2：没有注解

当文档不存在时：

1. 使用有意义的名称作为提示
2. 追踪数据流以理解
3. 将理解标记为 `[推断]`
4. 优先进行人类审查

### 挑战 3：意大利面代码

当结构不清楚时：

1. 专注于输入/输出边界
2. 记录可观察的行为
3. 将内部逻辑标记为 `[未知]`
4. 建议在详细规格前进行重构

### 挑战 4：多个实作

当代码有变体时：

1. 记录发现的所有变体
2. 记录哪个看起来是目前的
3. 标记为 `[需确认]`
4. 询问哪个是标准版本

---

## 质量关卡

在完成反向工程规格之前：

| 关卡 | 要求 | 检查 |
|------|------|------|
| **来源标注** | 每个声明都有 file:line | ✅/❌ |
| **确定性标签** | 每个陈述都有标签 | ✅/❌ |
| **无捏造** | 没有发明的 API/设定 | ✅/❌ |
| **缺口记录** | 所有未知项目已列出 | ✅/❌ |
| **人类审查** | 利害关系人已审查 | ✅/❌ |

---

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | 2026-01-19 | 初始发布 |
