将现有代码反向工程成 SDD 规格文档。 使用时机：分析旧有代码、为未文档化的系统撰写文档、从现有实作提取规格。 关键字：reverse engineering, legacy code, documentation, spec extraction, code archaeology, 反向工程, 旧有代码, 规格提取。
Scanned 2/12/2026
Install via CLI
Skills Directoryopenskills install AsiaOstrich/universal-dev-standards---
name: reverse
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 件时会发生什么？（拒绝或限制？）
```
## 与其他技能的整合
### 与 /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 │
│ │ │
│ ├─→ 分析现有单元测试 │
│ └─→ 生成覆盖率报告与缺口 │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
### 管道命令
| 命令 | 输入 | 输出 | 目的 |
|------|------|------|------|
| `/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 提取工作流程](./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)
No comments yet. Be the first to comment!
