---
name: reverse-document
description: "从现有实现生成设计或架构文档。从代码/原型逆向工作，创建缺失的规划文档。"
argument-hint: "<类型> <路径>（例如 'design src/gameplay/combat' 或 'architecture src/core'）"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Edit, Bash
---

# 逆向文档化

本技能分析现有实现（代码、原型、系统）并生成相应的设计或架构文档。适用于以下场景：
- 你在没有先写设计文档的情况下构建了一个功能
- 你接手了一个没有文档的代码库
- 你原型化了一个机制并需要将其规范化
- 你需要记录现有代码背后的 "为什么"

---

## 工作流

### 1. 解析参数

**格式**：`/reverse-document <类型> <路径>`

**类型选项**：
- `design` -> 生成游戏设计文档 (GDD 章节)
- `architecture` -> 生成架构决策记录 (ADR)
- `concept` -> 从原型生成概念文档

**路径**：要分析的目录或文件
- `src/gameplay/combat/` -> 所有战斗相关代码
- `src/core/event-system.cpp` -> 特定文件
- `prototypes/stealth-mech/` -> 原型目录

**示例**：
```bash
/reverse-document design src/gameplay/magic-system
/reverse-document architecture src/core/entity-component
/reverse-document concept prototypes/vehicle-combat
```

### 2. 分析实现

**阅读并理解代码/原型**：

**对于设计文档 (GDD)**：
- 识别机制、规则、公式
- 提取玩法数值（伤害、冷却时间、范围）
- 找到状态机、技能系统、成长系统
- 检测代码中处理的边缘情况
- 映射依赖（哪些系统之间有交互？）

**对于架构文档 (ADR)**：
- 识别模式（ECS、单例、观察者等）
- 理解技术决策（线程、序列化等）
- 映射依赖和耦合关系
- 评估性能特征
- 找到约束和权衡

**对于概念文档（原型分析）**：
- 识别核心机制
- 提取涌现的玩法模式
- 记录什么有效、什么无效
- 发现技术可行性洞见
- 记录玩家幻想 / 手感

### 3. 提出澄清问题（协作协议）

**不要**只是描述代码。**要问**关于意图：

**设计问题**：
- "我看到一个在战斗中消耗的体力系统。这是为了：
  - 节奏控制（防止乱按）？
  - 资源管理（策略深度）？
  - 还是其他原因？"
- "击倒机制似乎很核心。这是一个核心支柱，还是辅助功能？"
- "伤害随等级指数缩放。是有意为之的力量幻想，还是需要重新平衡？"

**架构问题**：
- "你使用了服务定位器模式。这是为了：
  - 可测试性（模拟依赖）？
  - 解耦（减少硬引用）？
  - 还是继承了现有代码？"
- "我看到使用了手动内存管理而非智能指针。是性能需求，还是历史遗留？"

**概念问题**：
- "原型强调潜行而非战斗。这是预期的核心支柱吗？"
- "玩家似乎在利用抓钩加速。这是功能还是 Bug？"

### 4. 展示发现

在起草之前，展示你发现了什么：

```
我已经分析了 src/gameplay/combat/。以下是我的发现：

已实现的机制：
- 3 连击系统，带时机窗口
- 破防机制（重攻击 vs 格挡中的敌人）
- 体力系统（攻击/闪避时消耗，空闲时恢复）
- 击倒系统（累积触发脆弱状态）

发现的公式：
- 伤害 = 基础值 * (1 + 力量缩放 * 等级)
- 击倒累积 = 攻击击倒值 / (敌人.定力 * 0.5)
- 体力消耗 = 基础体力消耗 * (1 - 效率加成)

意图不明确的区域：
1. 体力系统 — 节奏控制还是资源管理？
2. 击倒 — 核心支柱还是辅助功能？
3. 伤害缩放 — 力量幻想还是需要调整？

在起草设计文档之前，能否请您澄清这些要点？
```

等待用户澄清意图后再起草。

### 5. 使用模板起草文档

根据类型，使用相应模板：

| 类型 | 模板 | 输出路径 |
|------|------|---------|
| `design` | `templates/design-doc-from-implementation.md` | `design/gdd/[系统名称].md` |
| `architecture` | `templates/architecture-doc-from-code.md` | `docs/architecture/[决策名称].md` |
| `concept` | `templates/concept-doc-from-prototype.md` | `prototypes/[名称]/CONCEPT.md` 或 `design/concepts/[名称].md` |

**草稿结构**：
- 捕获**存在什么**（机制、模式、实现）
- 记录**为什么存在**（经用户澄清的意图）
- 识别**缺失什么**（未处理的边缘情况、设计中的空白）
- 标记**后续工作**（数值平衡调整、缺失功能）

### 6. 展示草稿并请求批准

**协作协议**：
```
我已经根据你的代码和澄清内容起草了战斗系统设计文档。

[展示关键章节：概述、机制、公式、设计意图]

我添加的内容：
- 根据你的澄清，将体力记录为 "节奏控制机制"
- 添加了代码中未涉及的边缘情况（如果体力在连击中途归零怎么办？）
- 标记了平衡隐患：高等级的指数伤害缩放

标记为不完整的章节：
- "敌人 AI 与击倒的交互"（尚未完全实现）
- "武器多样性和缩放"（目前只实现了剑）

可以将此内容写入 design/gdd/combat-system.md 吗？
```

等待批准。用户可能在写入前要求修改。

### 7. 带元数据写入文档

获得批准后，使用特殊标记写入文件：

```markdown
---
status: reverse-documented
source: src/gameplay/combat/
date: 2026-02-13
verified-by: [用户名称]
---

# 战斗系统设计

> **注意**：本文档是从现有实现逆向工程得出的。
> 它记录了当前行为和经澄清的设计意图。某些部分可能不完整，
> 特别是实现不完整或意图不明确的地方。

[文档其余部分...]
```

### 8. 标记后续工作

写入后，建议下一步操作：

```
已写入 design/gdd/combat-system.md

建议后续工作：
1. 对战斗公式运行 /balance-check（指数缩放隐患）
2. 为体力系统的架构决策创建 ADR
3. 实现缺失的边缘情况：
   - 连击中途体力归零的行为
   - 闪避期间的击倒状态
4. 当实现武器多样性时扩展设计文档

需要我现在处理其中任何一项吗？
```

---

## 模板选择逻辑

| 如果分析... | 使用模板... | 因为... |
|-----------|-----------|--------|
| `src/gameplay/*` | design-doc-from-implementation.md | 玩法机制 -> GDD |
| `src/core/*`、`src/ai/*` | architecture-doc-from-code.md | 核心系统 -> ADR |
| `prototypes/*` | concept-doc-from-prototype.md | 实验 -> 概念文档 |
| `src/networking/*` | architecture-doc-from-code.md | 技术系统 -> ADR |
| `src/ui/*` | design-doc-from-implementation.md | UI/UX -> 设计规范 |

---

## 示例会话：逆向文档化战斗代码

```
用户: /reverse-document design src/gameplay/combat

代理: 我将分析你的战斗实现来创建设计文档。
      [读取代码，发现机制、公式]

代理: 我已经分析了 src/gameplay/combat/。以下是我的发现：
      [展示机制、公式、不明确的区域]

      在起草之前，能否请您澄清：
      1. 体力系统的意图？
      2. 击倒是核心支柱吗？
      3. 伤害缩放 — 有意为之还是需要调整？

用户: 1. 体力是为了节奏控制，防止乱按
      2. 击倒是核心 — 我想要深思熟虑的战斗
      3. 对，指数缩放太过分了，应该是线性的

代理: 明白了，这澄清了愿景。让我起草设计文档。
      [展示含澄清意图的草稿]

      可以将此内容写入 design/gdd/combat-system.md 吗？

用户: 好，写入吧。

代理: 已写入 design/gdd/combat-system.md
      已标记为 [逆向文档化]
      已标记伤害缩放需要重新平衡

      后续步骤：
      - 将伤害公式更新为线性缩放
      - 运行 /balance-check 验证成长曲线
      - 在 game-pillars.md 中将击倒记录为核心支柱
```

---

## 协作协议

本技能遵循协作设计原则：

1. **先分析**：阅读代码，理解实现
2. **询问意图**：问 "为什么"，而不仅仅是 "是什么"
3. **展示发现**：展示发现，高亮不明确的区域
4. **用户澄清**：将意图与偶然结果分开
5. **起草文档**：基于现实 + 意图创建文档
6. **展示草稿**：展示关键章节，解释添加的内容
7. **获取批准**："可以写入 [文件路径] 吗？"
8. **标记后续**：建议相关工作，不要自动执行

**绝不要假设意图。在记录 "为什么" 之前，始终先询问。**