reverse-document

逆向文档化

本技能分析现有实现（代码、原型、系统）并生成相应的设计或架构文档。适用于以下场景：

• 你在没有先写设计文档的情况下构建了一个功能
• 你接手了一个没有文档的代码库
• 你原型化了一个机制并需要将其规范化
• 你需要记录现有代码背后的 "为什么"

---

工作流

1. 解析参数

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

类型选项：

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

路径：要分析的目录或文件

• src/gameplay/combat/ -> 所有战斗相关代码
• src/core/event-system.cpp -> 特定文件
• prototypes/stealth-mech/ -> 原型目录

示例：

/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