roblox-debugging-bugfix

Roblox のデバッグとバグ修正

目標

推測せず、症状から検証済みの修正へ進みます。難しいバグや断続的に発生するバグでは、正当な理由がある場合に限りフェーズを省略し、以下の手順に従ってください。

フェーズ 1 — まず再現ループを作る（これがスキルです）

バグに対する高速で再現性のある合否シグナルさえ得られれば、それ以外はすべて機械的な作業です。ここに労力を惜しまずかけてください。修正に手をつける前に、積極的かつ創造的に取り組んでください。

再現ループの作り方の例を、おおよその優先順に示します。

1. Studio でのプレイテストによる再現 — バグを発生させるプレイモードでの正確な手順を実行し、get_console_output を確認します。
2. execute_luau ハーネス — ゲーム全体を操作するのではなく、問題が疑われるサーバー／モジュール関数をフィクスチャ入力で直接呼び出し、結果をアサートします。
3. 対象を絞ったシナリオ — コードパスを実行する最小限のインスタンス／状態（1 つのパーツ、1 つのリモート、1 つのプレイヤー状態）を生成します。
4. キャプチャしたペイロードの再生 — 問題を起こす実際のリモートペイロード／データプロファイルを保存し、隔離した状態でコードパスに再度渡します。

ループは高速で、焦点が明確で、決定論的なものにしてください。特定の症状に絞り、ランダム性やタイミングを固定し、無関係なセットアップを取り除きます。30 秒かかる不安定なチェックより、2 秒で終わる決定論的なチェックのほうが優れています。

断続的に発生するバグ： 目標は一度で確実に再現することではなく、再現率を上げることです。トリガーを何度も繰り返し、負荷を加え、タイミングの幅を絞ります。再現率が 50％のバグでもデバッグできます。再現率が上がるまで改善を続けてください。

本当にループを作れない場合は、作業を止めてその旨を伝えてください。試したことを列挙し、環境、キャプチャした成果物（ログダンプ、タイムスタンプ付きの画面録画、問題のデータ）、または一時的な計測機能を追加する許可をユーザーに求めてください。ループなしで仮説を立ててはいけません。

フェーズ 2 — 再現する

ループを実行します。ユーザーが説明した不具合（似ているだけの別の症状ではなく）が発生すること、繰り返し発生すること、後で検証するための正確な症状を記録したことを確認してください。

フェーズ 3 — 仮説を立てる

検証を始める前に、反証可能な仮説を 3～5 個、優先順位を付けて作成します。仮説を 1 つだけに絞ると、最初の推測に固執しやすくなります。それぞれに予測を記します。「X が原因なら、Y を変更すると症状が消える」。調査を始める前に、優先順位を付けた一覧をユーザーに見せてください。ユーザーは「#3 はたった今変更しました」のように、すぐ優先順位を付け直すことがよくあります。ユーザーが離席中なら、自分の優先順位に従って進めてください。

フェーズ 4 — 計測する

各調査は 1 つの仮説に対応させ、変更する変数は一度に 1 つだけにします。ログを大量に出すより、実際の値を調べる（inspect_instance、execute_luau）方法を優先します。一時的なログにはすべて、[DEBUG-a4f2] のような一意のプレフィックスを付けてください。これにより、script_grep でまとめて削除できます。パフォーマンスの低下は、まず計測（タイミング／os.clock、MicroProfiler、インスタンス数）してから二分探索します。通常、ログは適切なツールではありません。

フェーズ 5 — 修正と回帰チェック

multi_edit を使って、最小限で安全な修正を行います。完了と判断する前に、適切な接続点がある場合は、再現手順を長期的に維持できるチェックにします（execute_luau によるアサーション、または文書化されたプレイテスト手順）。適切な接続点がない場合は、それ自体が発見事項です。アーキテクチャ上の問題により、バグの再発防止を確実にできないことを記録してください。

デバッグループ（手順）

1. ユーザーに見える症状と期待される動作を記録します。
2. 可能であれば、プレイモードで再現します。
3. get_console_output を読みます。
4. script_grep と script_search で検索します。
5. 関連するスクリプトを script_read で読みます。
6. search_game_tree と inspect_instance で関連するインスタンスを調べます。
7. multi_edit で最小限かつ安全な修正を行います。
8. 再現手順を再実行し、コンソール出力を再確認します。
9. [DEBUG-...] の計測コードをすべて削除します（script_grep でプレフィックスを検索します）。

よくあるバグの種類

• クライアントとサーバーの状態の不一致。
• リモートペイロードの信頼性に関する問題。
• サーバーの状態変更後に UI が更新されない。
• イベント接続が重複している、または切断されていない。
• DataStore の読み込み／保存の競合。
• オブジェクトのパス名が変更されている、または見つからない。
• プレイモードの DataModel の不一致。
• キャラクターのスポーン、UI の作成、サーバーの初期化の間の競合。

修正ルール

• 防御的にエラーを黙殺するのではなく、根本原因を修正してください。
• コンテキストを記録せずにエラーを握りつぶさないでください。
• 信頼境界の近くで検証を追加してください。
• バグ修正に無関係なリファクタリングを含めないでください。
• 新たなコンソールエラーがないことを確認してください。

出力

以下を返してください。

• 再現手順。
• 根本原因（どの仮説が正しいと判明したかを明記してください）。
• 変更したファイル／スクリプト。
• 実施した検証。
• 残存するリスク。
• 事後分析：このバグを防ぐには何が必要でしたか？ アーキテクチャ上の問題（適切なテストの接点がない、クライアントとサーバーの境界が複雑に絡み合っている、隠れた依存関係があるなど）が原因の場合は、修正を反映した後で、roblox-code-maintenance-refactor または roblox-luau-architecture の利用を提案してください。修正前には提案しないでください。

次のステップ

roblox-playtest-qa（UI／モバイルに影響する変更がある場合は roblox-mobile-playtest も）で修正が有効であることを確認してください。事後分析でアーキテクチャ上の負債が明らかになった場合は、roblox-luau-architecture または roblox-code-maintenance-refactor に引き継いでください。ロードマップを再開するために、roblox-game-development-lifecycle に戻ってください。