ue5-debug-validation

クイックスタート

• 最小限の手順で問題を再現します。
• 出力ログの行と、関連するアクター／アセットの状態を収集します。
• 障害領域を分類します：データ、Blueprint、C++、ネットワーク、またはエディター設定。

API の手がかり（UE5.6-UE5.8）

• コア診断の手がかり：
  • UE_LOG(...)
  • ensure(...)、ensureMsgf(...)
  • check(...)、checkf(...)
• ランタイムデバッグ出力の手がかり：
  • UEngine::AddOnScreenDebugMessage(...)
  • UKismetSystemLibrary::PrintString(...)
• 構造化ログレビューの手がかり：
  • FMessageLog::Info(...)
  • FMessageLog::Warning(...)
  • FMessageLog::Error(...)
• アセット／設定検証の手がかり：
  • FAssetRegistryModule、IAssetRegistry
  • GetAssetsByPath(...)
  • GetDependencies(...)、GetReferencers(...)

デバッグステージの要件

• すべてのデバッグタスクで、以下を定義する必要があります：
  • 再現可能なシナリオと、期待される動作と実際に観測された動作
  • データ収集セット（ログ、ランタイム状態、アセット／設定のスナップショット）
  • 実行パイプラインにおける最初の不正な遷移の候補
  • 確率と検証コストの順に順位付けした仮説リスト
  • 修正の検証と回帰テストの範囲
• いずれかの項目が欠けている場合、診断結果は不完全です。

ワークフロー

1) 再現してコンテキストを固定する

• 正確な手順と前提条件を含む、最小限で決定論的な再現手順を作成します。
• マップ、アクターの設定、入力シーケンス、ランタイムモードを記録します。
• 期待される結果と、観測された差異を定義します。

2) シグナルを収集する

• 障害発生前後の時間範囲で、関連カテゴリとタイムスタンプに基づいてログを絞り込みます。
• 必要に応じて、対象を絞ったデバッグマーカー（UE_LOG、画面上のデバッグ表示、またはBlueprintのプリント）を追加します。
• ステージ境界ごとに、関連する状態のスナップショットを記録します。

3) データとアセットを検証する

• 主要なアセット／クラス／設定エントリーが存在し、正しく解決されることを確認します。
• 依存関係／参照元を確認し、アセットの欠落や不一致がないか調べます。
• ランタイムで読み込まれたデータが、想定される環境と一致することを確認します。

4) 最初の不正な遷移を特定する

• パイプラインをステップごとにたどり、最初に逸脱する箇所を特定します。
• 根本原因と、後続で発生するノイズ症状を切り分けます。
• 修正可能な原因のうち、確信度が最も高いものを優先します。

5) 仮説と検証

• 確率と検証コストに基づいて仮説に順位を付けます。
• 相互汚染を避けるため、各仮説について焦点を絞ったテストを1つ実行します。
• 棄却した仮説は、根拠とともに記録します。

6) 修正と回帰検証

• 最小限の修正を適用し、同じ再現シナリオを再実行します。
• 隣接するシステム／経路に回帰がないことを検証します。
• 確信度と残存リスクを含む修正の概要を出力します。

制約

• 診断中に広範囲なリファクタリングを行わないでください。
• 再現手順は決定論的かつ文書化された状態に保ってください。
• 仮定よりも、観測可能なチェックを優先してください。
• 根本原因と二次的なノイズを切り分けてください。
• 計測の変更と機能修正を、1つのステップで混在させないでください。
• 緩和策の変更を導入する前に、失敗時の証拠を保持してください。

障害への対処

• 症状：問題を一貫して再現できない。
  • 特定：前提条件の欠落、競合が発生する時間帯、または非決定的な設定を確認します。
  • 修正：再現手順の設定を厳密にし、対象を絞った計測チェックポイントを追加します。
• 症状：ログに無関係なノイズが多すぎる。
  • 特定：ログカテゴリの範囲が広すぎることと、時間範囲が適切に絞られていないことを確認します。
  • 修正：カテゴリフィルターを絞り込み、障害発生時刻の前後に焦点を合わせます。
• 症状：原因として考えられるものが複数残っている。
  • 特定：最初の障害箇所を切り分けられておらず、後続で共有される症状が発生していないか確認します。
  • 修正：仮説を個別に分け、低コストで原因を判別できるテストを実行します。
• 症状：デバッグ出力の追加後に問題が消える。
  • 特定：タイミング依存／競合依存の動作を確認します。
  • 修正：オーバーヘッドの小さいマーカーを使い、タイミングを制御して繰り返します。
• 症状：修正で1つの経路は解決するが、別の経路が壊れる。
  • 特定：システム間または設定レイヤー間に隠れた結合がないか確認します。
  • 修正：修正を最小限に保ち、影響を受ける経路を中心に回帰テストの範囲を広げます。
• 症状：ランタイムの不一致がパッケージビルドでのみ発生する。
  • 特定：エディター実行とのビルド設定／クックの差異を確認します。
  • 修正：パッケージ版とエディターの設定／アセットを比較し、読み込み順序を検証します。

検証運用

• 診断結果とともに、最小限の再現用アーティファクト（手順、マップ、設定）を必ず保持してください。
• 最終的な症状のログだけでなく、最初の失敗を示す証拠も必ず含めてください。
• 提案する修正の検証チェックリストを必ず提示してください。
• 確信度が高くない場合は、残存するリスクを必ず明記してください。

UE5.6-UE5.8 互換性に関する注意事項

• 上記のロギング／アサーション／メッセージ／アセットレジストリ API は、UE5.6-UE5.8 で安定しています。
• エディター外で実行する必要がある検証経路では、実行時に安全な診断を優先してください。

エスカレーション

• 失敗が、プロジェクトコードの管理対象外であるエンジン／プラグインの内部で発生している場合は、エスカレーションしてください。
• 現在の環境では利用できないプラットフォーム固有のプロファイリングツールが診断に必要な場合は、エスカレーションしてください。