game-reverse-document

AlterLab GameForge -- 逆引きドキュメント作成ワークフロー

多くのゲームプロジェクトは、書類作業ではなく情熱から始まります。開発者はプロトタイプを作り、試行錯誤を重ね、開発を進めます。数週間後、コードベースは動いているものの、元の作者を含め、誰もすべてのファイルを読まずにアーキテクチャを説明できません。設計がコードから生まれたため、設計ドキュメントはありません。その場で決めたことが記録されないままになっているため、アーキテクチャ決定記録もありません。これはインディー開発ではよくある状態であり、そうでないふりをするのは不誠実です。

このワークフローでは、従来のドキュメント作成の流れを逆転させます。ドキュメントを作成してから開発するのではなく、既存のコードを読み、最初からあるべきだったドキュメントを作成します。出力するのは自動生成された API ドキュメントではなく、コードの言葉ではなくゲーム開発の言葉で、意図、アーキテクチャ、ゲームシステムを記録した、人が読みやすい設計ドキュメントです。

逆引きドキュメント作成は、3 つの重要なニーズに応えます。オンボーディング（新しいチームメンバーが、何週間もコードを読み解くことなく数時間でプロジェクトを理解できます）、知識の保存（元の開発者が理由を忘れてしまう前に、その判断を記録できます）、診断（システム同士を並べてドキュメント化すると、不整合が見えるようになります）。

目的と実施のきっかけ

次のような場合に、このワークフローを使用してください：

• プロトタイプは動くものの、ドキュメントがまったくない
• 新しいチームメンバーが既存のコードベースを理解する必要がある
• 元の開発者が離れるため、知識を引き継ぐ必要がある
• プロジェクトが複雑になり、作者がシステムを把握しきれなくなっている
• 誰かが「これをドキュメント化して」または「このコードは何をするの？」と言った
• ゲームジャムのプロトタイプを本格的なプロジェクトへ発展させるため、正式なドキュメントが必要になった
• 既存のプロジェクトで、パブリッシャーや投資家への説明、またはチーム内の認識合わせのために設計ドキュメントが必要になった

このワークフローで解決できる問題：

• 動作しているのに、誰も説明も安全な変更もできないコード
• ドキュメントを読むのではなくコードを読むため、オンボーディングに数週間かかる
• アーキテクチャ上の判断がコードに埋め込まれたまま記録されず、見えない
• コードには存在するものの、設計ドキュメントに記載されていないゲームメカニクス
• 誰も相互作用を整理していないため、互いに矛盾するシステム
• 何もしていないのに、自信を持って削除できる人がいない孤立したコード

重要なルール

1. 書く前に読む。 推測に基づいてドキュメントを作成しないでください。まず実際のコードベースを調べてください。出力するすべての記述は、具体的なファイルまたはコードパターンを根拠として示してください。ファイルパスと行番号を記載してください。

2. 実装より意図を重視する。 コードが何をするかだけでなく、なぜそうするのかを説明してください。重力を加える関数は、単に「下向きの力を加える」のではなく、「無限にジャンプできないように移動の制約を適用する」と説明します。Celeste のコードベースには、「コヨーテタイム：足場から離れた後も、プレイヤーは6フレームのあいだジャンプできる」のように、意図を記したコメントが数多くあります。このレベルの意図を説明するドキュメントを目指してください。

3. 不確かな点を明示する。 コードの意図が曖昧な場合は、その旨を記載してください。該当箇所に [UNVERIFIED] を付け、開発者に確認を求めてください。推測した意図を事実として記載するより、情報が欠けているままにするほうが適切です。

4. ファイルではなくシステムを軸にする。 ファイル構成ではなく、ゲームシステム（移動、戦闘、インベントリ、UI）に沿ってドキュメントを構成してください。移動システムは、3つのディレクトリにまたがる5つのファイルで構成される場合があります。ドキュメントでは、システムを説明してから関連ファイルを列挙します。Dead Cells の内部ドキュメントは、ゲームのファイルツリーではなく、デザイナーの考え方に沿って、戦闘、バイオーム、進行、敵などのゲームシステムごとに構成されていました。

5. 矛盾を見つけて指摘する。 移動コードがタイルベースの移動を前提としている一方で、衝突コードが連続的な移動を前提としている場合、それはドキュメント上の発見事項であり、曖昧に取り繕うべきものではありません。明確に指摘してください。Factorio のコードベースは、内部整合性の模範です。あらゆるシステムで、「ティック」の意味、「ベルト」が運べるもの、エンティティ同士の相互作用が一貫しています。ドキュメントによって、2つのシステムが根本的な前提で食い違っていると明らかになったなら、リリース前にバグを発見したことになります。

6. 3つのモードで、1つのパイプラインを使う。 コード分析パイプラインは、3つすべてのモードで共通です。変わるのは出力形式であり、分析の深さではありません。

ワークフロー

---

🧠 フェーズ1：プロジェクトのスキャン

目標：コードを読む前に、プロジェクトの構造、エンジン、構成を理解します。

PROJECT SCAN PROTOCOL
-------------------------------------------------
Step 1: Detect engine and framework
  Scan for:
  - project.godot, *.gd, *.tscn         --> Godot
  - *.unity, *.cs, ProjectSettings/      --> Unity
  - *.uproject, *.cpp/*.h with UE macros --> Unreal Engine
  - package.json with game libs          --> Web/JS game framework
  - Cargo.toml with game crates          --> Rust game framework
  - None of the above                    --> Custom engine or unknown

Step 2: Map directory structure
  Produce a tree of the project with annotations:
  /project-root/
    /src/ or /scripts/    -- Game logic
    /assets/ or /art/     -- Visual and audio assets
    /scenes/ or /levels/  -- Level/scene data
    /ui/                  -- User interface
    /data/ or /config/    -- Game data, settings
    /tests/               -- Test files (if any)
    /docs/                -- Existing documentation (if any)

Step 3: Measure project scale
  - Total source files: [N]
  - Total lines of code: [approximate]
  - Number of scenes/levels: [N]
  - Number of asset files: [N]
  - Estimated project complexity: [small / medium / large]

Step 4: Check for existing documentation
  - README present: [Y/N]
  - Design document present: [Y/N]
  - Inline comments density: [sparse / moderate / thorough]
  - Architecture docs present: [Y/N]
-------------------------------------------------

---

🎯 フェーズ2：システムの検出

目標：コードパターンから個別のゲームシステムを特定します。

ゲームシステムには、エンジンや言語を問わず、コード上に識別可能な特徴が現れます。このフェーズでは、特徴的なパターンをスキャンし、どのシステムが存在するかを特定します。

SYSTEM DETECTION HEURISTICS
-------------------------------------------------
MOVEMENT SYSTEM:
  Signals: velocity variables, position updates per frame, input axis
  reading, acceleration/deceleration curves, ground detection, gravity
  application, jump state machines, character controller references
  Common files: Player.*, CharacterController.*, Movement.*, Locomotion.*

COMBAT SYSTEM:
  Signals: damage calculation functions, health/HP variables, hit detection,
  attack state machines, weapon data structures, damage types/resistances,
  invincibility frames, knockback vectors
  Common files: Combat.*, Weapon.*, DamageSystem.*, Health.*, Attack.*

INVENTORY SYSTEM:
  Signals: item data structures, add/remove item functions, capacity limits,
  item stacking logic, equipment slots, item categories/types
  Common files: Inventory.*, Item.*, Equipment.*, ItemDatabase.*

UI SYSTEM:
  Signals: UI element references, menu state machines, HUD update functions,
  button callbacks, screen transition logic, UI animation triggers
  Common files: UIManager.*, HUD.*, Menu.*, Screen.*, Panel.*

AUDIO SYSTEM:
  Signals: sound effect triggers, music track management, volume controls,
  audio bus routing, spatial audio positioning, adaptive music states
  Common files: AudioManager.*, SoundManager.*, Music.*, SFX.*

SAVE/LOAD SYSTEM:
  Signals: serialization logic, file I/O operations, data persistence,
  save slot management, auto-save triggers, data migration
  Common files: SaveManager.*, SaveLoad.*, GameData.*, Persistence.*

AI SYSTEM:
  Signals: state machines (enemy states), pathfinding calls, behavior trees,
  decision-making logic, perception/detection systems, patrol patterns
  Common files: AI.*, Enemy.*, Behavior.*, StateMachine.*, NPC.*

PROGRESSION SYSTEM:
  Signals: XP/level calculations, unlock conditions, skill trees,
  achievement tracking, milestone checks, difficulty scaling
  Common files: Progression.*, Level.*, Unlock.*, Achievement.*, XP.*

PHYSICS/COLLISION:
  Signals: collision callbacks, physics material references, raycast
  usage, trigger zones, force application, rigid body management
  Common files: Physics.*, Collision.*, Trigger.*, WorldInteraction.*

CAMERA SYSTEM:
  Signals: camera follow logic, zoom controls, screen shake, camera
  bounds, cinematic camera paths, split-screen management
  Common files: Camera.*, CameraController.*, CameraManager.*
-------------------------------------------------

検出した各システムについて、以下を記録します。

SYSTEM INVENTORY
-------------------------------------------------
System          | Files Involved     | Complexity | Dependencies
-------------------------------------------------
[Movement]      | [file1, file2]     | [low/med/  | [depends on Physics,
[Combat]        | [file1, file2]     |  high]     |  Input, etc.]
[UI]            | [file1, file2]     |            |
...             |                    |            |
-------------------------------------------------

ORPHANED CODE (files that do not belong to any detected system):
  - [file] -- Purpose: [unclear / deprecated / utility / unknown]

MISSING SYSTEMS (expected but not found):
  - [e.g., "No save system detected -- game state is not persisted"]
  - [e.g., "No audio management -- sounds may be ad-hoc or missing"]

---

🚨 フェーズ3：メカニクスの抽出

目標：構造だけでなく、コードの振る舞いからゲームメカニクスを特定します。

メカニクスとは、相互作用を規定するルールです。コードはメカニクスを実装しますが、メカニクス自体はデザイン上の概念です。このフェーズでは、その隔たりを埋めます。

MECHANICS EXTRACTION
-------------------------------------------------
For each identified system, extract:

MECHANIC: [name, e.g., "Double Jump"]
  Implementation: [file:line -- brief code description]
  Rule: [the game design rule, e.g., "Player may jump once in the air
         after a ground jump. Air jump has 80% of ground jump force."]
  Parameters: [tunable values -- jump force, gravity, cooldown, etc.]
  Interactions: [how this mechanic connects to other mechanics]
  Design intent: [VERIFIED: developer confirmed / INFERRED: based on
                  code behavior / UNVERIFIED: unclear, needs clarification]
-------------------------------------------------

以下を探してください。

• ステートマシン -- 各状態は、プレイヤーや敵の個別の振る舞いを表している可能性があります
• 入力ハンドラー -- 各入力バインドから、プレイヤーのアクションが分かります
• 衝突時の処理 -- 各衝突コールバックから、相互作用のルールが分かります
• タイマーとクールダウン -- 各タイマーから、ペース配分やバランスに関する判断が分かります
• 定数と設定値 -- 調整可能な各数値から、バランス調整用のパラメーターが分かります

---

📋 フェーズ4：依存関係のマッピング

目標：各システムがどのように相互作用するかを可視化します。

DEPENDENCY MAP
-------------------------------------------------
[Movement] ---uses---> [Physics/Collision]
[Movement] ---reads--> [Input]
[Combat]   ---uses---> [Physics/Collision]
[Combat]   ---modifies-> [Health (in Movement entity)]
[UI]       ---reads--> [Health]
[UI]       ---reads--> [Inventory]
[Save]     ---reads--> [all systems with persistent state]
-------------------------------------------------

TIGHT COUPLINGS (potential refactoring targets):
  - [System A] directly modifies internal state of [System B]
    instead of using events/signals. Fragile if either changes.

CIRCULAR DEPENDENCIES:
  - [System A] depends on [System B] which depends on [System A].
    May cause initialization order bugs.

ISOLATED SYSTEMS:
  - [System X] has no dependencies and nothing depends on it.
    Verify: is this intentional or orphaned code?

---

🛠️ モード1：デザインドキュメントの生成（design）

出力：リバースエンジニアリングによって作成したゲームデザインドキュメント。

標準的な GDD テンプレートについては、@templates/game-design-document.md を参照してください。

# Reverse-Engineered Game Design Document

## Project Overview
- **Project name:** [from project config or directory name]
- **Engine:** [detected engine and version]
- **Genre:** [inferred from mechanics -- e.g., platformer, RPG, puzzle]
- **Estimated scope:** [small/medium/large based on file count and systems]

## Core Mechanics
[For each mechanic extracted in Phase 3, described in design language]

### [Mechanic Name]
**What the player experiences:** [description from player perspective]
**How it works:** [design-level explanation, not code]
**Tunable parameters:** [list of values that affect feel/balance]
**Design intent:** [VERIFIED/INFERRED/UNVERIFIED]

## Game Systems
[For each system detected in Phase 2]

### [System Name]
**Purpose:** [what this system contributes to the player experience]
**Components:** [files and classes involved]
**Key behaviors:** [bullet list of what this system does]
**Dependencies:** [what it needs from other systems]
**Provides to others:** [what other systems consume from it]

## System Interaction Map
[Dependency map from Phase 4, in readable format]

## Identified Gaps
[Missing systems, orphaned code, inconsistencies]

## Balance Parameters
[All tunable values extracted from code, organized by system]

## Recommendations
[Suggestions for design documentation that should be written manually
 to supplement what code analysis can provide -- narrative design,
 art direction, audio design, player onboarding]

---

📊 モード2：アーキテクチャ決定記録（architecture）

出力：コードパターンとアーキテクチャ上の選択を記録したアーキテクチャ決定記録。

標準的な ADR テンプレートについては、@templates/architecture-decision-record.md を参照してください。

# Architecture Overview: [Project Name]

## Technology Stack
- **Engine:** [name and version]
- **Language:** [primary language]
- **Key libraries/plugins:** [detected dependencies]

## Project Structure
[Annotated directory tree from Phase 1]

## Architectural Patterns Detected

### Pattern: [e.g., "Singleton Manager Pattern"]
**Where:** [files using this pattern]
**Purpose:** [why this pattern was likely chosen]
**Trade-offs:** [benefits and risks of this pattern in this context]
**ADR:** We use [pattern] for [reason]. This was likely chosen because
[inferred rationale]. Alternative approaches include [alternatives].

### Pattern: [e.g., "Component-Based Architecture"]
[Same structure]

## System Architecture
[For each system, describe its internal architecture]

### [System Name]
**Architecture:** [pattern used -- state machine, event-driven, etc.]
**Entry points:** [where execution starts for this system]
**Data flow:** [how data moves through the system]
**Extension points:** [where new behavior can be added]
**Coupling assessment:** [tight/loose, and to what]

## Cross-Cutting Concerns
- **State management:** [how game state is managed globally]
- **Event system:** [how systems communicate -- direct calls, signals, events]
- **Error handling:** [how errors are handled -- or not]
- **Configuration:** [how game parameters are stored and loaded]
- **Testing:** [test coverage, testability of architecture]

## Technical Debt Register
[Issues identified during code analysis]
| Area | Issue | Severity | Suggested Fix |
|------|-------|----------|---------------|
| [system] | [problem] | [high/med/low] | [recommendation] |

## Recommendations
[Architectural improvements, refactoring opportunities, scalability concerns]

---

🎭 モード3：コンセプトドキュメントの生成（concept）

出力：プレイ可能なプロトタイプから抽出したゲームコンセプトドキュメント。

標準的なコンセプトテンプレートについては、@templates/game-concept.md を参照してください。

# Game Concept Document: [Project Name]
*Reverse-engineered from playable prototype*

## Core Concept
**One-sentence pitch:** [inferred from core mechanics and theme]
**Core verb:** [the primary action the player performs]
**Core loop:** [the repeating cycle of play identified from code]

## Player Experience
**What the player does:** [moment-to-moment gameplay from mechanics]
**What the player feels:** [inferred emotional experience]
**What makes it interesting:** [unique mechanical interactions found]

## Mechanics Summary
[Condensed from Phase 3 -- design-language descriptions only]

## Visual Style
**Art approach:** [inferred from assets -- pixel art, 3D, vector, etc.]
**Color palette:** [extracted from art assets or UI if present]
**Visual complexity:** [minimalist / moderate / detailed]

## Audio Profile
**Music:** [present/absent, style if detectable]
**SFX:** [present/absent, coverage of mechanics]
**Audio completeness:** [placeholder / partial / complete]

## Scope Assessment
**Current state:** [prototype / alpha / beta / near-complete]
**Content volume:** [levels, items, enemies, etc. counted from data]
**Estimated completion:** [what remains to be built for a shippable game]

## Strengths (from code evidence)
[What the prototype does well -- tight mechanics, clean architecture, etc.]

## Gaps (from code evidence)
[What is missing or incomplete -- no save system, no audio, no UI, etc.]

## Recommendations for Full Development
[What to prioritize if taking this prototype to a full game]

品質チェック

すべてのリバースドキュメント作成では、以下を確認する必要があります。

QUALITY CHECKLIST
-------------------------------------------------
[ ] Every documented system traces to specific source files
[ ] Ambiguous intent is marked [UNVERIFIED], not guessed
[ ] Orphaned code is identified and listed
[ ] System dependencies are mapped, including circular dependencies
[ ] Inconsistencies between systems are flagged (not hidden)
[ ] All tunable parameters are extracted and listed
[ ] The documentation is organized by game system, not file structure
[ ] Missing expected systems are noted (no save, no audio, etc.)
[ ] The output matches the requested mode (design/architecture/concept)
[ ] File paths are absolute and accurate
[ ] The documentation is useful to someone who has never seen the code
-------------------------------------------------

相互参照

• @templates/game-design-document.md -- デザインモードの出力用テンプレート
• @templates/architecture-decision-record.md -- アーキテクチャモードの出力用テンプレート
• @templates/game-concept.md -- コンセプトモードの出力用テンプレート
• @docs/coding-standards.md -- 分析時に照合するコード規約
• @docs/game-design-theory.md -- メカニクスの説明に使うデザイン用語
• @docs/collaboration-protocol.md -- リバースドキュメントで得た知見をチームと共有する方法
• ワークフローの引き継ぎ：出力は検証用の game-design-review、アーキテクチャ評価用の game-code-review、またはドキュメント化したシステムのスコープ評価用の game-scope-check に引き継がれます

使用例

1. 「ゲームジャムのプロトタイプを、本格的なプロジェクトにしたいです。」 コンセプトモードで実行します。プロトタイプを調べ、核となるコンセプトを抽出し、機能している点と不足している点を特定して、開発全体の指針となるコンセプト文書を作成します。

2. 「新しい開発者が参加するので、コードベースを理解する必要があります。」 アーキテクチャモードで実行します。システム、パターン、依存関係、拡張ポイントを整理したアーキテクチャの概要を作成します。新しい開発者はすべてのファイルをくまなく調べる代わりに、この文書を読みます。

3. 「何か月も開発を続けてきましたが、デザイン文書を書いていません。」 デザインモードで実行します。コードからメカニクス、システム、パラメーターを抽出します。文書なしで開発を進めたことで生じた不足や矛盾も含め、ゲームデザインの現状を記録した GDD を作成します。

4. 「このモジュールを安全にリファクタリングできるよう、文書化してください。」 特定のパスを対象にアーキテクチャモードで実行します。モジュールの内部構造、依存関係、結合箇所を整理します。作成された ADR により、安全に変更できる箇所と、手を加えると壊れる箇所を把握できます。

5. 「このシステムをなぜこのように作ったのか、忘れてしまいました。」 特定のシステムパスを対象にデザインモードで実行します。メカニクスとパラメーターを抽出し、設計意図を再構築します。記憶がまだある程度残っているうちに、開発者が確認または修正できるよう、[UNVERIFIED] と記された項目にはフラグを付けます。

AlterLab GameForge -- Indie Game Development Skills スイートの一部です。