debugging-code

コードのデバッグ

Rider で開いたソリューションを対象に、C#、C++、F#、VB、Unreal Engine などの GameDev プロジェクトをデバッガー優先で実行時の根本原因分析します。

すべてのツールは execute_tool(command="<tool> --arg value ...") を通じて呼び出してください。基盤となるハンドルを直接呼び出さないでください。reference/tools.md は、呼び出す直前の特定のツールについてのみ読み込んでください。ツリー全体を事前に読み込まないでください。

目標

静的なコードの読み取りだけでは不十分な場合や、静的解析で得た考えや結果を確認する場合に、デバッガーの証拠を用いて具体的な実行時の質問に答えます。これには、ブレークポイントまたはトレースポイントを使って、実行がエージェントの選択したコード位置に到達するかどうかの確認も含まれます。

このスキルを使う場合

次のいずれかに該当する場合は、このスキルを使ってください。

• 実行時の状態や制御フローの証拠（実際の値、実行された分岐、呼び出し順序、スレッドのコンテキスト、選択した位置に実行が到達するかどうか）が必要であり、ソースやログから確信を持って導き出せない。
• 関連する経路を見つけるには、多数のファイルを読むか、長い呼び出しチェーンを手動で追跡する必要がある。
• ユーザーがデバッガーの使用を明示的に依頼している（ブレークポイント、ステップ実行、値の確認、デバッガーセッション）。

ユーザーがこのスキルを手動で有効にしたり、言及したりした場合、必要なツールが利用可能であれば、デバッガーの起動と使用を明示的に依頼されたものとして扱ってください。概念的な説明だけにとどめないでください。

次のいずれかに該当する場合は、デバッガーを使わず（静的解析またはログの調査を使ってください）。

• コンパイル時または構文エラーがソースやビルド出力にはっきりと示されている。
• コードを実行しなくても原因が明らかである（タイプミス、誤ったオーバーロード、明らかな null レシーバー、引数の数の誤り）。
• すべての状態がソースレベルで確認できる単一ファイルのロジックバグである。
• 失敗したテストのメッセージやログから、問題の行と値がすでに特定できている。

判別

コードベースのドメインにデバッグ関連の概念が含まれている場合、ユーザーが自分のコードについて話しているのか、実際にデバッガーの起動を求めているのかを明示的に判断してください。System.Diagnostics.Debug や Debug ビルド構成など、debug／Debugger と名付けられた識別子、機能、フラグ、ログカテゴリを、デフォルトでデバッガーの使用依頼と見なさないでください。

有効化の条件（ツールの利用可否）

このスキルは、現在のセッションでデバッガー MCP ツールを利用できる場合にのみ使ってください。最低限必要なツールは次のとおりです。

• xdebug_set_breakpoint
• xdebug_start_debugger_session
• xdebug_control_session
• xdebug_get_stack
• 少なくとも 1 つの値取得ツール：xdebug_get_frame_values、xdebug_get_value_by_path、または xdebug_evaluate_expression
• get_run_configurations

この最低限のツールセットが利用できない場合は、妨げとなっている要因を明示し、無理にデバッガーのワークフローを実行せず、最適な代替手段に切り替えてください。すべてのツールは reference/tools.md に記載されています。

デバッグ前の初期トリアージ

最小限の静的トリアージ（エラーテキスト、スタックトレース、周辺のソース）から始めてください。次のいずれかに該当する場合は、デバッガーでの調査を開始してください。静的解析では実行時の仮説を複数残してしまう場合、具体的な実行時の値や正確な制御フローが判断に必要な場合、大規模なファイル横断の経路を読むよりコードをステップ実行するほうが効率的な場合、またはユーザーがデバッガー操作を明示的に依頼した場合です。

新しい実行を開始する前に、現在の関連セッションを再利用できるかどうかを評価してください。最初のブレークポイントを早めに設定し、実行時の動作を変更する前に具体的な証拠を収集してください。

必須のランタイム証拠

デバッガーの証拠を取得できる場合、ランタイム動作に関する問題でコードを編集する前に、最低限、次の情報を収集してください。

• 中断中のセッションから取得した停止位置（ファイル／行番号）。
• xdebug_get_stack による呼び出し経路の先頭部分。
• 到達可能性が質問の一部である場合は、明示的に選択したブレークポイントまたはトレースポイントに実行が到達したかどうかを示す証拠。
• xdebug_get_frame_values、xdebug_get_value_by_path、または xdebug_evaluate_expression で取得した、具体的なランタイム値を少なくとも1つ。

明確な阻害要因をすでに示している場合を除き、これらの証拠を収集する前にランタイムについて結論を述べないでください。

再現モードの選択

1. AUTO：エージェントがシナリオを直接実行し、再実行できます（実行構成、テスト、実行可能ファイル、エンドポイント）。デバッグを有効にして起動するには xdebug_start_debugger_session を使用します。出力または終了コードだけが必要な非デバッグ実行には execute_run_configuration を使用します。
2. ASSISTED：再現にユーザーだけが実行できる操作（UI 操作、認証、外部依存関係、ハードウェアとのやり取り）が必要です。
3. HYBRID：まず AUTO を1～2回試し、失敗を再現できない場合は ASSISTED に切り替えます。

候補となる対象がテストの場合、既定では AUTO を使用します。ブレークポイントを設定する前に、ユーザーに再現を依頼してはいけません。

ユーザーの明示的な許可なしに、ユーザーのプロジェクト設定（NuGet パッケージ、ターゲットフレームワーク、.csproj／.sln、実行構成、環境、認証情報、サービス）を変更してはいけません。設定の変更が必要な場合は、阻害要因として提示し、ユーザーの許可を待ってください。1回限りの指示による許可は、その操作にのみ適用されます。

テストタスクの実行

• テストをデバッグするには、テスト定義（[Fact]／[Test]／[TestMethod] メソッドまたはケース）の --filePath と --line を指定します。IDE がフレームワーク（xUnit、NUnit、MSTest）を解決します。既存のテスト実行構成を使用する場合は、--configurationName を指定します。デバッグなしでテストを実行する場合（たとえば、ブレークポイントを設定する前に失敗を確認する場合）は、同じ対象を指定して execute_run_configuration を使用します。
• 実行を開始した後、execute_tool(command="xdebug_get_debugger_status") で状態を確認し、該当するセッションで続行します。
• 利用可能なテスト実行手段で再現できない場合、または再現にユーザーのみが実行できる設定が必要な場合を除き、手動で再実行するようユーザーに依頼してはいけません。

引数の適切な扱い

• オプションのパラメーターは省略するか、null にするか、実際の値を設定します。省略する場合は、省略したままにします。
• 省略するオプションのパラメーターを、""、"/"、"__omit__"、 "."、または架空のパスなどのプレースホルダー文字列で表してはいけません。
• ID とパスは、実行時データとしてそのまま扱います。生成せず、ツール出力からコピーしてください。

セッションのバインド

• ブレークポイントを設定したり起動したりする前に、execute_tool(command="xdebug_get_debugger_status") を呼び出します。
• 関連するアクティブなセッションがある場合は、新たに開始せず、そのセッション内で続行します。
• 正確な sessionId を取得し、セッションにスコープされたすべての呼び出しで再利用します。セッションが停止、タイムアウト、または消失した場合は、再利用する前に xdebug_get_debugger_status で状態を更新します。
• 停止位置が変わった後は、古い frameIndex や path を再利用しないでください。最新の xdebug_get_stack から読み直します。

実行構成の解決

• get_run_configurations から configurationName を解決します。supportsDynamicLaunchOverrides が --programArguments／--workingDirectory／--envs の指定可否を決定します（reference/tools/get_run_configurations.md を参照）。
• 自分で dotnet の呼び出しを組み立てたり、オーバーライドに対応していない構成で --programArguments を使ってテストフィルターを渡したりしてはいけません。実行構成を信頼し、再現性または可観測性を実質的に向上させる場合に限り、起動時のオーバーライドを使用してください。

ブレークポイントの所有権と管理

• 常に最初に execute_tool(command="xdebug_list_breakpoints") を実行し、返された owner（user / agent）を正として扱います。
• 何かを変更する前に、ベースラインのスナップショット（breakpointId -> enabled）を作成します。
• 現在の実行経路で不要な owner=user のブレークポイントは、execute_tool(command="xdebug_set_breakpoint --breakpointId <id> --enabled false") で一時的に無効化し、デバッガーサイクルの最後に一度だけ復元します。
• イテレーション間でブレークポイントを広範囲に変更しないでください。xdebug_remove_breakpoint のデフォルトは --owner agent です。すべてをクリーンアップするには、--owner agent、次に --owner user の順で2回呼び出します。

ブレークポイントの設定モード

xdebug_set_breakpoint には、相互に排他的な2つの設定モード（位置と breakpointId）があります。1回の呼び出しで混在させないでください。また、breakpointId モードでは、指定したフィールドが結果の状態になるため、望ましい状態をすべて渡してください。各呼び出しの後、返された lineText が意図した行と一致することを確認します。モードと完全な仕様については、reference/tools/xdebug_set_breakpoint.md を参照してください。

ライブラリと逆コンパイルされたソースのデバッグ

ライブラリやフレームワークのコードにもブレークポイントを設定できます。read_file は外部ソースファイルと、アセンブリ用の同梱された逆コンパイル出力（利用可能な場合は SourceLink / PDB で解決された元のソースも）を読み取ります。パスを取得するには、次の方法があります。

• スタックフレーム：xdebug_get_stack は、外部アセンブリ内のパスも含む file パスを返します。返されたパスをそのまま使用してください。
• シンボル検索：search_symbol(q="TypeName", include_external=true) は、外部 / ライブラリのシンボルパスを返します。

外部コードにブレークポイントを設定する前に、必ず read_file(file_path=<path>) で正確な行を確認してください。行番号を推測してはいけません。Console.WriteLine を挿入するためにソースを編集しないでください。代わりにトレースポイントを使用します。

エントリーポイントと最初のブレークポイントの選択

最初の実行前に、再現可能な最小範囲のエントリーポイント（単一のテスト、対象を絞った実行構成、エンドポイントハンドラー、コマンドハンドラー）と、不確実性が観測可能になる最も早い実行可能行（分岐判定、マッピング境界、状態遷移、動的ディスパッチ、例外の構築）にある最初のブレークポイントを明確に選択します。判断に迷う場合は、大まかなブレークポイントを最大2つ（エントリー境界に1つ、障害が疑われる境界に1つ）設定して一度実行し、その後、対象を絞り込みます。

基本ワークフロー

このチェックリストをコピーし、進行に合わせて項目にチェックを入れてください。

Debugger Run Progress:
- [ ] Scope the failure: exact error text, expected vs actual, 2-5 candidate anchors in the runtime path
- [ ] `xdebug_get_debugger_status` → reuse an active relevant session OR plan a new one
- [ ] Pick reproduction mode (AUTO / ASSISTED / HYBRID)
- [ ] Snapshot the breakpoint baseline; disable irrelevant user breakpoints
- [ ] Set initial breakpoints; verify `lineText` for each
- [ ] `xdebug_start_debugger_session ...` OR continue inside the existing session
- [ ] After a fresh start or RESUME: `xdebug_control_session --action WAIT_FOR_PAUSE`
- [ ] At each pause: `xdebug_get_stack` + values / eval (`xdebug_get_frame_values`, `xdebug_get_value_by_path`, `xdebug_evaluate_expression`)
- [ ] Decide next movement (`STEP_OVER` / `STEP_INTO` when evidence is nearby, OR a new breakpoint then `RESUME`)
- [ ] For tracepoints: `xdebug_control_session --action DRAIN_EVENTS`
- [ ] Stop on the first proven incorrect state transition or a stated blocker
- [ ] Wrap-up (cleanup + report)

各手順で守ること：

• 期待する次の停止位置を明確に指定せずに RESUME してはいけません。RESUME の後は必ず WAIT_FOR_PAUSE を実行します。
• 待機がタイムアウトした場合は、PAUSE して、有効なブレークポイントと想定される実行経路を再確認します。タイムアウトが2回連続したら、その待機の再試行をやめ、ブレークポイントの対象範囲を広げます。
• 具体的な実行時の値を確認せずに根本原因を断定してはいけません。また、それが立証される前に実行時の動作を変更してはいけません。
• 下流の症状だけで終わらせず、フレームをたどる / 巻き戻して状態を生成した箇所を特定します。必要な箇所をすでに通過している場合は、より前のブレークポイントから再起動します。
• フレームが外部コード / 逆コンパイルされたコードを示している場合は、read_file で読み取り、そこでさらに深いブレークポイントを設定します。飛ばしてはいけません。

イベントとトレースポイント

• breakpointErrorsTail / tracepointOutputsTail（xdebug_control_session。リファレンスを参照）は、JVM ベースのデバッガーでのみ値が設定されます。Rider のデバッガーは JVM ベースではないため、これらに依存しないでください。--condition は停止中のフレームで xdebug_evaluate_expression を使って事前に検証し、トレースポイントのログはプログラムの実行 / コンソール出力で確認してください。
• 停止させずにトレースポイント形式のログを記録するには、execute_tool(command="xdebug_set_breakpoint --filePath <path> --line <n> --isLogMessage true --suspendPolicy NONE")（または --isLogStack true）を使用します。

式の記述規則

xdebug_evaluate_expression と xdebug_set_variable は、現在のフレームの言語（C#、C++、F#、または VB）の式をそのまま受け取ります。入力規則の詳細は、それぞれのリファレンスファイルを参照してください。この仕様に加えて、次の点に注意してください。

• --condition と --expression では、グローバル／静的シンボルに完全修飾名を使うことを推奨します。デバッガーの式評価コンテキストでインポートが不足し、Unresolved reference が発生するのを防げます。
• ルーターは、外側の execute_tool(command=...) 行を ParametersListUtil で解析します。式に二重引用符が含まれる場合は、外側のコマンド文字列を単一引用符で囲みます。式に単一引用符が含まれる場合は、外側を二重引用符で囲みます。エスケープせずに両方を混在させないでください。
• 停止中の場合は、リスクのある --condition 式に頼る前に、xdebug_evaluate_expression で事前確認してください。

フレームをさかのぼる

フレーム内で停止したら、上位のフレームを調べてデータの流れを再構築します。現在の値を渡した呼び出し元と、状態が最初に誤ったものになった最も早い呼び出し元フレームを特定してください。必要な位置をすでに通過している場合は、より前のブレークポイント（AUTO）を設定して実行を再開するか、より前のブレークポイントを設定してユーザーに再現を依頼します（ASSISTED）。必要な証拠を得るにはすでに遅すぎる位置から、処理を続けないでください。フレームが外部コードや逆コンパイルされたコードを指している場合は、read_file で読み取り、必要に応じてその場所にもブレークポイントを設定して、データの流れをさらにさかのぼって追跡してください。

証拠の確認項目

結論を出す前に、次の内容を記録してください。正確な失敗メッセージ／本文、例外の種類および／またはステータスコード、状態が期待値から最初に逸脱した場所、問題のある具体的なキー／値（該当する場合は件数も）、誤ったデータの発生元／来歴、パイプラインがそれを許した理由。

まとめ

デバッグ後は、次の手順を実行してください。

1. クリーンアップします。execute_tool(command="xdebug_remove_breakpoint --owner agent") を実行し、無効化したユーザーのブレークポイントを元の状態に戻します。セッションが不要になった場合は、execute_tool(command="xdebug_control_session --action STOP") も実行します。
2. 次の内容を報告します。
   • 根本原因を1文で記述します。
   • 因果関係を3～6個の箇条書きで示します。
   • 実行時に確認した値を正確に記載します。
   • コード参照（絶対パスと行番号）を示します。
   • デバッグではなく別の方法に切り替えた場合は、その正確な理由と、まだ不足している証拠を示します。
3. 次のアクションはユーザーの目的に応じて決めます。診断のみを求められた場合は、報告と推奨する次のステップを提示して完了します。タスクにコード変更が含まれる場合は、根本原因を実証したうえで修正を実装します。

ツールリファレンス

13 個の xdebug_* MCP ツールに加えて、get_run_configurations／execute_run_configuration のシグネチャとパラメーターごとの注記については、reference/tools.md を参照してください。