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 の場合は 1 ページの概要を作成するため、 ティアを誤ると成果物全体が不適切なものになります。

例：

/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：明確化のための質問をする

コードの説明だけで済ませてはいけません。意図について質問してください。

設計に関する質問：

• 「[resource] システムは [activity] 中に減少するようですね。これは次のどれを意図したものですか？
  • ペース配分（スパムを防ぐため）？
  • リソース管理（戦略性を高めるため）？
  • それとも別の目的ですか？」
• 「[mechanic] は中核となる要素のようです。これは主要な柱ですか、それとも補助的な機能ですか？」
• 「[Value] は [factor] に応じて指数関数的に増加します。意図した設計ですか、それともバランス調整が必要ですか？」

アーキテクチャに関する質問：

• 「サービスロケーターパターンを使用していますね。これは次のどれを目的に選択しましたか？
  • テスト容易性（依存関係をモックするため）？
  • 疎結合化（直接的な参照を減らすため）？
  • それとも既存のコードから引き継いだものですか？」
• 「スマートポインターではなく、手動でメモリー管理を行っていますね。パフォーマンス要件ですか、それともレガシーな実装ですか？」

コンセプトに関する質問：

• 「プロトタイプでは戦闘よりもステルスが重視されています。これは意図した柱ですか？」
• 「プレイヤーはグラップリングフックを速度向上に利用しているようです。これは仕様ですか、それとも不具合ですか？」

フェーズ 3b：十分性の確認 — ドキュメント化に足る情報がありますか？

フェーズ 4 の前にこれを実行し、条件を満たさない場合はここで中止してください。 このスキルは実装から設計を推測するため、実装が薄い場合は推測の材料がありません。以下のテンプレートはすべてのセクションが必須なので、内容を捏造しても受け入れてしまいます。

フェーズ 2 で実際に見つかったものを数えてください。

シグナル	該当するもの
メカニクス	観察可能なルールを持つ、名前の付いた動作。スタブや空のクラスは含みません
数式	入力からゲームプレイ値を算出する式
値	使用箇所がある調整用定数

3つすべての数がゼロの場合、または対象パスに定型コード以外のコードが約20行未満しかない場合は、中止して次のように伝えてください。

「[path] には、実装から逆引きしてドキュメントを作成するのに十分な内容がありません。 見つかったもの：[N] 個のメカニクス、[N] 個の数式、[N] 個の調整値。 逆引きドキュメントでは動作から設計を推測します。読み取れる動作がなければ、私が作成するものは設計ドキュメントの形式をまとった創作になってしまいます。 設計が頭の中にしかない場合は、/design-system [name] がそれを形にするスキルです。推測するのではなく、質問をします。」

不足分を埋めて、部分的な集計を完成させてはいけません。 メカニクスが2つあり、数式がないパスの場合、メカニクスが2つ記載され、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 と記載してください。見出しを省略すると「調査していない」と受け取られるため、省略してはいけません。また、この種のシステムに通常あるものから内容を補ってはいけません。角括弧で示された行は形式であり、ノルマではありません。メカニクスが1つのソースなら、行は4つではなく1つです。

これはレポートよりもここで重要です。このスキルの出力はレポートではなく、設計ドキュメントだからです。/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 を作成します（Overview、Detailed Design、Edge Cases、 Dependencies、Acceptance Criteria。復元したシステムで数値ルールが定義されている場合は Formulas も追加します）。Player Fantasy と Tuning Knobs は省略します。
• minimal — GDD ではなく、1 ページ形式の ゲームブリーフ（.claude/docs/templates/game-brief.md）を作成します。ゲーム全体を対象とする場合 （パスがコードルートそのものの場合）は 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]?

プロンプトでは、ティアに合った出力パスを使用してください。full／standard の GDD では design/gdd/[system-name].md、minimal のブリーフでは design/[system-name]-brief.md を指定します。

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] に書き込んでもよいですか？」承認された場合：判定：完了 — ドキュメントが生成されました。拒否された場合：判定：ブロック — ユーザーが書き込みを拒否しました。
8. フォローアップを示す：関連作業を提案し、自動実行はしません

意図を決して推測しないでください。「なぜ」をドキュメントに記載する前に、必ず尋ねてください。