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