WebSearch/WebFetch は本当に必要か
Claude Code で外部サイトを参照したいとき、WebFetch や WebSearch に手が伸びるのは自然だ。しかし「便利さ」と「コンテキストコスト」は別の話で、長いセッションで品質低下が起きるとき、原因はコンテキストウィンドウの浪費に行き着くことが多い。八雲では外部サイト調査を agent-browser に一本化するルールを設けた。
課題: HTML がコンテキストを浪費する
WebFetch が返すのは HTML の全文だ。ナビゲーション・広告・スクリプトタグ・インラインスタイルなどほぼすべてがコンテキストに流れ込む。企業サイト 1 ページの HTML は軽くて 30KB、重ければ 100KB を超える。
実際に関心があるのは「サービス構成」「ナビゲーション」「CTA のコピー」程度だが、HTML の 90% 以上は推論に貢献しないノイズだ。このノイズが Claude の推論の焦点を散らし、信号対雑音比の悪化が返答の精度に響く。
アプローチ: agent-browser を別プロセスにする
agent-browser は Playwright ベースのヘッドレスブラウザ CLI ツールだ。Claude Code の外側でデーモンとして常駐し、HTML の取得・レンダリング・DOM 操作はすべて子プロセスが担う。親 Claude は精製された答えだけを受け取る。
agent-browser open https://example.com
agent-browser snapshot # アクセシビリティツリー（軽量）
agent-browser eval "Array.from(document.querySelectorAll('h1,h2,h3')).slice(0,20).map(h => h.tagName + ':' + h.textContent.trim().slice(0,80)).join(' | ')"
agent-browser screenshot /tmp/ref.png # 必要時のみsnapshot はアクセシビリティツリーを返す。見出し・ボタン・リンクが構造化テキストで得られ、HTML 全体と比べると桁が違う情報量に収まる。eval で JavaScript を実行する方式はさらに精密で、欲しい要素だけを取り出してコンテキストに乗るのは数十〜数百文字だけになる。
トークンコスト試算
厳密な数字は場合によって変わるが、体感として桁が違う。WebFetch で 1 ページを取得すると数千〜数万トークン程度がコンテキストに乗る。eval でナビゲーション構成を抽出した場合は数百トークン以下に収まることが多い。競合 10 社の調査シナリオでは、両方式でトータルの消費量に一桁以上の差が出る。この差が積み重なることで長いセッションの安定性が変わる。
どんなときに WebFetch を使うか
agent-browser がすべてのケースで最適解とは言えない。JSON / Markdown 形式のドキュメントを取得するときは WebFetch で十分だ。GitHub の README、npm ドキュメント、MDN の仕様ページなどは構造化テキストそのもので HTML のノイズが少ない。API エンドポイントから JSON を直接取得するときも同様だ。
一方、ビジュアル・レイアウト・トンマナを調査するときは agent-browser 一択だ。snapshot で構造を把握し、必要なら screenshot で視覚を確認する二段構えが効く。
八雲の CLAUDE.md には「ビジュアル・レイアウト・トンマナ調査では agent-browser に統一、WebFetch / WebSearch は軽量な JSON / Markdown 取得のみ」と明示している。判断基準を文書化することで、エージェントが都度悩まずに適切な手段を選べる。
運用してわかった効果と落とし穴
効果として実感しているのは長時間セッションの安定性だ。複数サイトを調べる調査タスクは以前コンテキストが詰まって品質が落ちることがあったが、agent-browser に切り替えて以降は体感として大幅に減った。
研究系タスクでは並列サブエージェント方式との組み合わせが効く。競合調査・デザインリファレンス収集・技術検証の各調査軸を独立したサブエージェントに割り振り並列で走らせる。各サブエージェントは agent-browser で調査を完遂し、単一ファイルに保存して 3 行のサマリーだけを返す。直列処理では Plan の上限に達して成果が失われるリスクがあるが、並列化はそのヘッジにもなる。
落とし穴として注意が必要なのは eval のセレクタ精度だ。指定が甘いと意図しない要素が混入し、SPA でハイドレーション前に取得しようとすると引っかかりやすい。agent-browser wait 2000 でレンダリングを待つか snapshot に切り替えるかを状況で判断している。スクリーンショットは視覚確認に有効だが画像をコンテキストに乗せるため「必要時のみ」という原則は変わらない。
まとめ
WebFetch / WebSearch はコンテキストウィンドウを HTML のノイズで埋めるコストがある。agent-browser は「ブラウザを外に置いて抽出結果だけを返す」設計でそのトレードオフを解消する。使い分けの基準はシンプルだ。ビジュアル・レイアウト・トンマナなら agent-browser、軽量な JSON / Markdown なら WebFetch。この判断を CLAUDE.md に書いておくことで、エージェントの行動を設計できる。
コンテキストウィンドウを有限の資源として意識し、何をどれだけ乗せるかを設計することが、Claude Code を長期間・大規模に使う上での基盤になる。
関連記事
- Yakumo の AI 駆動開発のリアル — 八雲の AI 駆動開発の全体設計（ハブ記事）
- agent-browser を使う理由 — Claude Code でのトークン経済学 — agent-browser の設計思想の詳細
- agent-browser wrapper 設計 — ログイン継続セッションを AI 駆動で扱う — headless 強制 wrapper と hook によるガードレール