phaser-analyze

Phaser 4 ブラウンフィールドプロジェクト分析

既存の Phaser 4 プロジェクトを包括的に分析し、アーキテクチャの品質を評価し、パフォーマンス上のリスクを特定し、API の正確性に関する問題を洗い出し、優先順位付きの改善ロードマップを作成します。

分析プロセス

5 つのフェーズをすべて順番に実行します。フェーズを飛ばさないでください。各フェーズは前のフェーズの上に積み重なります。

フェーズ 1 — ディスカバリー

判断を下す前に、プロジェクトに関する生の事実を収集します。

• 依存関係と Phaser のバージョンを確認するため package.json を読み取る
• src/ 内のすべての .ts/.js ファイルを Glob で検索する
• GameConfig を確認するため main.ts を読み取る
• すべてのシーンを特定する: src/ 全体で grep "extends Phaser.Scene" を実行する
• シーングラフをマッピングする: this.scene.start、this.scene.launch、this.scene.stop を grep で検索する
• すべてのカスタムゲームオブジェクトを特定する: grep "extends Phaser.Physics" または grep "extends Phaser.GameObjects" を実行する
• ソースファイルの総数とコード行数を数える

フェーズ 2 — アーキテクチャ評価

コードベースの構造的な品質を評価します。

• シーンの数と構成 — シーンは src/scenes/ にありますか？ ゲームの複雑さに対して多すぎたり少なすぎたりしませんか？
• 状態管理パターン — Registry 対 グローバル 対 モジュール状態。window.、モジュールレベルの let/var 宣言を検索します。
• アセット読み込み戦略 — 集中管理された PreloaderScene 対 シーン全体に散在する preload() メソッド。
• コード構成 — プロジェクトは scenes/、objects/、managers/ の規約に従っていますか？
• シーン間の結合分析 — 直接参照 対 イベントバス 対 Registry。this.registry、this.events.emit、this.scene.get を検索します。

調査結果に基づいてアーキテクチャを A から F で評価します:

• A — 明確な分離、集中管理された読み込み、イベント駆動型の通信
• B — 軽微な構成上のギャップはあるが、ほぼ適切に構造化されている
• C — いくつかの結合問題、混在したパターン、機能的だが雑然としている
• D — 重大な構造的問題、グローバル、散在する読み込み
• F — 認識できるアーキテクチャがない、すべてが 1 つのファイル内にあるか深く絡み合っている

フェーズ 3 — パフォーマンス監査

実行時のパフォーマンスリスクを特定します。

• オブジェクトプーリング: グループ宣言内の classType/maxSize を検索します。maxSize を欠いた this.physics.add.group() で作成された物理グループにフラグを立てます — これらはオブジェクトをリークします。
• パーティクルエミッターの上限: maxParticles を欠いたパーティクルエミッターを検索します。上限のないエミッターはフレーム時間を急増させる可能性があります。
• 静的グループ 対 動的グループ: プラットフォーム、壁、その他の不動体が staticGroup()（正しい）を使用しているか group()（物理サイクルを浪費する）を使用しているかを確認します。
• 更新ループの負荷: 各シーンの update() メソッドを読み取ります。update() 内の複雑なロジック、オブジェクト割り当て（new）、または重い反復処理にフラグを立てます。
• テクスチャアトラスの使用: 個別の this.load.image() 呼び出しと this.load.atlas() 呼び出しを数えます。15 を超える個別の画像読み込みは危険信号です — アトラスにまとめるべきです。
• 物理ボディの数: グループ宣言と個別の this.physics.add.* 呼び出しから、アクティブな物理ボディの総数を推定します。

フェーズ 4 — API の正確性

非推奨、削除済み、または誤用されている API を確認します。

• v3 API スキャン: 削除された API を検索します — Geom.Point、Math.PI2、Phaser.Structs、Camera3D、Layer3D、FacebookInstant、Create.GenerateTexture、TileSprite.setCrop。
• TypeScript の厳格性: as any、@ts-ignore、型指定のない関数パラメータを Grep で検索します。これらは実際のバグを隠します。
• アセットキーの一貫性: this.load.* のキーと this.add.*/this.physics.add.* のキーを相互参照します。キーの不一致はサイレントなテクスチャ欠落エラーを引き起こします。
• シーンキーの登録: すべてのシーンクラスが main.ts の GameConfig シーン配列に含まれていることを確認します。
• 物理ボディの作成: this.physics.add.sprite() であるべき this.add.sprite() 呼び出しにフラグを立てます（物理ボディを持つことが期待されているのにボディなしで作成されたスプライト）。
• DynamicTexture/RenderTexture: 描画操作の後に .render() 呼び出しが欠落していないか確認します。

フェーズ 5 — ベストプラクティスチェック

プロジェクトが Phaser 4 のベストプラクティスに従っているかを検証します。

• ライフサイクルの規律: preload() はアセットの読み込みのみを行うべきで、create() はシーンの構築のみを行うべきで、update() は軽量であるべきです（アセットの読み込みやオブジェクトの生成を行わない）。
• シャットダウン時のクリーンアップ: シーンはクリーンアップすべきです — this.events.off、this.sound.stopAll()、タイマーの破棄、this.events.on('shutdown', ...) を探してください。
• カメラの境界: カメラの境界はワールドまたはタイルマップの境界と一致すべきです。this.cameras.main.setBounds を検索し、ワールド／マップの寸法と比較してください。
• 入力キーボードの null アサーション: Phaser 4 では this.input.keyboard が null になる可能性があります。this.input.keyboard! または適切な null ガードがあるかを確認してください。
• 物理のデバッグフラグ: 物理設定の debug: true は本番環境では false にすべきです。存在する場合は指摘してください。
• コンソールステートメント: console.log／console.warn／console.error の呼び出しを数えてください。これらは import.meta.env.DEV の背後にゲートするか、本番環境では削除すべきです。

出力フォーマット

以下のセクションを含む構造化されたレポートを作成してください。

1. プロジェクト概要 — ファイル数、シーン数、コード行数、推定複雑度（小／中／大）。
2. アーキテクチャスコア — 評価の根拠を添えたアルファベット評価（A/B/C/D/F）。
3. パフォーマンスリスク — 深刻度（critical／high／medium／low）順に並べ、それぞれに具体的な修正提案を付けてください。
4. コード品質の問題 — 可能な限り file:line 参照を付けてください。
5. 改善ロードマップ — 影響度と労力の観点で優先順位を付けたリファクタリング手順。
6. クイックウィン — 目に見える改善のためにすぐ実施できる 3〜5 個の変更。

関連スキル

• フェーズ 4 で見つかった Phaser v3 API の問題を修正するには /phaser-migrate を使用してください。
• フェーズ 3 のオブジェクトプーリングの実装と物理グループの問題を修正するには /phaser-physics を使用してください。
• フェーズ 3 で指摘されたランタイムパフォーマンスの問題を調査するには、phaser-debugger エージェントを使用してください。

参照ファイル

• references/analysis-checklist.md — すべてのチェックについての grep パターン、深刻度評価、修正参照を含む完全なチェックリスト。
• references/performance-playbook.md — ミドルレンジのモバイルターゲット向けの 9 フェーズからなる Phaser 4 パフォーマンスプレイブック: 計測優先のプロンプティング、フレームごとの割り当ての排除、レジストリのスロットリング、音声の遅延読み込み、VFX のプーリング、空間グリッド、アトラスパッキング、イベントのスロットリング、実際のデルタを用いた AI のティックスキップ、トゥイーンのクリーンアップ。FPS が目標を下回る場合や、ゲームプレイ中にメモリが増加する場合に読んでください。

自動プリスキャン

手動の詳細レビューを始める前に、自動分析スクリプトを実行してください:

bash "${CLAUDE_PLUGIN_ROOT}/skills/phaser-analyze/scripts/analyze-project.sh"

これによりベースラインの指標が得られ、明らかな問題が指摘されます。スクリプトの出力を出発点として使用し、その後、実際のソースファイルを読んで 5 フェーズの完全な分析を実行してください。