reverse-document

逆向文档编写

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

• 实现功能前没有先编写设计文档
• 接手了没有文档的代码库
• 制作了一个机制原型，需要将其正式整理成文档
• 需要记录现有代码背后的“原因”

---

工作流

阶段 1：解析参数

格式：/reverse-document <type> <path>

类型选项：

• design → 生成游戏设计文档（GDD）章节
• architecture → 生成架构决策记录（ADR）
• concept → 根据原型生成概念文档

路径：要分析的目录或文件，必须位于代码根目录下 — src/（Godot）、 Assets/（Unity）、Source/<Module>/（Unreal）（.claude/docs/code-root-resolution.md）

• src/gameplay/combat/ → 所有与战斗相关的代码（Godot）
• Assets/Scripts/Core/EventSystem.cs → 特定文件（Unity）
• Source/MyGame/Private/AI/ → 模块文件夹（Unreal）
• prototypes/stealth-mech/ → 原型目录

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys workflow,system_overrides,automation

自动化模式：解析 modes.automation（project.local.yaml → project.yaml → 默认值 collaborative）。每次 AskUserQuestion 调用和 每次文件写入都遵循 .claude/docs/automation-modes.md （collaborative 始终询问 · guided 仅对重大操作询问 · autonomous 记录日志并继续； automation_always_ask 类别始终提示）。

已在上方解析 — 按原样使用。如果没有内容块 → 使用 .claude/docs/config-resolution.md 中的默认值。

解析目标系统的工作流级别：将 <path> 映射到系统名称，然后使用该系统在上方内容块中列出的 system_overrides 行；否则使用项目的 workflow 值。它决定生成的文档详略程度 — 参见阶段 5。各级别的具体含义见 .claude/docs/workflow-modes.md。

解析级别 — 不要自行假设。 workflow-modes.md 定义了各级别的含义， 但无法说明本项目设置了哪个级别；请从上方内容块中获取。这里的影响很大 — 在 full 模式下，这项技能会编写包含 8 个章节的 GDD；在 minimal 模式下则会生成一页简报，因此选错级别会导致产物完全不符。

示例：

/reverse-document design src/gameplay/magic-system
/reverse-document architecture Source/MyGame/Private/EntityComponent
/reverse-document concept prototypes/vehicle-combat

阶段 2：分析实现

阅读并理解代码／原型：

对于设计文档（GDD）：

• 识别机制、规则和公式
• 提取游戏数值（伤害、冷却时间、范围）
• 查找状态机、能力系统和进度系统
• 检测代码中处理的边缘情况
• 梳理依赖关系（哪些系统会相互作用？）

对于架构文档（ADR）：

• 识别模式（ECS、单例、观察者等）
• 理解技术决策（线程处理、序列化等）
• 梳理依赖关系和耦合情况
• 评估性能特征
• 找出限制和权衡

对于概念文档（原型分析）：

• 识别核心机制
• 提取涌现式游戏玩法模式
• 记录哪些设计有效、哪些无效
• 找出技术可行性方面的见解
• 记录玩家幻想／体验感受

阶段 3：提出澄清问题

不要只是描述代码。要询问意图：

设计问题：

• “我看到一个[资源]系统会在[活动]期间逐渐耗尽。这是为了：
  • 控制节奏（防止刷屏）？
  • 管理资源（增加策略深度）？
  • 还是另有原因？”
• “[机制]似乎是核心内容。它是核心支柱，还是辅助功能？”
• “[数值]会随[因素]呈指数级增长。这是有意的设计，还是需要重新平衡？”

架构问题：

• “你使用了服务定位器模式。选择它是为了：
  • 可测试性（模拟依赖）？
  • 解耦（减少硬引用）？
  • 还是沿用了现有代码？”
• “我看到你使用手动内存管理，而不是智能指针。这是出于性能要求，还是历史遗留？”

概念问题：

• “原型强调潜行而非战斗。这是预期的核心支柱吗？”
• “玩家似乎会利用抓钩来提速。这是功能还是 Bug？”

阶段 3b：充分性检查——这里有足够的内容可供编写文档吗？

在阶段 4 之前运行此检查；如果未通过，请在此处停止。 此技能根据实现推断设计，因此当实现过于简单时，就无从推断——而下面的模板会欣然接受杜撰的内容，因为其中每个部分都是必填项。

统计阶段 2 实际发现的内容：

信号	计入标准
机制	有名称且规则可观察的行为——不是存根，也不是空类
公式	根据输入计算游戏数值的表达式
数值	有使用位置的调优常量

如果三项的计数全为零，或者目标路径中少于约 20 行非样板代码，请停止并说明：

“[path] 中没有足够的实现内容可用于逆向编写文档。 发现：[N] 个机制、[N] 个公式、[N] 个调优数值。 逆向文档是根据行为推断设计；没有行为可供参考，我产出的任何内容都只会是披着设计文档外衣的杜撰。 如果设计只存在于你的脑海中，/design-system [name] 才是用来记录它的技能——它会通过提问来了解设计，而不是进行推断。”

不要通过补齐其余内容来应付不完整的统计结果。 如果某个路径中有两个机制但没有公式，就编写一份包含这两个机制，并明确写上 FORMULAS DISCOVERED: none found in the source 的文档——参见阶段 4。

阶段 4：展示发现结果

起草之前，先展示你发现的内容：

I've analyzed [path]/. Here's what I found:

MECHANICS IMPLEMENTED:
- [mechanic-a] with [property] (e.g. timing windows, cooldowns)
- [mechanic-b] (e.g. interaction between two states)
- [resource] system (depletes on [action], regens on [condition])
- [state] system (builds up, triggers [effect])

FORMULAS DISCOVERED:
- [Output] = [formula using discovered variables]
- [Secondary output] = [formula]

UNCLEAR INTENT AREAS:
1. [Resource] system — pacing or resource management?
2. [Mechanic] — core pillar or supporting feature?
3. [Value] scaling — intentional design or needs tuning?

Before I draft the design doc, could you clarify these points?

上面的每个部分都可以为空；如果为空，必须明确说明。 在标题下写上 none found in the source——绝不能省略标题（省略会让人以为“没有查找”），也绝不能根据此类系统通常包含的内容来填充。方括号中的行只是示例形式，不是配额：源中只有一个机制，就只写一行，而不是四行。

这比报告更需要注意，因为此技能的输出不是报告，而是设计文档；/design-review、/create-epics 和 /create-stories 会将其视为已确定的设计意图。GDD 中杜撰的公式不会止步于文档错误；它会变成需求，接着变成故事，最后变成满足该公式的代码。

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

如果用户没有回答 UNCLEAR INTENT AREAS 中的问题，不要照样起草已消除歧义的版本。 这些问题之所以存在，是因为代码无法告诉你原因——代码记录的是已构建的内容，而不是预期内容；两者之间的差距正是设计文档的全部内容。未回答的问题必须原样保留为文档中的待解决问题，并标记为 INTENT UNKNOWN — inferred from implementation, not confirmed。将推断出的意图写成已确认的意图，正是此技能要避免的根本问题。

阶段 5：使用模板起草文档

根据类型使用相应模板：

类型	模板	输出路径
design	templates/design-doc-from-implementation.md	design/gdd/[system-name].md
architecture	templates/architecture-doc-from-code.md	docs/architecture/[decision-name].md
concept	templates/concept-doc-from-prototype.md	prototypes/[name]/CONCEPT.md 或 design/concepts/[name].md

design 输出的规模取决于工作流层级（在阶段 1 中确定）：

• full — 生成一份包含 8 个章节的完整 GDD。
• standard — 生成一份包含 5 个章节的 GDD（概览、详细设计、边界情况、依赖项、验收标准；如果还原出的系统定义了数值规则，则加上公式）。跳过玩家幻想和调优参数。
• minimal — 按单页格式生成一份游戏简报（.claude/docs/templates/game-brief.md），而非 GDD。对于整个游戏（路径本身就是代码根目录），写入 design/game-brief.md；对于单个逆向工程系统，写入 design/[system-name]-brief.md。

（architecture 和 concept 输出不受层级影响。）

起草结构：

• 记录现有内容（机制、模式、实现）
• 记录存在原因（与用户澄清后的意图）
• 指出缺失内容（未处理的边界情况、设计缺口）
• 标记后续工作（平衡性调整、缺失功能）

标注来源 — 必须置于此技能撰写的每份文档顶部

此处生成的文档与设计师手工撰写的文档格式相同、路径相同，且所有下游使用者都会一视同仁地处理这两种文档。/design-review 会检查文档是否完整，/create-epics 会据此提取史诗任务，/create-stories 会将其中的内容转化为验收标准。没有任何地方会询问文档的来源。

这一区别并非表面功夫：设计师撰写的 GDD 陈述的是意图，而此处生成的文档陈述的是观察到的行为及推断。两者不一致时，前者需要修改代码，后者需要修改文档——读者无法分辨自己看到的是哪一种，除非文档明确说明。

请在标题下方立即添加以下内容：

> **Reverse-documented from implementation** — generated by `/reverse-document`
> from `[path]` on `[date]`, at commit `[short-sha]`.
> This records what the code **does**; intent marked `INTENT UNKNOWN` below was
> inferred, not confirmed by the author. Where this document and the code
> disagree, do not assume the document is the requirement.

修订时保留此标记。如果之后有人工确认了意图并将文档采纳为正式设计，移除此标记应由其明确执行，而不是下一次编辑时的副作用。

阶段 6：展示草稿并请求批准

协作协议：

I've drafted the [system-name] design doc based on your code and clarifications.

[Show key sections: Overview, Mechanics, Formulas, Design Intent]

ADDITIONS I MADE:
- Documented [mechanic] as "[intent]" per your clarification
- Added edge cases not in code (e.g., what if [resource] hits 0 mid-[action]?)
- Flagged balance concern: [scaling type] scaling at [boundary condition]

SECTIONS MARKED AS INCOMPLETE:
- "[System] interaction with [other-system]" (not fully implemented yet)
- "[Variant or feature]" (only [subset] implemented so far)

May I write this to [output path]?

在提示中使用符合层级的输出路径：design/gdd/[system-name].md 用于 full/standard GDD，或 design/[system-name]-brief.md 用于 minimal 简报。

处于 collaborative 模式时——等待批准；用户可以在写入前要求修改。处于 guided 模式时——这是一个新文件，因此 automation-modes.md:81 中的规则仍然适用（仅对新文件询问“可以写入吗？”）；如果目标文件已存在，则展示差异并继续，无需等待明确的“是”。处于 autonomous 模式时——写入文件并记录决策。

阶段 7：写入带有元数据的文档

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

---
status: reverse-documented
source: [path/]
date: [today]
verified-by: [User name]
---

# [System Name] Design

> **Note**: This document was reverse-engineered from the existing implementation.
> It captures current behavior and clarified design intent. Some sections may be
> incomplete where implementation is partial or intent was unclear.

[Rest of document...]

阶段 8：标记后续工作

写入后，建议后续步骤：

✅ Written to design/gdd/combat-system.md

FOLLOW-UP RECOMMENDED:
1. Run /balance-check on combat formulas (exponential scaling concern)
2. Create ADR for stamina system architecture decision
3. Implement missing edge cases:
   - Stamina depletion mid-combo behavior
   - Stagger state during dodge
4. Extend design doc when weapon variety is implemented

Would you like me to tackle any of these now?

---

模板选择逻辑

分析对象	使用模板	原因
<code root>/gameplay/*	design-doc-from-implementation.md	游戏玩法机制 → GDD
<code root>/core/*、<code root>/ai/*	architecture-doc-from-code.md	核心系统 → ADR
prototypes/*	concept-doc-from-prototype.md	实验 → 概念文档
<code root>/networking/*	architecture-doc-from-code.md	技术系统 → ADR
<code root>/ui/*	design-doc-from-implementation.md	UI/UX → 设计规范

---

示例会话：为系统补写文档

User: /reverse-document design <code root>/gameplay/[system]

Agent: I'll analyze your [system] implementation to create a design doc.
       [Reads code, discovers mechanics, formulas]

Agent: I've analyzed <code root>/gameplay/[system]/. Here's what I found:
       [Shows mechanics, formulas, unclear areas]

       Before drafting, could you clarify:
       1. [Resource] system intent?
       2. Is [mechanic] a core pillar?
       3. [Value] scaling — intentional or needs tuning?

User: 1. [Resource] is for pacing, prevent [unwanted behavior]
      2. [Mechanic] is core — I want [design intent]
      3. Yeah, exponential is too much, should be linear

Agent: Perfect, that clarifies the vision. Let me draft the design doc.
       [Shows draft with clarified intent]

       May I write this to design/gdd/[system-name].md?

User: Yes, write it.

Agent: ✅ Written to design/gdd/[system-name].md
       ✅ Marked as [REVERSE-DOCUMENTED]
       ✅ Flagged [value] scaling for rebalancing

       Next steps:
       - Update [formula] to [corrected scaling]
       - Run /balance-check to validate [curve]
       - Document [mechanic] as core pillar in game-pillars.md

---

协作协议

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

1. 先分析：阅读代码，了解实现方式
2. 询问意图：询问“为什么”，而不只是“是什么”
3. 展示发现：展示发现，并指出不明确之处
4. 用户澄清：区分意图与意外情况
5. 起草文档：根据实际情况和意图创建文档
6. 展示草稿：展示关键部分，并说明新增内容
7. 征求批准：“我可以写入 [filepath] 吗？”获批后：结论：COMPLETE — 文档已生成。遭拒后：结论：BLOCKED — 用户拒绝写入。
8. 标记后续工作：建议相关工作，不要自动执行

绝不臆测意图。记录“为什么”之前，务必先询问。