hybrid-debug

ハイブリッドフルスタックデバッグ

役割：ハイブリッドアプリ（ネイティブシェル＋埋め込みWeb）のデバッグ向けに、4層分析モデルとドメインナレッジベースを提供します。これは方法論とナレッジの強化であり、単独で完結するエンドツーエンドのワークフローではありません。PDCAホストがフロントマターの dependencies を介して参照し（前提条件の確認後に呼び出されます）、実行時の検証は browser-debug-toolkit に委任します。

ドメインナレッジ（技術的な落とし穴、ネイティブ↔H5の契約テンプレート、アンカー付き事例）は reference.md にあります。

このスキルが存在する理由

ハイブリッドアプリには、レイヤー間のギャップを見落とす問題があります。フロントエンドのみを担当するエンジニアはH5レイヤー（CSS/JS）だけを調べる傾向があり、ネイティブのみを担当するエンジニアはネイティブコードだけを調べる傾向があります。プラットフォームランタイム層（WebViewの prefers-color-scheme、WKWebViewのジェスチャー処理、Electron IPC）は、どちらの側も詳しく把握していないグレーゾーンです。

その結果、問題が解決しないまま何度も「修正」されたり、ある要素を修正しても、同じ隠れたバグが兄弟要素に広がったり、一時しのぎの修正によって新たなクロスプラットフォームの不整合が生じたりします。このスキルが徹底させるべき本質的な教訓は次のとおりです。

ハイブリッドアプリでは、根本的な修正を見つけるために、ネイティブ／Web／プラットフォームランタイムという全チェーンにわたって分析する必要があります。単一レイヤーの分析では、場当たり的な修正を繰り返すことになります。

使用するタイミング

次の強い兆候のうち、どれか1つでも当てはまれば使用してください。

• ハイブリッドアプリ（WebView／WKWebView／Electron／React Native＋H5）で、UI、テーマ、または動作の問題が発生している。
• プラットフォーム間の差異 — Androidでは問題が再現するがiOSでは再現しない（またはその逆）、あるいはあるバージョンのElectronでは再現するが、別のバージョンでは再現しない。これは最も強い兆候です。プラットフォームの差異はほぼ必ずL2/L3/L4（ブリッジ／ネイティブ設定／プラットフォームランタイム）に起因し、L1に起因することはありません（H5コードはプラットフォーム間で共有されており、それ単体ではプラットフォーム間の差異を生み出せません）。
• 片側だけで修正を試みたものの問題が再発した、または同じ根本原因を持つ兄弟要素を見落とした。
• サイレントな失敗：呼び出しチェーンは完全に見え、パラメーターも正しく、ログにも実行が記録されているにもかかわらず、実行時の動作が誤っている。これはプラットフォームランタイムによる割り込み（L4）または不完全なネイティブ↔H5間の契約（L2）を示しています。

他のスキルとの関係

スキル	担当範囲	このスキルとの関係
PDCAホスト	ワークフローのホスト	フロントマターの dependencies を介してPDCAホストから参照されます（不足している場合、ホストは中止します）。PDCAホストの技術分析フェーズを、ハイブリッドアプリ向けに詳しく掘り下げます。この依存関係の情報源はホストです。
browser-debug-toolkit	ブラウザーDevToolsのツール選択判断表	このスキルの実行時の証拠のステップでは、これに処理を委任します。4層分析によって何を検証すべきかが分かり、browser-debug-toolkit によってどのツールで検証すべきかが分かります。
essence-diagnosis	一般的な本質診断（SOAP＋複数仮説＋反証的な議論）	4層分析後もハイブリッドアプリの問題が不明瞭な場合は、essence-diagnosis に引き継ぎ、複数の仮説を用いた綿密な検証を行います。
android-webview-debug	Android WebViewのリモートデバッグを有効／無効にする	前提となる手順であることがよくあります。Android WebViewのリモートデバッグを有効にして、このスキルの実行時証拠のステップでchrome-devtoolsによる検査を行えるようにします。

4 層モデル

あらゆるハイブリッド環境の問題は、次の 4 層のどこに位置するかを特定して分析します。各層は、症状が現れる場所（L1）から、根本原因が隠れていることの多い場所（L4）へと並んでいます。

層	対象	典型的な兆候
L1 — Web ランタイム	H5 のコードロジック、CSS ルール、DOM 構造、JS の状態	症状がここで確認できます（色が違う、クラスがない、レイアウトが崩れているなど）。問題が現れる場所ですが、問題が始まる場所であることはほとんどありません。
L2 — ネイティブ↔Web ブリッジ	ネイティブから H5 への通知方法（属性の注入、クラスの切り替え、JS API 呼び出し）、注入される内容、タイミングや順序	setAttribute('data-theme','dark') が呼び出されてもクラスが変わらない、DOM の準備が整う前に evaluateJavascript が呼び出される、ネイティブが設定した状態を H5 が読み取らない。
L3 — ネイティブ設定	Activity／テーマの設定、WebView 設定（forceDarkAllowed、algorithmicDarkening）、Manifest、Info.plist	Activity が Light テーマに固定されている、forceDarkAllowed=false、WebView のダークモード設定が H5 の前提と矛盾している。
L4 — プラットフォームランタイム	デスクトップブラウザーと異なる、プラットフォーム固有の WebView／WKWebView／Electron の動作	Android WebView の prefers-color-scheme はシステムのダークモードではなく isLightTheme に従う、WKWebView のジェスチャーに関する癖、Electron の IPC シリアル化の制限。

最も重要な原則：L1 で調査を止めない

L1 で原因を見つけることは、終点ではなく出発点です。L1 の原因を特定した後は、必ず「なぜ L1 の状態がこのようになっているのか？」と問いかけ、根本原因への確信が高まるまで L2 → L3／L4 へとたどります。

L1 で調査を止めることは、ハイブリッド環境のデバッグで最もよくある失敗です。典型的な落とし穴は、L1 で --color-canvas-subtle が明るい値に解決されているのを見て、それを使う要素に修正を加えることです。しかし、「このプラットフォームでは、なぜこの変数が明るい値に解決されるのか？」という、さらに深い問いを突き詰めれば、L3／L4 に行き着き、1 つの要素だけでなく、同じ変数を使うすべての要素に適用される修正を見つけられます。

プラットフォーム間の差異は、チェーン全体を調査すべきという兆候です

プラットフォーム A では問題が再現し、プラットフォーム B では再現しない場合、プラットフォーム A だけを分析してはいけません。差異は L2／L3／L4 に起因します。両方のプラットフォームで、ブリッジの経路、ネイティブ設定、プラットフォームランタイムの動作を比較してください。L1 の H5 コードは共通のため、それだけではプラットフォーム間の差異を説明できません。

例：iOS では setTheme('dark') が呼び出されて H5 のクラスが切り替わり、WKWebView の prefers-color-scheme はシステムに従います。Android では setAttribute('data-theme','dark') が呼び出されてもクラスは変わらず、WebView の prefers-color-scheme は明るい状態のままです。この差異の原因は L2（ブリッジの仕組み）と L4（プラットフォームランタイム）にあり、L1 にはありません。

調査フロー

1. 症状が現れているレイヤーを特定する（通常は L1）。目に見える誤った動作と、それを引き起こしている正確な CSS／DOM／状態を確認します。
2. 「なぜ L1 はこの状態なのか？」と問いかけ、L2 → L3/L4 へとたどります。まだ修正案は出さないでください。このステップの目標は、根本原因への確信度を高にすることです。
3. 既知の落とし穴と照合する。 reference.md を参照してください。5 つの技術的な落とし穴は、よくあるハイブリッド環境の罠（プラットフォームの prefers-color-scheme の癖、二重のテーマ変数システム、不完全なネイティブ↔H5 間の契約、CSS の同じ詳細度におけるソース順、開発時とビルド時の CSS 処理の違い）を網羅しています。既知の落とし穴に当てはまる場合は、それによって根本原因を手早く確認できます。
4. 実行時の証拠で根本原因を裏付ける。 CSS 変数の解決、ルールの優先順位、プラットフォームのメディアクエリの戻り値は、実行時にしか観測できません。静的なコードの読み取りでは誤った判断につながります。ツールの選定は browser-debug-toolkit に委ねてください。「ルールを一つずつ無効にする」手法で適用されるルールを見つけ、プラットフォーム環境（モバイル UA + prefers-color-scheme + 注入されたクラス）をエミュレートしてデバイスの動作を再現し、スクリーンショットのピクセルサンプリングで実際にレンダリングされた色を確認します。
5. 同じ根本原因を持つ要素を調べる。 根本原因がわかったら、それを共有するすべての要素／シナリオを見つけます（例：同じ壊れた CSS 変数を使用するすべての要素）。一つだけ修正して残りを見落とすと、必ず再発します。
6. 修正を選ぶ前に、レイヤーをまたぐ副作用を評価する。 次の点を確認してください。この修正によって、別のレイヤーの既存の動作が変わりませんか？（H5 のみのパッチは iOS の既存の見た目を変える可能性があり、ネイティブのみのパッチは Web のみのコードパスを壊す可能性があります。）新たな不整合を生じさせずに、影響を受けるすべてのレイヤーで根本原因に対処する必要があります。
7. 根本原因への確信度を基準に進める。 ステップ 2 の後も確信度が曖昧または不明な場合は、修正に飛びつかないでください。調査を続けるか、実行時の計測にエスカレーションします。根本原因への確信が低いまま実行に移ると、最初の試みが表面的なパッチとして捨てられることになります。

ステップ 4～7 の一般的な原則（実行時の証拠、同じ根本原因を持つ要素の調査、副作用の評価、確信度に基づく判断）は、runtime-evidence-debug スキル（solve-workflow の dependencies エントリでもあります）によって提供されます。このスキルは、これらを4 層モデルの中でどう適用するかに焦点を当てています。単独で使用する場合は、ワークフロー全体がなくても、これらの原則に沿ってください。

アンチパターン（禁止事項）

次に挙げるのは、いたちごっこのような修正を招く行動です。見つけたら避けてください。

1. L1 で止まる — Web レイヤーの原因を見つけても、なぜ L1 がその状態なのかを問わずに修正すること。修正が繰り返し失敗する最大の原因です。
2. プラットフォーム間の差異の問題を片方だけで分析する — 差異は L2/L3/L4 にあります。片方だけを分析しても、見るべき場所を間違えています。
3. ソースを読んで CSS ルールの優先順位を推測する — カスケードと変数の解決は実行時の動作です。必ず DevTools で検証してください。
4. 関連要素を調べず一点だけを修正する — pre を修正して、同じ壊れた変数を共有する thead／kbd／code を見落とすこと。
5. レイヤーをまたぐ副作用を評価せずに修正を選ぶ — H5 のパッチによって、別のプラットフォームの既存の見た目が気づかないうちに変わること。
6. 根本原因への確信が低いまま実行に移る — 「おそらくこれだ」という判断は、最初の試みを無駄にし、サイクルを浪費します。
7. 「防御的フォールバック」で自己正当化する — 精査に耐えない「後方互換性」という理由をでっち上げて、表面的だとわかっている修正を残すこと。不完全な修正は、修正しない場合よりも混乱を招きます。

ドメイン知識リファレンス

このファイルを簡潔に保つため、以下はreference.mdに記載しています。

• 5つの技術的な落とし穴 — Android WebView の prefers-color-scheme の挙動、2つのテーマ変数システムの競合、不完全なネイティブ↔H5 テーマ同期契約、CSS の同一詳細度におけるソース順序の落とし穴、開発時とビルド時の CSS 処理の相違。それぞれの挙動、公式な根拠、回避方法。
• ネイティブ↔H5 通信契約のテンプレート — 状態変更を H5 に通知する際、ネイティブ側が同期を保つ必要がある3つの要素（クラス、属性、永続ストレージ）と、直接 DOM を操作するよりも H5 が公開する統一 API が優れている理由。
• 根拠に基づく事例の概要 — 4層モデル全体を示す、サニタイズ済みの参照事例（あるプラットフォームでダークモード時にコードブロックの背景色がテーマに追従しない問題）。L1 のみに対処した最初の試みが失敗したことと、チェーン全体を修正して成功した原因修正を含みます。