runtime-evidence-debug

ランタイム証拠に基づくデバッグ

役割：ランタイムデバッグの方法論レイヤーです。静的解析からランタイム観察にいつ移行するか、またランタイム証拠をどのように収集、分析し、活用するかを示します。前提条件の確認後に呼び出される依存関係として、frontmatter の dependencies を通じて PDCA ホストから参照されます。ツールの選択は browser-debug-toolkit に、ドメイン分析は hybrid-debug に委任します。

reference.md には、フレームワークの詳細な項目（作成者、年、手法、出典）と計装用テンプレートが記載されています。

このスキルが必要な理由

コードを読む、呼び出しチェーンをたどる、ロジックを推論するといった静的コード解析には限界があります。次のことは観察できません。

• ランタイムのデータフロー：実行時に変数が実際にどの値を保持しているか
• 呼び出し順序：タイミングが重要な場合に、どの関数が先に実行されるか
• プラットフォーム／ホストによる介入：WebView、Electron、OS レベルの制御、フレームワークのランタイムが引き起こす、ソースコードからは見えない暗黙の動作変更

静的解析後も根本原因への確信が「曖昧」または「不明」な場合、同じコードをさらに注意深く読み直すのは、適切な対応ではありません。ランタイム証拠の収集に移行し、対象を絞った計装を追加して問題を再現し、実際の実行を観察し、推論したロジックではなく観察された事実に基づいて根本原因を特定します。

このスキルでは、その方法論を説明します。重要な教訓は次のとおりです。

ランタイム観察で確認された根本原因は、コードを読んで推論したものより、桁違いに信頼できます。確信が持てないときは、さらに深く推論するのではなく、証拠を集めてください。

使用するタイミング

次の強い兆候のうち、いずれか1つでも当てはまる場合に使用します。

• 静的解析後も根本原因への確信が低い — 原因と思われるモジュールは特定できても、具体的なロジックや発生経路を確認できません。
• 再試行のシナリオ — 静的解析に基づく修正を適用しても問題が解決しません。静的解析はすでに一度限界に達しているため、次のステップではランタイムデータを使う必要があります。
• サイレントな失敗 — 呼び出しチェーンは完全に見え、パラメーターも正しく、ログにも実行が記録されているのに、ランタイムの動作が間違っています。これは、ランタイム観察でしか明らかにできないプラットフォーム／ホストによる介入を示唆します。
• ランタイムで実際に何が起きているか観察するため、ログや計装（console.log、print、デバッガーのブレークポイント）を追加する必要がある場合。
• 修正の検証 — コードについて推論するだけでなく、修正前後の動作を比較して、修正が機能することを確認する必要がある場合。

他のスキルとの関係

スキル	担当範囲	このスキルとの関係
PDCA ホスト	ホストのワークフロー	frontmatter の dependencies を通じて PDCA ホストから参照されます（見つからない場合、ホストは中止します）。ホストの技術分析における計装ステップを、ランタイム証拠の観点から深掘りします。この依存関係の正式な情報源はホストです。
browser-debug-toolkit	ブラウザー DevTools のツール選択判断表	ブラウザーで再現可能な問題（典型例：UI／CSS／DOM）では、このスキルの計装ステップで参照します。ランタイム観察には、console.log より DevTools のライブインスペクションのほうが効率的です。
hybrid-debug	ハイブリッドアプリの4層デバッグモデル	このスキルは一般的なランタイム証拠の方法論です。hybrid-debug は、ネイティブアプリと Web アプリを組み合わせたアプリ向けに、4層モデルの中でこの方法論を適用します。ハイブリッドアプリの問題では、まず hybrid-debug を使って調査箇所を把握し、このスキルで各レイヤーの証拠の集め方を確認します。
debug-workflow（利用可能な場合）	体系的なデバッグプロトコル（根本原因の特定）	相互に補完します。debug-workflow がデバッグプロセス全体を進め、このスキルがその中のランタイム証拠収集フェーズを担います。
essence-diagnosis	証拠チェーンの構築と敵対的議論	ランタイム証拠だけでは不十分な問題では、複数の仮説に基づく証拠チェーンの検証を行うために essence-diagnosis に移行します。

証拠収集のライフサイクル

エスカレーションを判断する段階から修正を検証する段階までの7つのフェーズです。すべての問題に7つすべてが必要なわけではありませんが、フェーズを省略すると、確度の低い結論につながります。

フェーズ1 — エスカレーションの判断（静的解析からランタイム解析に移るタイミング）

フレームワーク：科学的デバッグ — Andreas Zeller、『Why Programs Fail』（2009年、第2版 2022年）。

ログを追加する前に、静的解析が本当に限界に達していることを確認してください。判断基準は、呼び出しチェーンをたどり、関連するコードを読んだ後に、根本原因を高い確度で述べられるかどうかです。述べられる場合、まだランタイムの証拠は必要ありません。確信度が「曖昧」または「不明」で、疑わしいモジュールは特定できても、正確なメカニズムを説明できない場合は、エスカレーションするタイミングです。

科学的方法を適用します。仮説（根本原因はXである）を立て、実験（Y地点に計測を追加してZを観察する）を設計し、結果を観察して、結論（Xを確認または反証する）を導きます。計測を追加する各ラウンドは、手当たり次第に探るのではなく、統制された実験です。

フェーズ2 — 計測の設計（的を絞ったログ記録）

フレームワーク：可観測性の3本柱（Charity Majors、『Observability Engineering』、2022年；Cindy Sridharan、『Distributed Systems Observability』、2018年）；構造化ログのベストプラクティス（OpenTelemetry のセマンティック規約）。

console.logをあちこちに追加するのではなく、計測ポイントを2～5か所設計します。各ポイントは、特定の仮説を検証するものにします。

• 関数の開始点／終了点：関数が呼び出されているか、またどのような引数で呼び出されているかを確認する
• 状態変更点：変数が誤った値にいつ、どのように変化するかを観察する
• データフローの接続点：データがモジュールやサービスの境界を越える際の流れを追跡する

適切な計測では、位置識別子（[DEBUG-<location>]）、主要な変数（すべての変数ではなく、仮説に関係するもの）、タイムスタンプを記録します。形式：console.log('[DEBUG-auth-check]', { userId, hasToken: !!token, timestamp: Date.now() })。

アンチパターン：「念のため」と、あらゆる場所にログを追加することです。こうするとノイズが増え、シグナルが埋もれてしまいます。すべてのログ記録ポイントは、何らかの仮説に対応していなければなりません。

ブラウザーで再現できる問題（典型的にはUI／CSS／DOMに関するもの）については、browser-debug-toolkitに委任してください。DevToolsでのライブ検査（DOM、計算済みスタイル、ボックスモデル、コンソール、ネットワーク）は、console.logより効率的です。

フェーズ3 — 再現方法の案内

フレームワーク：最小再現可能な例（MRE／MCVE、Stack Overflowの方法論；Benjamin C. Haller、『Ten Simple Rules for Reporting a Bug』、PLOS Computational Biology、2022年）；決定論的な再現（Google Testing Blog — 不安定なテストへの対策、Micco 2016）。

有用なランタイムの証拠を得るには、問題を再現可能にする必要があります。次の点をユーザーに案内します。

1. 再現手順：問題を引き起こす正確な手順（「ときどき発生する」ではなく、具体的な操作経路）
2. 環境：ブラウザーのバージョン、OS、デバイス、ネットワークの状態など、ランタイムの動作に影響する要素
3. 最小限の再現：再現に不要なものをすべて取り除き、問題を再現できる最小のケースにします。再現ケースが小さいほど、ログが明瞭になり、反復も速くなります。

問題が非決定的（断続的に発生する、タイミングに依存する）な場合は、発生頻度と発生条件を記録してください。非決定的なバグ（ハイゼンバグ — reference.mdを参照）には特別な対応が必要です。計測自体がタイミングを変え、バグを隠してしまうことがあります。

ツールの制約：AIは計測を設計し、再現方法を案内しますが、ログを追加して再現を実行するのはユーザーです（ユーザーがAIに実行を明示的に許可した場合を除きます）。ユーザーの確認なしに、再現手順を実行しないでください。

フェーズ 4 — 証拠の分析

フレームワーク：デバッグにおける証拠の階層。

ユーザーが実行時の出力を提示したら、証拠の階層を念頭に置いて分析します。

証拠の階層	強さ	例
階層 1 — 実行時の観察	最も強い	デバッガーのブレークポイントで変数の値を確認すること、DevTools で計算済みのスタイルを確認すること、プロファイラーでホットスポットを確認すること
階層 2 — ログ出力	強い	特定の引数で関数が呼び出されたことを確認する console.log の出力
階層 3 — コードからの推論	中程度	コードを読み、「この分岐は実行されるはずです。なぜなら……」と推論すること
階層 4 — 仮定／推測	弱い	「おそらくキャッシュが原因だと思います。なぜなら……」

階層 1〜2 の証拠に基づく根本原因は信頼できます。階層 3〜4 に基づく根本原因を確定するには、さらに計測して証拠の水準を高める必要があります。最も強い証拠が階層 3（コードからの推論）である場合、根本原因を「確認済み」と宣言しないでください。それは、実行時の装いをした静的分析にすぎません。

よくある誤診の落とし穴（最初の仮説に固執しない）

コードを読むと、もっともらしい仮説をひとつ立てて、それで終わりにしがちです。しかし、多くの症状には、ソースコードだけでは見分けのつかない原因がいくつもあります。計測計画を決める前に、以下の代替案を検討してください。

症状	おそらく最初に思いつく仮説	コードを読むだけでは見落としがちな代替案
メモリーリーク（RSS の増加）	イベントリスナーのクリーンアップ漏れ	大きなスコープを捕捉するクロージャー、無制限に増えるキャッシュ／Map、クリアされないタイマー、ストリームバッファー、ネイティブアドオンのリーク（Buffer／C++）、V8 の GC の遅延（そもそもリークではない）、接続プールに残ったままの接続
断続的なクラッシュ／500	競合状態	バースト時のプール枯渇、DB タイムアウト、ネットワークの瞬断、OOM キル、上流サービスの一時的な障害、接続リーク（リスナーリークとは別）
古い UI の描画	useEffect の依存関係の誤り	非同期処理の競合（古い Promise が最後に解決する）、useCallback 内の古いクロージャー、React.memo が古い props を保持する、並行レンダリング時のバッチ処理の違い、開発時に StrictMode が問題を見えにくくする
無言の失敗（エラーはないが動作が誤っている）	自分たちのコードのロジックバグ	プラットフォーム／ホストによる割り込み（WebView の癖、Electron IPC）、境界での型変換、シリアライズによるデータ損失（JSON.stringify が undefined／関数を除外する）、環境変数が読み込まれていない
パフォーマンスの低下	アルゴリズムの計算量	メモリー圧迫による GC の過剰な動作、隠れた N+1 クエリ、バンドルサイズの肥大化、ロック競合、キャッシュ無効化の集中

原則：計測がひとつの仮説しか検証していない場合、その仮説が裏付けられても、代替原因を排除できたわけではありません。最初の仮説を裏付けるだけでなく、上位 2〜3 個の候補を否定できるように計測を設計してください。

フェーズ 5 — 確信度による判断

フレームワーク：デバッグにベイズ推論を適用する（事前の確信度 + 新たな証拠 → 事後の確信度）。

実行時の証拠を分析した後、確信度を調整します。

• 高：実行時の証拠によって仕組みが直接確認されています（例：ログで、本来オブジェクトであるはずの変数が null と示されている。デバッガーで誤った分岐が実行されていると確認できる）。→ 修正に進んでも問題ありません。
• 中：実行時の証拠によって範囲は絞れていますが、仕組みをひとつに特定できていません。→ もう一度、対象を絞って計測するか、不確実性を明示したうえで進めます。
• 低／不明瞭：実行時の証拠では仕組みが明らかになっていません。ログでは期待どおりの動作が示されているのに、問題が続いています。→ 修正に進まないでください。エスケープハッチ（フェーズ 6）に進んでください。

デバッグで最もコストの高い誤り：確信度が低いまま作業に着手し（修正を書くこと）、実行に移すことです。最初の試みは、最終的に捨てられる表面的なパッチになります。確信度が低いときに取るべき慎重な対応は、推測に頼って期待をかけることではなく、証拠を集め続けることです。

修正準備ゲート — 修正を書く前に、3つの条件がすべて満たされていること

コード変更を提案または適用する前に、3つすべてを確認してください。1つでも満たされていない場合は、修正の準備ができていません。計測に戻ってください。

1. 推測ではなく、実行時の証拠を使って次の文を完成できること：「根本原因が X だと確信しています。なぜなら、［具体的な実行時の観察結果：ログ行／デバッガーの値／プロファイラーの出力に Y と示されている］からです。」— 「おそらく X だと思います」や「コードを見ると X のようです」としか言えない場合は、まだ準備ができていません。
2. 少なくとも1つの別の仮説を反証していること — 自分の本命の仮説を確認しただけでは不十分です。上記の「よくある誤診の落とし穴」テーブルには、症状の種類ごとの別の仮説が記載されています。計測によって、そのうち少なくとも1つを除外できている必要があります。
3. 修正の検証方法がわかっていること — 修正後に動作が変わったことを確認するため、再実行する再現手順があること（フェーズ 7）。修正前に検証方法を説明できない場合は、まだ準備ができていません。

このゲートは、このスキルにおいて最も効果の高い規律です。デバッグに費やす時間の大半は、このゲートを省略し、ティア 3 の証拠だけで修正を書き、それが機能しないのを確認して、同じことを繰り返すことで無駄になります。

フェーズ 6 — 逃げ道（実行時にレイヤーへ到達できない場合）

フレームワーク：git bisect（コミット履歴の二分探索）、既知のプラットフォーム／フレームワークの問題に関するウェブ調査。

実行時の計測にも限界があります。コード層の実行経路は観察できますが、プラットフォーム／ホスト層でのサイレントな介入（WebView の prefers-color-scheme に関する問題、Electron IPC のシリアライズ、OS レベルの制御）には踏み込めません。ログ上はコードが正しく実行されているのに、動作が依然として正しくない場合は、次の手順に進んでください。

1. Git bisect：問題がリグレッションであれば、コミット履歴を二分探索して、問題を引き起こしたコミットを特定します（git bisect start → git bisect bad → git bisect good <commit> → 各中間コミットをテスト）。これにより、原因を特定の差分に絞り込めます。
2. ウェブ調査：症状に一致する既知のプラットフォーム／フレームワークの問題を検索します（症状のキーワード + プラットフォーム／フレームワーク + 年）。effective-web-research スキルを利用できる場合は、その手順に従ってください。
3. ドメインの専門家にエスカレーションする：ハイブリッドアプリの場合は、hybrid-debug（4層モデル）にエスカレーションしてください。証拠チェーンによる複数仮説の検証の場合は、essence-diagnosis にエスカレーションしてください。

フェーズ 7 — 修正の検証

フレームワーク：修正前後の比較、回帰テスト（Kent Beck、『Test-Driven Development』、2002 年）、責任を問わない事後検証（Google SRE、『Site Reliability Engineering』、2016 年）。

修正を適用した後は、修正後のコードを読むだけでなく、実行時の証拠を使って検証します。

1. 修正前後の比較：フェーズ 3 で使用したものと同じ再現手順および環境で問題を再現します。修正前と修正後の実行時の挙動を比較します。以前に確認された誤った挙動が正しくなった場合にのみ、修正が確認されたことになります。
2. 回帰の確認：修正によって他の挙動が壊れていないことを検証します。テストスイートを実行し、変更したロジックを共有する隣接するコードパスを確認します。
3. ハイゼンバグへの注意 — 修正そのものがタイミングへの介入です：タイミングに左右されるバグ（競合状態、デッドロック、UI のちらつき）では、計測と修正のどちらも、バグを隠してしまうほどタイミングを変える可能性があります。ミューテックスロックは console.log よりも侵襲的で、スレッドの実行順序を根本的に変えます。async/await のリファクタリングはマイクロタスクのスケジューリングを変えます。debounce はイベントのタイミングを変えます。以下を検証してください。
   • デバッグログを一切有効にせず、リリース版または本番環境相当のビルドで修正が機能すること
   • 修正が複数回の実行に耐えること（競合状態では 10 回以上、断続的に発生する UI のバグでは 50 回以上）。手動テストを 1 回行うだけでは不十分です。
   • 修正によって新たなタイミングの問題が発生しないこと（ロック順序によるデッドロック、直列化によるスループットの崩壊、ミューテックスの保持時間による飢餓状態） タイミングへの副作用によって別の競合状態がたまたま隠れたために「機能する」修正は、本当の修正ではなく、時限爆弾です。
4. クリーンアップ：一時的な計測を削除します。どのログ出力箇所を恒久的なモニタリングに移す価値があるかを特定します。

アンチパターン（禁止される行為）

1. エスカレーションせずにコードを読み直す — 静的解析ですでに一度失敗しているのに、さらに念入りに同じことをしても、同じ結果になります。実行時の証拠へとエスカレーションしてください。
2. 手当たり次第の計測 — 「念のため」に console.log をあちこちに追加することです。すべてのログ出力箇所は、仮説に対応していなければなりません。
3. コードの推論から根本原因を断定する — 「コードに X と書いてあるので、実行時も X になるはず」は Tier 3 の証拠であり、確認ではありません。高い確度を得るには、実行時の観察（Tier 1～2）が必要です。
4. 確度が低いまま行動する — 確度がまだ「曖昧」な状態で実行に移り（修正を書く）、修正を破棄される最初の試みの一つにしてしまうことです。
5. ハイゼンバグを無視する — ログを追加するとバグが再現するかどうかが変わる場合は、タイミングまたは並行処理の問題です。計測に依存する修正で解決を宣言してはいけません。
6. 修正の検証を省略する — 「コードの変更は正しそうだ」は検証ではありません。同じ手順で再現し、挙動が変わったことを確認してください。
7. ユーザーの許可なく再現を実行する — ユーザーが計測を追加し、再現手順を実行する必要があります（AI に明示的に委任した場合を除きます）。