reverse-document

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/ -> 原型目录

示例：

/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. 带元数据写入文档

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

---
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. 标记后续：建议相关工作，不要自动执行

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