hz-unity-project-analyzer

Unity プロジェクトアナライザー

AI エージェントが理解しやすいように最適化された、Unity プロジェクトの構造に関するナレッジベースを分析、文書化し、継続的に更新します。出力は、ソース管理に適した Markdown ファイルとして .agent-docs/ に保存されます。

操作モード

このスキルは 4 つのモードで動作します。状況に応じて使用するモードを判断してください。

Mode 1: 初回の全体スキャン

トリガー： .agent-docs/ ディレクトリまたは .agent-docs/index.md が存在しません。

Mode 2: 差分更新

トリガー： ユーザーがドキュメントの更新を依頼した場合、または AI エージェントが構造上の変更（新しいシーン、スクリプト、プレハブ、システムなど）を行った場合です。デフォルトの更新モードです。

重要： 差分更新は実装の一部であり、独立したステップではありません。スクリプト、プレハブ、アセットを作成または変更する際は、次のタスクに進む前に、同じ作業の中で対応する .agent-docs/ ファイルを更新してください。

Mode 3: 全体の再スキャン

トリガー： ユーザーが明示的に全体の再スキャンを依頼した場合（例：「プロジェクトを再スキャン」「プロジェクト全体を分析」）。

Mode 4: 情報の読み込み

トリガー： ユーザーがプロジェクトの構造や、システム／機能の仕組みについて尋ねた場合（例：「このプロジェクトは何をするのか」「ボールシステムの仕組み」「プロジェクト構造」「プロジェクト分析を読み込む」）。このモードは .agent-docs/ が存在する場合にのみ使用してください。このモードは読み取り専用です。ドキュメントを変更しないでください。

---

全体スキャン（Mode 1）および全体の再スキャン（Mode 3）の手順

Step 1: プロジェクトの概要を把握する

1. README.md、CHANGELOG.md、および Documentation/ フォルダー内のドキュメントを読みます
2. Packages/manifest.json を読み、含まれているすべてのパッケージを確認します
3. すべてのシーンを一覧表示します：Assets/**/*.unity
4. すべてのスクリプトフォルダーとアセンブリ定義を一覧表示します：Assets/**/*.asmdef
5. .prefab ファイルを含むディレクトリを探し、すべてのプレハブフォルダーを一覧表示します
6. ProjectSettings/ProjectVersion.txt からプロジェクトの Unity バージョンを特定します
7. エディターに接続できる場合（unity status --format json で状態が ready と表示される場合）は、ファイルだけでは得られない詳細情報を得るため、エディターを直接調査します。unity command get_scene_hierarchy、find_assets、package_list --scope installed、および get_*_settings コマンド（get_player_settings、get_quality_settings、get_graphics_settings）を使用してください。unity-cli スキルを参照してください。
8. ヘッドセットが接続されている場合は、テストデバイスのベースラインを記録します（OS バージョン、フォームファクター）。metavr device list と metavr device info <id> を使用し、後の調査結果で観測に使用したハードウェアを明記できるようにします。

Step 2: 確認事項を質問する

文書化する前に、コードやドキュメントだけでは明確でない事項について、ユーザーに質問してください。例：

• 「X、Y、Z という名前のシーンがあります。メインのエントリーポイントはどれですか？」
• 「[name] というフォルダーに、用途を特定できないアセットがあります。何に使うものですか？」
• 「ネットワーク関連の方式が複数あります。主に使うのはどれですか？」

本当に曖昧な項目についてのみ質問してください。命名、フォルダー構造、コードの調査から明らかな場合は、そのまま記録してください。

Step 3: 分析して文書化する

以下の各カテゴリについて、対応するサブドキュメントを作成または更新してください。

3a. プロジェクト概要（.agent-docs/project-overview.md）

• プロジェクト名、説明、Unity バージョン
• 対象プラットフォーム
• アーキテクチャの概要
• 主なサードパーティ製パッケージと、このプロジェクトでの用途（概要レベルのみ。内部の仕組みは含めない）

3b. シーンの流れ（.agent-docs/scenes/）

シーンごとにファイルを 1 つ作成します（例：.agent-docs/scenes/startup.md）。

各シーンのドキュメントには、以下を記載してください。

• プロジェクト内での目的と役割
• 主要な GameObject とその用途
• 使用されるスクリプト／プレハブ
• シーン遷移（このシーンを読み込むもの、このシーンが読み込むもの）
• メインの実行時フローの一部か、テストシーンか、サンプルか

mermaid を使って、.agent-docs/scenes/_flow.md にシーンフロー図を作成してください：

graph LR
    Startup --> MainMenu --> Gameplay

3c. システム（.agent-docs/systems/）

ネットワーク、UI、オーディオ、入力、ゲームプレイなどの論理システムを特定し、システムごとにファイルを1つ作成します。

各システムのドキュメントには、以下を記載します。

• 目的と責務
• 主要なスクリプト（ファイルパスを含む）とその役割 — 実装ではなく、使い方に重点を置いてください
• システムが使用する主要なプレハブ
• 他のシステムとの依存関係
• 相対リンクを使用した、関連シーンおよび他のシステムドキュメントへの相互参照

3d. プレハブ（.agent-docs/prefabs/）

明確さに応じて、まとめて記載するか、個別に記載します。

• プレハブのフォルダーが命名から見て明確な場合 → グループドキュメント（例：.agent-docs/prefabs/ui-elements.md）
• 個々のプレハブの目的が名前から分かりにくい場合 → 個別に記載（例：.agent-docs/prefabs/player-rig.md）

各プレハブ／グループについて、以下を記載します。

• 目的と使用する場面
• 入れ子になったプレハブの階層（入れ子のプレハブとバリアントを記載）
• アタッチされている主要なコンポーネント
• 使用しているシーン
• 設定に関する注意事項（重要なインスペクターの値、必須の参照など）

3e. アセット（.agent-docs/assets/）

スクリプトでもプレハブでもないアセットを、状況に応じて記載します。

• マテリアル、シェーダー、テクスチャ、オーディオ、アニメーション、スクリプタブルオブジェクト
• フォルダー名が明確な場合はまとめ、目的が分かりにくい場合は個別に記載
• 重点項目：それが何か、何のためのものか、どこでどのように使用されているか

3f. スクリプトリファレンス（.agent-docs/scripts/）

スクリプトはコードによって自己記述されています。ここでは使用状況のみを記載します。

• システムまたは機能領域ごとに整理
• 各スクリプトについて、目的、使用方法、関連するプレハブ／シーンを記載
• コードを重複して記載したり、実装の詳細を説明したりしないでください

ステップ 4：インデックスを作成する

メインのエントリーポイントとして .agent-docs/index.md を作成または更新します。

# [Project Name] — Agent Documentation

> Auto-generated project knowledge base for AI agent comprehension.
> Last updated: YYYY-MM-DD

## Quick Context
[2-3 sentence project summary]

## Document Map
- [Project Overview](project-overview.md)
- Scenes
  - [Scene Flow](<scenes/_flow.md>)
  - [SceneName](<scenes/scene-name.md>)
  - ...
- Systems
  - [SystemName](<systems/system-name.md>)
  - ...
- Prefabs
  - [PrefabGroup](<prefabs/group-name.md>)
  - ...
- Assets
  - [AssetGroup](<assets/group-name.md>)
  - ...
- Scripts
  - [ScriptArea](<scripts/area-name.md>)
  - ...

## Runtime Flow
[Brief description of app lifecycle from launch to gameplay]

ステップ 5：設定ファイルを作成する

.agent-docs/_config.md を作成します。

---
last_full_scan: YYYY-MM-DD
last_update: YYYY-MM-DD
documented_systems:
  - system-name-1
  - system-name-2
documented_scenes:
  - scene-name-1
  - scene-name-2
documented_prefab_groups:
  - group-name-1
  - group-name-2
---

---

増分更新の手順（モード 2）

1. .agent-docs/_config.md と .agent-docs/index.md を読みます
2. 変更内容を特定します。
   • AI エージェントが変更を加えた直後の場合：その変更の影響を受けるドキュメントのみを更新します
   • ユーザーから更新を依頼された場合：現在のプロジェクトの状態をドキュメントの記載内容と比較します
     • シーン、スクリプト、プレハブの新規追加、削除、名称変更を確認します
     • Packages/manifest.json に新しいパッケージが追加されているか確認します
     • 必要に応じて、最近変更されたファイルを git status で確認します
3. 影響を受けるサブドキュメントのみを更新します
4. 古い参照を整理します。 スクリプト、プレハブ、アセットが削除または名称変更された場合、影響を受けるドキュメント内の参照を削除または更新します。リンク切れを残さないでください。
5. 新しいドキュメントが追加または削除された場合は、.agent-docs/index.md を更新します
6. .agent-docs/_config.md の last_update と、ドキュメント化されたリストを更新します

変更されていないドキュメントを書き直さないでください。

---

読み込みの手順（モード 4）

1. .agent-docs/index.md が存在するか確認します。存在しない場合はスキップします（読み込むドキュメントはありません）。
2. .agent-docs/index.md を読み、ドキュメントマップと概要を確認します
3. ユーザーの質問に基づき、関連するサブドキュメントのみを読みます。例：
   • 「このプロジェクトは何をするものですか？」→ project-overview.md を読む
   • 「ボールシステムはどのように動作しますか？」→ systems/balls.md を読む
   • 「どのようなシーンがありますか？」→ scenes/_flow.md を読む
   • プロジェクト全般についての質問 → project-overview.md と scenes/_flow.md を読む
4. コンテキストを絞るため、すべてのサブドキュメントを先回りして読むのではなく、必要に応じて読みます

---

ドキュメント作成ガイドライン

• 対象読者： まず AI エージェントを対象とします。明確で、構造化され、曖昧さのない記述にしてください。
• 分量： 各サブドキュメントは簡潔にまとめてください。段落よりも構造化されたリストを優先してください。各ドキュメントは 200 行未満を目安にします。
• 相互参照： 実際に依存関係や関連性がある場合は、ドキュメント間を相対パスの Markdown リンクでつないでください。
• 図： 文章よりもフローやアーキテクチャを明確にできる場合は、mermaid を使用してください。文章のほうが明確な場合は省略します。
• サードパーティ製パッケージ： プロジェクトでの使用方法を記載してください。パッケージ内部の仕組みは記載しないでください。
• スクリプト： 目的と使用方法を記載してください。実装については記載しないでください。コード自体が説明になっています。
• プレハブ： 入れ子になった階層を記載してください。インスペクターの重要な設定にも触れてください。
• ソース管理： 1 ファイルにつき 1 つの概念を扱います。内容がわかるファイル名を付け、大規模で一枚岩のドキュメントは避けてください。
• 古さの判定： 各サブドキュメントの先頭に Last updated: YYYY-MM-DD を記載してください。更新が必要な可能性のあるドキュメントを特定しやすくなります。
• 日付： Last updated フィールドには日付のみを記載し、括弧書きの注記は付けないでください。

ファイル命名規則

• すべてのファイル名に小文字のケバブケースを使用してください：player-controller.md、main-menu.md
• フロー／インデックスファイルにはアンダースコアを接頭辞として付けてください：_flow.md、_config.md
• シーン名／システム名に合わせ、ケバブケースにしてください：Startup.unity → startup.md