ブラウザパイロット

目的: 任意のエージェント（またはユーザー）にブラウザ内での目と手を提供します。自然言語の命令を解釈し、実行中のウェブアプリに対して Playwright MCP ツールを使用して実行します。 呼び出し元: ユーザーが直接実行（/browser-pilot）、エグゼキューター、PR レビューアー、スパーリング、またはスクリーン上で何かを確認する必要がある任意のエージェント。

---

飛行前チェック

どの操作の前にも、接続が確立していることを確認します:

1. browser_tabsを呼び出します（アクション: "list"）。
2. 応答がある場合: 接続されています。関連するタブが既に開いているかを確認します。
3. 失敗した場合: 停止して報告します:

Playwright MCP が応答していません。確認してください:

1. Chrome が開いている
2. 拡張機能「Playwright MCP Bridge」がインストールされ、有効化されている（緑のアイコン）
3. MCP が ~/toolkit/config/mcp.json に --extension で設定されている
4. Claude Code を再起動して MCP の設定を再度読み込む

飛行前チェックに合格するまで先に進まないでください。

---

入力

フィールド	必須	説明
命令	はい	何をするか — 自然言語で、フレーズ、質問、またはリスト形式
URL	いいえ	指定されない場合は、まず開いているタブを確認します。関連するタブがない場合はユーザーに確認します
環境	推測	URL から検出: localhost = 開発環境、staging/pre = ステージング環境、admin/internal = 本番に近い環境。それに応じて慎重さレベルを調整します

---

ガードレール

1. オリエンテーション

行動を起こす前に、作業対象を確立します:

• どの URL またはタブ？ URL が指定されない場合は、browser_tabsを呼び出して何が開いているかを確認します — 関連するタブがあれば使用します。
• 目標は何か？（検証、探索、比較、テスト、証拠取得）

命令が十分に明確であれば、質問をスキップして進みます。

2. 最初に観察

クリック、入力、ナビゲーションを行う前に:

• browser_snapshotを取得してページ構造（アクセシビリティツリー）を理解します
• ビジュアルコンテキストが重要な場合はbrowser_take_screenshotを取得します

3. 説明する

実行する全てのアクション について、簡潔に何をしているか、なぜかを述べます:

• 「レイアウトを確認するために /risk-ops にナビゲートしています」
• 「タブを急速に閉じるテストを行うため、タブ 2 の『閉じる』ボタンをクリックしています」
• 「モバイルレンダリングを確認するため、375x812 にリサイズしています」

4. 報告

完了したら、以下のサマリーテンプレートを使用して、見つかった内容で終了します。

5. 報告前に検証

結果を提供する前に、確認してください:

• 命令の全ての項目を網羅していますか？ (理由: ステップをスキップした不完全なレポートを防止)
• チェックリストを実行している場合、全ての項目に対して合格/不合格の判定がありますか？
• 調査結果には必要に応じてスナップショットやスクリーンショットの証拠がありますか？
• 確認していないコンソールエラーやネットワーク障害はありますか？

---

モード検出

命令からモードを推測します。命令がどのパターンにも当てはまらない場合は、デフォルトで探索に設定します。

命令内のパターン	モード	動作
「見てください」「チェックしてください」「どのように見えますか」、単一の質問	探索	ナビゲーション、観察、見つかった内容を報告
ステップのリスト、「UAT」、「一つずつ」、「これらをテストしてください」	チェックリスト	順序通り実行、項目ごとに合格/不合格を報告
「比較」、「A vs B」、「どちらが見栄えが良いか」	比較	両方のスクリーンショットを取得、相違点を説明
「モック」、「シミュレート」、「もしこうなったら」	シナリオ	条件を設定（evaluate/インターセプト経由）、結果を観察
「監視してください」、「進みながら検証してください」	コンパニオン	他の作業間での定期的なチェック、軽量

---

ツール参照

命令が必要とする任意の Playwright MCP ツールを使用します。主要なもの:

ツール	使用時機
browser_navigate	URL に移動
browser_snapshot	ページ構造（a11y ツリー）を読取 — あなたの主要な「目」
browser_take_screenshot	ビジュアル証拠を取得
browser_click / browser_hover / browser_type	要素と対話
browser_fill_form	複数のフォームフィールドを一度に入力
browser_press_key	キーボードショートカット、送信用の Enter
browser_tabs	タブをリスト表示、作成、閉じる、または切り替え
browser_resize	異なるビューポートでレスポンシブをテスト
browser_console_messages	JS エラーを確認（レベル: "error"）
browser_network_requests	HTTP リクエスト失敗を確認
browser_evaluate	ページ上で JS を実行（DOM 状態を確認、パフォーマンスを測定）
browser_run_code	複雑なフローのための完全な Playwright コードスニペットを実行
browser_wait_for	要素、ナビゲーション、またはネットワークアイドルを待機

ページロードの待機

SPA は非同期です。ナビゲーションまたは対話の後:

1. browser_wait_forを使用してキー要素またはネットワークアイドルを待機します
2. ローディングスピナーのスクリーンショットを撮らないでください — コンテンツがレンダリングされるまで待機します
3. ページの読み込みに長時間（>10s）かかる場合は、それを検出結果として報告します

スクリーンショット予算

呼び出しごとに最大5 スクリーンショット。ナビゲーションと意思決定にはbrowser_snapshot（テキスト、低コスト）を使用します。ユーザーまたは別のエージェントが確認する必要があるビジュアル証拠のためにbrowser_take_screenshot（画像、高コスト）を予約します。(理由: 画像が多いセッションからのコンテキスト枯渇を防止)

ビデオウォークスルーの記録

ユーザーが「記録」、「デモ」、「grabar」、またはビデオ出力での「ウォークスルー」をリクエストする場合、このプロトコルに従います。目標は自然な人間らしいビデオです — デバッグアーティファクトなし、無駄な時間なし、古い UI なし。

フェーズ 1 — リハーサル（記録なし）

通常のツール呼び出し（browser_click、browser_snapshot など）を使用してフロー全体をナビゲートします。このフェーズはビデオのための UI 発見ではなくデバッグ用です。

• ビデオ中に対話するすべてのモーダル、ドロップダウン、フォームを開きます
• 各要素の機能するセレクターを記録します（ロール、名前、プレースホルダー、インデックス）
• ドライラン前にページをリセット（更新）します — browser_run_codeスクリプトは探索後の状態ではなくクリーン状態から動作する必要があります (理由: フェーズ 2 のリセットが開始条件を変更するため、リハーサルは成功したがビデオ中には失敗するスクリプトを防止)
• 単一のbrowser_run_code呼び出しでアクションチェーン全体をテストしてエラーなく実行することを確認します
• 何か失敗した場合: 修正して、チェーンが完全に成功するまで再試行します

リハーサルがエンドツーエンドで成功するまで記録を開始しないでください。 (理由: ビデオ内のデバッグアーティファクト — セレクター不一致、部分的に入力されたフォーム、エラーポップアップを防止)

フェーズ 2 — リセット

ビデオ用のクリーンな開始状態を準備します:

• ページをリフレッシュ（browser_navigateをターゲット URL に）
• ページが完全に読み込まれるまで待機（スピナーなし、「読み込み中...」なし）
• 確認: 古いモーダルやツールチップは開いていない、スクロール位置は上部

フェーズ 3 — 記録

1. browser_run_code内でpage.bringToFront()を使用してターゲットタブをフロントに持ってきます。browser_navigateは Chrome でタブをアクティブ化しません — ビデオは Chrome が表示しているタブを記録します。 (理由: 間違ったタブを記録するのを防止)
2. ~/toolkit/scripts/record-walkthrough.sh startを実行します — Chrome ウィンドウのみをキャプチャ（フルスクリーンではない）。ユーザーは他のアプリで作業を続けられます。
3. フェーズ 1 で検証されたフローをbrowser_run_codeを使用して実行します — すべてのアクションを単一の呼び出しで、ステップ間に自然な人間的なペース決めのためのwaitForTimeout()付き。より高速な出力と無駄な時間を減らすため、記録前に高速なモデル（/model claude-sonnet-4-6）に切り替えることを検討するか、記録をサブエージェントに委譲します。 (理由: ツール呼び出し間のモデル思考からの無駄な時間を防止)
4. メインアクション（例えばフォーム送信）の後: 結果にスクロールする前に非同期完了を待機します。モーダルとダイアログは非同期で閉じます — waitForSelector('[role="dialog"]', { state: 'detached' })または同様のものを使用して、スクロール前に結果が見えることを確認します。これを同じbrowser_run_code呼び出しに含めます。 (理由: モーダルオーバーレイの下にスクロール、または結果が確認される前にビデオが終了するのを防止)
5. ~/toolkit/scripts/record-walkthrough.sh stopを実行します — mp4 を~/Desktop/に出力

記録中は Chrome を最小化しないでください（他のウィンドウに遮られるのは問題ありません）。

スクリーンショット予算は記録中には適用されません — ビデオはすべてをキャプチャします。

フェーズ 4 — 検証とクリーンアップ

• mp4 が生成されたことを確認し、パスとサイズをユーザーに報告します
• 記録が失敗した場合（ファイルなし、スクリーンキャプチャエラー）: システム設定 > プライバシーとセキュリティでスクリーンレコーディング権限を確認します
• オプション: ビデオがアクション間に無駄な時間がある場合（例えばツール呼び出しが使用されたがbrowser_run_codeではない）、~/toolkit/scripts/cut-freeze.py input.mp4 -o output.mp4を実行して自動的に固定フレームを削除します

フォールバック: スクリーンショット + FFmpeg（1fps スライドショー）

スクリーンレコーディング権限が利用できない場合、またはユーザーがフレーバイフレームの制御を望む場合に使用します。

1. mkdir -p /tmp/browser-pilot-frames
2. スクリーンショットを順序通り命名: frame_001.png、frame_002.png など。
3. ~/toolkit/scripts/frames-to-video.sh /tmp/browser-pilot-frames ~/Desktop/demo.mp4 1

記録オプションの完全な評価については、docs/video-recording-research.mdを参照してください。

---

トラブルシューティング

検出: browser_tabsまたは任意の Playwright ツールが接続エラーを返します。修正: Chrome が開いているか、拡張機能がアクティブ（緑のアイコン）かを確認し、Claude Code を再起動して MCP 設定を再度読み込みます。

検出: ページが読み込まれるがアプリの代わりにログイン/SSO リダイレクトを表示します。修正: 拡張機能ブリッジがセッションを失いました。ユーザーは Chrome でページを手動でリフレッシュしてから再試行する必要があります。

検出: browser_snapshotがナビゲーション後に空または最小限のツリーを返します。修正: ページはまだ読み込まれている可能性があります。セレクターまたは "networkidle" でbrowser_wait_forを呼び出してから、スナップショットを再試行します。

検出: browser_take_screenshotが空白または古い画像を返します。修正: ページがモーダルまたは読み込みオーバーレイの背後にある可能性があります。最初にスナップショットを取得して DOM 状態を確認し、オーバーレイを閉じてから再試行します。

検出: スナップショットの要素refがクリック時に一致しません。修正: スナップショットとクリック間でページが変更されました。新しいbrowser_snapshotを取得して更新された ref を使用します。

---

制限事項

• 人間が支援する検証、E2E テストではありません。 反復可能な自動テストスイートの場合は、Playwright テストファイルを直接使用します。(理由: 適切な CI を置き換える脆弱なエージェント駆動テストを防止)
• 本番データを変更しないでください。 環境が本番のように見える場合（URL に localhost や staging がない）かつ命令が レコードを作成/削除する場合、それにフラグを立てて確認を求めます。(理由: 実際のユーザーへの取り返しのつかない副作用を防止)
• 認証は拡張機能で処理されます。 ユーザーのアクティブセッションで Chrome に接続されています。ログイン、SSO の処理、またはクッキー管理を試みないでください。

---

サマリーテンプレート

最終レポートを作成するときは、この構造を使用します。命令のレベルの詳細に適応させます — クイックチェックは簡潔なレポート、UAT リストは完全なテーブルを取得します。

### ブラウザパイロット — {モード}
- **URL**: {ターゲット URL またはタブ}
- **命令**: {リクエストされた内容}
- **結果**: {合格 | 不合格 | 部分 | 観察された動作サマリー}
- **検出結果**: {観察のリスト、または「なし」}
- **証拠**: {取得したスクリーンショットファイル名、または「スクリーンショット不要」}
- **コンソールエラー**: {数とサマリー、または「なし」}
- **ネットワークエラー**: {数とサマリー、または「なし」}
- **注記**: {予期しない内容または注目すべき点}

---

呼び出しの例

/browser-pilot Risk and Ops の画面がどのように見えるか確認してください
/browser-pilot このUAT リストを一つずつ進めてください: [リスト]
/browser-pilot フィーチャーフラグ on/off での表の見え方を比較してください
/browser-pilot /api/risks エンドポイントが 500 を返す場合をモックして、UI に何が表示されるか確認してください
/browser-pilot ステージング環境がうまく動作しているか確認してください
/browser-pilot 作成している各コンポーネントがどのようになるか検証しながら進めてください
/browser-pilot feature-fintech で Risk and Ops を新規作成するウォークスルーを記録してください