stagehand-expert

🎭 スキル：Stagehand エキスパート（v4.1.0）

概要

stagehand-expert は、ブラウザー自動化と高精度なエージェントオーケストレーションを専門とするエリートです。2026年、ウェブ自動化は壊れやすいセレクターから、自然言語プリミティブと直接 CDP 通信へと移行しました。このスキルでは、Stagehand V3の習得、コストゼロの CI/CD を実現する判断キャッシュの活用、そして複雑なShadow DOM／iframe構造の操作に重点を置き、速度を44％向上させます。

---

📋 目次

1. 先回り調査プロトコル
2. 「やってはいけない」リスト（アンチパターン）
3. コアプリミティブ（Act、Extract、Observe）
4. 直接 CDP 通信とパフォーマンス
5. 高度なエージェントキャッシュ
6. 自律型エージェント（CUA）
7. リファレンスライブラリ

---

🔍 先回り調査プロトコル

テストを1つでも書く前に、エキスパートは必ず詳細な調査を実施します：

1. ルートのマッピング：page.tsx またはルーター設定からユーザーフローを特定します。
2. UI コンポーネントの監査：ソースコードを読み、ID、ラベル、読み込み状態を確認します。
3. 雰囲気のチェック：CDP の「Vibe Score」を使用して、レイアウトの安定性を測定します。
4. スキーマの推定：既存のバックエンド／DB の型を分析し、100％互換性のある extract() 用 Zod スキーマを作成します。

---

🚫 「やってはいけない」リスト（アンチパターン）

アンチパターン	2026年に失敗する理由	最新の代替手段
手動でのフレーム切り替え	壊れやすく、時間がかかります。	DeepLocator (>>) & CDP を使用します。
ハードコードされた Wait(2000)	信頼性が低く、動作のぎこちなさを引き起こします。	domSettleTimeout を使用します。
finally { close() } の欠落	ゾンビプロセスが残ります。	try...finally を必須にします。
CI での LLM 呼び出し	時間がかかり、コストも高くなります。	永続的な判断キャッシュを使用します。
CSS アニメーションの無視	トランジション中に操作が失敗します。	Reanimated 対応の待機処理を使用します。

---

⚡ コアプリミティブの習得

• Act：変数を割り当てた、自然言語による正確な指示です。
• Observe：ページ内のすべての要素を1ターンで特定し、コストを70％削減します。
• Extract：Zod で検証された構造化データを、意味的にフラット化して取得します。

---

💾 高度な判断キャッシュ

E2E テストを決定論的なアセットに変換します：

• ローカルで開発：ライブ LLM がキャッシュを生成します。
• キャッシュをコミット：DOM スナップショットと結果を Git に保存します。
• コストゼロの CI：「キャッシュのみ」モードでテストを実行します。

詳細については、リファレンス：エージェントキャッシュを参照してください。

---

🤖 自律型エージェントと CUA

最も複雑な UI（クロスオリジン iframe、動的キャンバス）には、次を使用します：

• Computer Use Agent（CUA）：解析が不可能な要素に対する、視覚情報のみに基づく推論です。
• 安全性コールバック：金銭が関係する操作や破壊的な操作では、人間による確認を必須にします。

---

📖 リファレンスライブラリ

Stagehand を最大限に活用するための詳細な解説：

• 直接 CDP 通信：速度と詳細なアクセス。
• エージェントキャッシュ：決定性とコスト削減。
• Shadow DOM の習得：ドキュメント境界を越える操作。
• インストールとセットアップ：Bun／Playwright スタック。

---

更新日：2026年1月22日 - 21:20