反向工程成 SDD 规格指南
版本: 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 授权。