browser-debug-toolkit

ブラウザー実行時デバッグツールキット

概要

UI／CSS／DOM のレイアウトの問題は、多くの場合、実行時にのみ表面化する根本原因があります。たとえば、動的に生成される DOM 構造、CSS の詳細度の競合、レイアウト計算の異常などです。静的コード分析（Read／Grep）やコンソールベースのデバッグ（console.log）には、レンダリングされた DOM ツリー、計算済み CSS プロパティ、ボックスモデルのジオメトリを確認できないという根本的な制約があります。

このスキルでは、状況に応じたツールの選択表と、各ツールの使用ガイドを提供します。frontmatter の dependencies を介して PDCA ホストから参照されます（ブラウザーで再現可能なシナリオが検出された場合、前提条件の確認後に呼び出されます）。この依存関係の管理元はホストです。

前提条件

ステップ 1：MCP の利用可否を確認する

ブラウザーデバッグツールを使う前に、chrome-devtools-mcp（chrome-devtools-connect と呼ばれる場合もあります）が利用可能か確認します。

プラットフォーム	確認方法
Claude Code	claude mcp list を実行し、「chrome-devtools」を探します
OpenCode	利用可能なツールを確認するか、cat ~/.config/opencode/opencode.json を実行します
Cursor	Settings → MCP → サーバー一覧を確認します

ステップ 2：MCP が見つからない場合 — 選択肢を提示する

chrome-devtools-mcp が利用できない場合、ユーザーに次の 3 つの選択肢を提示します。

オプション A：自動インストール（推奨）

AI が検出したプラットフォームに応じて、インストールコマンドを直接実行します。

プラットフォーム	インストールコマンド
Claude Code	claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
OpenCode	~/.config/opencode/opencode.json に MCP 設定を追加します
Cursor	公式 README の「Install in Cursor」ボタンを使用するか、MCP 設定に手動で追加します

インストール後、AI ツールを再起動して MCP サーバーを読み込みます。

オプション B：手動インストール

ユーザーがコピーして自分で実行できるよう、正確なコマンド（オプション A と同じ）を提示します。続行する前にユーザーの確認を待ちます。

オプション C：スキップ — DevTools を手動で使用する

代替手段として、ブラウザーの DevTools を手動で開き（F12）、要素を自分で調査するようユーザーを案内します。MCP より時間がかかりますが、セットアップは不要です。

ステップ 3：環境の前提条件

• Node.js LTS ＋ npm（chrome-devtools-mcp が必要とします）
• Chrome ブラウザー（安定版。Google Chrome または Chrome for Testing）

ステップ 4：インストールを確認する

インストールまたは有効化の後、MCP が読み込まれていることを確認します。

プラットフォーム	確認方法
Claude Code	claude mcp list に chrome-devtools が表示されます
OpenCode	設定ファイルに chrome-devtools のエントリが含まれています
Cursor	Settings → MCP にサーバーが緑色のステータスで表示されます

シーン別ツール選択表

問題のシーン	デフォルト：ego-browser	フォールバック：chrome-devtools-mcp	フォールバック：web-access CDP Proxy	主な機能
DOM 構造の異常（要素が欠落している／誤っている）	snapshotText() a11y ツリー + js() DOM ウォーク	Elements パネル	/eval で DOM を読み取り	ライブ DOM ツリー、要素の選択、属性の検査
CSS が適用されない／詳細度の競合	js() で getComputedStyle を取得 + オーバーライドチェーンをたどる	Elements → Styles	/eval で getComputedStyle を取得	計算済みスタイル、オーバーライドチェーン、ボックスモデル
レイアウトシフト／ボックスモデルの異常	js() で getBoundingClientRect を取得 + 祖先をたどる	Computed / Layout パネル	/eval で getBoundingClientRect を取得	ボックスモデルの可視化、Flex／Grid ガイド
インタラクションの異常（クリックに反応しない）	click(@N) + js() でリスナー／状態を確認 + cdp() Console	Console + Event Listeners	/click と /clickAt の実際のジェスチャーを比較	イベントリスナーの検査、JS ランタイムエラー
ログイン画面／CAPTCHA によるデバッグ中断	handOffTaskSpace → ユーザーが操作 → takeOverTaskSpace (独自)	—	—	デバッグ中の人間と AI のアトミックな引き継ぎ。エージェントとユーザーが 1 つのブラウザーを共有し、操作権を奪い合わずに利用
セレクターが不安定な UI（Canvas／仮想化リスト／頻繁に再スタイルされるページ）	snapshotText() の @N 参照 + ビジュアルモード（スクリーンショット + 座標）	—（macOS 以外：playwright-mcp a11y スナップショット）	—	a11y ツリーの参照は CSS／マークアップの変更後も維持されます。変更後にスナップショットを再取得
ログイン状態と完全な CDP ドメインが同時に必要（例：ログイン後のネットワークウォーターフォール）	ログイン済みタスクスペースで cdp('Network.*')	既存のログイン済み Chrome に接続	/eval は読み取りのみ。完全なドメインには非対応	ログイン状態を引き継いだ CDP の生データパススルー
レンダリング性能（ジャンク／フレーム落ち）	cdp('Performance.*') の生トレース	Performance パネル（専用機能のため、性能調査に推奨）	—	フレームチャート、Long Tasks、レンダリング統計。perf-optimize-workflow と併用
ビジュアルリグレッション（スタイルの上書き）	captureScreenshot() で変更前後を比較	—	/screenshot で変更前後を比較	スクリーンショットの比較。visual-qa スキルと併用
非同期読み込み／ネットワークの問題	cdp('Network.*') + drainEvents()	Network パネル	—	リクエスト／レスポンス、ウォーターフォール、ステータスコード
状態管理の異常（React／Vue）	js() でストア／コンポーネントの状態を検査	React／Vue DevTools（ユーザーが操作する拡張機能）	—	コンポーネントツリー、props／state、タイムトラベル

デフォルトのチャネル：ego-browser（外部スキル、macOS のみ）— まずランタイムで利用可能か確認してください。これはランタイムローカルの依存関係であり、frontmatter の dependencies には宣言されていないため、solve-workflow などの上流ワークフローに外部プラグインの要件が生じることはありません。ego-browser が利用できない場合（未インストール／macOS 以外）、またはタスクの途中で失敗した場合（エラー、ページにアクセスできない、必要な操作に対して生の cdp() の粒度が低すぎる）は、以下のチェーンに沿って切り替え、現在使用しているチャネルをユーザーに伝えてください。黙ってフォールバックしてはいけません。フォールバック列に示されているのは chrome-devtools-mcp（MCP サーバー。Prerequisites を参照）と、外部 web-access スキルの CDP Proxy です（同じ弱参照のルールが適用されます。利用可能か確認し、見つからない場合はインストール方法を案内して中止してください）。ego-browser の行に対する macOS 以外での代替手段：playwright-mcp（MCP、a11y ツリーのスナップショット）→ agent-browser（CLI）。

ツールの使用ガイド

chrome-devtools-mcp（MCP サーバー）

種類：MCP サーバー（Chrome DevTools Protocol）／利用可能性：環境に依存します（前提条件を参照）

使用する場面：ページの DOM、CSS、ネットワーク、コンソールをリアルタイムで調査します。AI が手動でコンテキストを切り替えることなく、DevTools を直接操作できます。

主な機能：DOM の調査（querySelector、計算済みスタイル、要素の属性）、CSS のデバッグ（一致するルール、上書きの連鎖、ボックスモデル）、コンソール（JS の実行、出力の読み取り）、ネットワーク（リクエスト／レスポンスの調査）、スクリーンショット（ページまたは要素のキャプチャ）。

使用パターン：MCP が利用可能な場合は、ワークフローの分析段階でブラウザーに接続し、問題を再現して実行時の状態（DOM 構造、計算済みスタイル、コンソール、ネットワーク）を調査します。次に、期待値と実際の値を比較して根本原因を特定します。検証段階では、修正が機能することを確認します。

注：MCP がインストールされていない場合は、適応的なセットアップ方法（自動インストール／手動／スキップ）について、上記の前提条件セクションを参照してください。

playwright / webapp-testing（スキル）

種類：スキル（ブラウザー自動化）／利用可能性：OpenCode 組み込みの playwright、ユーザースキルの webapp-testing

使用する場面：操作（クリック、入力、ページ移動）の自動再現、スクリーンショットの比較、エンドツーエンド検証。

chrome-devtools-mcp との違い：Playwright は自動操作（スクリプト駆動の一括検証）を重視し、chrome-devtools-mcp はリアルタイム調査（対話型デバッグ、即時フィードバック）を重視します。

visual-qa（スキル）

種類：スキル（ビジュアル品質保証）／利用可能性：共有／opencode スキル

使用する場面：スクリーンショットの比較、デザインレビュー、視覚的なリグレッションの検証。特に修正前後の比較シナリオに適しています。

フレームワーク DevTools（ブラウザー拡張機能）

フレームワーク	DevTools	主な機能
React	React DevTools	コンポーネントツリー、props／state、Profiler のタイムライン
Vue	Vue DevTools	コンポーネントツリー、Vuex／Pinia の状態、ルーティング
Angular	Angular DevTools	コンポーネントツリー、変更検知、Signal の依存関係グラフ

フレームワーク DevTools は、AI が直接操作できないブラウザー拡張機能です。ユーザーにインストールを案内し、手動で調査してもらってください。

3つのチャネル、3つの使い方 — シグナルに応じて選ぶ

習慣ではなく、デバッグセッションで必要なことに応じてチャネルを選んでください。基本的な操作（クリック／入力／評価／スクリーンショット）は共通していますが、使い方には大きな違いがあります。

項目	chrome-devtools-mcp	web-access CDP Proxy	ego-browser (macOS)
使い方	検査（DevTools パネル：Elements／Network／Performance）	軽量な操作＋確認（ページを操作し、状態を取得）	フルコントロール＋raw CDP＋人間とAIの引き継ぎ
ログイン状態	デフォルトでは新規セッション。既存の Chrome に接続することも可能	ユーザーが普段使っているブラウザーに接続 — ログイン状態をそのまま利用	ユーザーのブラウザーから継承 — ログイン状態をそのまま利用
要素の指定	CSS／テキストクエリ	/eval 経由の CSS	snapshotText() の a11y 参照（@N）＋ CSS ＋ xpath ＋座標
CDP の全ドメイン（Network／Performance／Console）	✅ パネル経由で利用可能	❌（プロキシの一部機能：eval／クリック／スクロール／スクリーンショット）	✅ cdp() による raw パススルー
デバッグ中の人間とAIの引き継ぎ	❌	❌	✅ handOffTaskSpace ／ takeOverTaskSpace
ブラウザーの分離	独立した新規インスタンス	ユーザーのブラウザーを共有（バックグラウンドタブ、並列実行に対応）	分離された Task Space — ユーザーのタブには一切影響しません
スクリプトの使い方	MCP ツール（対話型）	curl HTTP API（バッチ、並列エージェント）	heredoc JS バッチ（1回のラウンドで複数ステップ）
プラットフォーム	クロスプラットフォーム（Chrome 系）	クロスプラットフォーム	macOS のみ

デフォルト：まず ego-browser。 すべてのブラウザーデバッグ／操作セッションは、ego-browser チャネルから開始してください（最初にランタイムで利用可能か確認します）。フルインタラクション＋ページ JS＋raw CDP＋継承したログイン状態＋分離されたタスクスペース＋人間とAIの引き継ぎを一通り備えているのはこのチャネルだけなので、観察 → 再現 → 検証の一連のループを1つのチャネルでカバーできます。次の場合に限り、利用できない（未インストール／macOS 以外）または目の前の要件に対して機能しない場合に、別のチャネルに切り替えてください。

ego-browser (macOS, default — runtime-checked)
  ├─ unavailable or failed?
  │   ├─ non-macOS → playwright-mcp (MCP, a11y snapshots) → agent-browser (CLI)
  │   ├─ need purpose-built panels (perf trace / network waterfall / computed style),
  │   │  where raw cdp() is too low-level or fails → chrome-devtools-mcp
  │   ├─ need lightweight login-state control or curl-parallel sub-agents → web-access CDP Proxy
  │   └─ nothing available → guide user to manual DevTools (F12)
  └─ still tell the user which channel you are on (never silently fall back)

ego-browser が利用可能でも、フォールバックのほうを最初に選ぶのが適切な専門的な例外が2つあります。パフォーマンストレース（chrome-devtools-mcp の専用 Performance ツールは raw cdp('Performance.*') より適しています）と、無人の CI 回帰テスト（CI にはユーザーのブラウザーが存在しないため、Playwright／webapp-testing を使用します）です。情報検索のみ（検索／スクレイピング／スクレイピング対策プラットフォーム）はデバッグタスクではありません。その用途にはこのスキルではなく、effective-web-research ＋ web-access を使用してください。

web-access の curl API チートシート、ego-browser の heredoc レシピ、およびチャネルごとのデバッグレシピについては、reference.md を参照してください。

ワークフローとの統合

PDCA ホストから frontmatter の dependencies を介して参照されます（依存関係が見つからない場合、ホストは中断します）。また、環境の機能を調査する debug-workflow などのワークフロースキルからも検出されます。ハイブリッドアプリ（WebView／WKWebView／Electron ＋ H5）のデバッグにおけるランタイムの証拠収集は hybrid-debug から、一般的なデバッグにおける UI／CSS／DOM の計測は runtime-evidence-debug から委任されます。

1. 分析段階：ブラウザーで再現できる問題（典型的な例は UI／CSS／DOM）→ ブラウザーツールを優先して問題を再現し、ランタイムの状態を調査します
2. console.log によるデバッグの前に：UI の問題は、まずブラウザーの DevTools で調査します（console.log より効率的です）。それでも解決しない場合は、ログ出力に切り替えます
3. 検証段階：修正後、ブラウザーツールを使って修正が機能することを検証します（修正前後のランタイム状態を比較）

段階的な機能強化：このスキルはホストワークフローの中核となるプロセスを置き換えるものではありません。強い依存関係として読み込まれる場合、ホストの前提条件チェックにより利用が保証されます。他のワークフロー（例：debug-workflow）では、ブラウザーツールを利用できない場合も、元のプロセスが変更されずに実行されます。

クイックリファレンス

Scene detection: Can this problem be reproduced in a browser? (UI/CSS/DOM issues are the typical scenes)
Signal keywords: style, layout, render, display, visibility, position, size, color, animation
→ Yes → Prioritize browser tools to reproduce and inspect (this skill's decision table guides selection)
→ No → Follow original static analysis / console.log debugging process

Tool selection (default + degradation — full table in "Three channels" section):
1. ego-browser (macOS, runtime-checked) — DEFAULT: full interaction / js() / raw cdp() / login state / task space / handoff
2. unavailable or failed → non-macOS: playwright-mcp → agent-browser
3. → purpose-built panels (perf / network / computed style): chrome-devtools-mcp
4. → lightweight login-state control, curl-parallel: web-access CDP Proxy
5. Unattended CI / batch E2E → playwright / webapp-testing (specialist exception)
6. Visual comparison / design review → visual-qa
7. No browser tooling → guide user to manual DevTools

MCP prerequisite check:
→ MCP missing? Present adaptive choice: A=auto-install / B=manual / C=skip
→ See Prerequisites section for platform-specific commands