注釈付きスクリーンショット ドキュメンテーション

任意のウェブアプリまたはライブウェブサイトの注釈付きスクリーンショットを含むマークダウンドキュメントを生成します。

前提条件

• agent-browser CLI がグローバルにインストールされている (npm i -g agent-browser && agent-browser install)

フェーズ 1: ターゲットの決定

A) ライブウェブサイト

1. URL を正規化する (必要に応じて https:// を追加):

   agent-browser open https://example.com && agent-browser wait --load networkidle
   

2. セマンティックロケータを使用してクッキー/同意バナーを閉じる (最も信頼性が高い):

   agent-browser find text "Accept" click
   

   または、スナップショットを使用して受け入れボタンの参照を検出してから、参照を直接クリック:

   agent-browser snapshot -i -s "[role=dialog], [class*=cookie], [class*=consent]" -c
   agent-browser click @e1  # スナップショットから参照を使用
   

   消えたことを確認: agent-browser is visible "[role=dialog]" または agent-browser wait "[role=dialog]" --state hidden
3. ログインの壁またはアンチボットの問題については、references/live-sites.md を参照してください。

B) ローカル開発サーバー

1. 開発サーバーを検出または開始 (ポート 3000/5173/4321/8080 を確認するか、package.json から開始):
2. 自己署名証明書の場合: agent-browser --ignore-https-errors open https://localhost:<port>

フェーズ 2: サイトをマップする

1. ホームページを開く: agent-browser open <url> && agent-browser wait --load networkidle
2. クイック自動注釈スクリーンショットでページを調査 — これはすべてのインタラクティブ要素に番号付き参照でラベルを付けます:

   agent-browser screenshot --annotate docs/screenshots/_survey.png
   

   出力凡例を読んでページに何があるか理解する (ボタン、リンク、入力フィールドが @e 参照にマップされています)。
3. ナビゲーションをスナップショットしてページを発見:

   agent-browser snapshot -i -s "header, nav, [role=navigation]" -c
   

   深い DOM の場合: agent-browser snapshot -i -c -d 3
4. クライアント側ルーティングを持つ SPA の場合: ソースコード内のルート定義も確認してください (grep -r "path:" src/router など)。すべてのルートがナビゲーションからリンクされていないかもしれません。
5. ユーザーに確認を求めてください ページリストを。ライブサイトの場合、最大 5～10 ページを提案します。

フェーズ 3: 各ページのスクリーンショット

ページごとのワークフロー: セレクタを検証 → 注釈を付与 → FAILED を確認 → スクリーンショットを検証 → 修正または続行。

セットアップ (すべてのスクリーンショットの前に一度実行):

agent-browser set viewport 1440 900
export AGENT_BROWSER_SCREENSHOT_DIR=docs/screenshots

オーバーレイを作成したりページロードを遅くしたりする広告とトラッキングスクリプトをブロック (ライブサイト):

agent-browser network route "**/*.doubleclick.net/**" --abort
agent-browser network route "**/googlesyndication.com/**" --abort
agent-browser network route "**/analytics.js" --abort
agent-browser network route "**/gtm.js" --abort

注釈スクリプトパスを解決 (一般的なインストール場所をチェック):

ANNOT_JS="$(find . .claude .agents ~/skills -path '*/app-screenshots/references/annotate.js' 2>/dev/null | head -1)"
[ -z "$ANNOT_JS" ] && echo "ERROR: annotate.js not found — check skill installation"

各ページについて:

ステップ 1: ナビゲート

agent-browser open <url> && agent-browser wait --load networkidle

ライブサイトの場合、agent-browser wait 2000 を追加して遅延読み込みコンテンツを待機します。中間出力が不要な場合はチェーン: agent-browser open <url> && agent-browser wait --load networkidle && agent-browser wait 2000

ステップ 2: クッキー/同意バナーを閉じる (ライブサイト)

agent-browser find text "Accept" click
agent-browser wait "[class*=overlay]" --state hidden

複雑または iframe バナーの場合は、references/live-sites.md を参照してください。

ステップ 3: 注釈付与の前にセレクタを検証

常にセレクタを最初にテストしてください。 失敗したセレクタは見えない注釈を生成します。

複雑な JS の場合は heredoc で eval --stdin を使用 (シェルのクォート問題を回避):

agent-browser eval --stdin <<'EVALEOF'
const sels = ['selector1', 'selector2'];
sels.map(s => {
  const el = document.querySelector(s);
  if (!el) return 'MISSING: ' + s;
  const r = el.getBoundingClientRect();
  return 'OK: ' + s + ' (' + Math.round(r.width) + 'x' + Math.round(r.height) + ')';
}).join('\n')
EVALEOF

クイックマッチ数チェック: agent-browser get count "<selector>"

MISSING の場合、agent-browser snapshot -i -c を使用して正しいセレクタと参照を発見してください。壊れたセレクタで注釈を付与しないでください。 セレクタのヒントについては references/selectors.md を参照してください。

ビューポート下部の要素については、最初にスクロールして表示: agent-browser scrollintoview "<selector>"

ステップ 4: 注釈を挿入

eval --stdin を使用して注釈スクリプトを安全に挿入:

agent-browser eval --stdin <<EVALEOF
$(cat "$ANNOT_JS")
annotateMulti([
  {sel: 'selector', label: 'Label', type: 'box'},
  {sel: 'selector', label: 'Label', type: 'click'}
])
EVALEOF

重要: 出力が FAILED: で始まる場合、スクリーンショットの前にセレクタを修正してください。クリアして再試行:

agent-browser eval "clearAnnotations()"

注釈タイプ:

• click — 塗りつぶされた円 + 矢印 + 番号付きラベル。ボタン、リンク、入力フィールドに使用。
• box — 破線枠 + 番号付きラベル。セクション、カード、コンテナに使用。
• circle (デフォルト) — キャップ付き破線円 + 矢印 + 番号付きラベル。一般的な注釈。

色は自動回転: 赤、青、緑、琥珀色、紫。各注釈は自動番号付け (1, 2, 3...) されてマークダウン内で相互参照に使用されます。

1 つのスクリーンショットあたり最大 3 つの注釈。 必要に応じて複数のスクリーンショットに分割 (例: 03a-top.png, 03b-actions.png)。

タイプ選択ルール:

• click は小要素 (ボタン、リンク、アイコン) — キャップ付き円は膨張しません
• box は中程度の領域 (カード、フォームグループ、サイドバー) — 要素の形状に従う
• 決して circle または box をフルウィド要素 (ナビバー、ヘッダー) に使用しないでください — 代わりにそれらの中の特定のアイテムに注釈を付けます

ページタイプごとに注釈を付ける内容:

• ホームページ: ヒーロー CTA、検索入力、1 つのナビゲーション例
• 製品リスト: 1 つの製品カード、フィルタトグル、ソートドロップダウン
• 製品詳細: 価格、カートに追加、サイズ/バリアント選択肢
• 検索結果: 検索入力、1 つの結果カード、フィルタサイドバー
• ダッシュボード: 1 つのメトリクスカード、1 つのチャート、主要アクション
• テーブル/データビュー: 列ヘッダー、フィルタコントロール、データ領域
• 設定/フォーム: 主要フォームフィールド、送信ボタン

ステップ 5: スクリーンショット

agent-browser screenshot <NN>-<page-name>.png

ゼロパディング番号付け: 01-homepage.png, 02-category.png など。コンテンツがビューポート下に拡張する場合は --full を使用してフルページスクリーンショットを取得。

ステップ 6: スクリーンショット品質を検証

キャプチャしたばかりのスクリーンショットファイルを読んで 以下を確認:

• 注釈が見え、互いに重なっていない
• ラベルがビューポートエッジで切り取られていない
• ページコンテンツが正しく読み込まれた (スピナーや壊れた画像がない)
• クッキーバナーまたはオーバーレイがビューを遮っていない

問題がある場合: agent-browser eval "clearAnnotations()" を実行し、問題を修正し、再度注釈を付与して、再度スクリーンショット。悪いスクリーンショットで進めないでください。

インタラクティブスクリーンショット

検索、メニュー、モーダル、ホバー状態については — スナップショット → 参照 → インタラクトパターンを使用:

# 1. スナップショットして参照を取得
agent-browser snapshot -i
# 2. 参照を使用してインタラクト (CSS セレクタより信頼性高い)
agent-browser click @e5          # 参照で検索入力をクリック
agent-browser type @e5 "shoes"
agent-browser wait 2000
# 3. 結果に注釈を付与
agent-browser eval --stdin <<EVALEOF
$(cat "$ANNOT_JS")
annotateMulti([{sel: '[class*=suggest]', label: 'Suggestions', type: 'box'}])
EVALEOF
# 4. スクリーンショット
agent-browser screenshot 05-search-results.png
# 5. 検証 — スクリーンショットを読んで品質をチェック

注: iframe 内の参照は直接機能 — インタラクションには frame 切り替えが不要です。

インタラクティブフロー記録 (オプション)

複雑なインタラクション (チェックアウトフロー、マルチステップウィザード) の場合、スクリーンショットと共にビデオを記録:

agent-browser record start docs/screenshots/checkout-flow.webm
# ... インタラクションステップを実行し、その過程でスクリーンショットを撮影 ...
agent-browser record stop

マークダウンでビデオをリンク: [Watch checkout flow](screenshots/checkout-flow.webm)

モバイル / レスポンシブスクリーンショット

モバイルレイアウトをドキュメント化:

# デバイスエミュレーションを使用 (ビューポート + ユーザーエージェントを一緒に設定)
agent-browser set device "iPhone 14"

その後、同じ注釈付与 → スクリーンショット → 検証ワークフローに従ってください。ファイルに -mobile サフィックスで名前を付ける: 01-homepage-mobile.png。

デスクトップに戻す: agent-browser set viewport 1440 900

注: 狭いビューポートでは、混雑を避けるため 1 スクリーンショットあたり最大 2 つの注釈を使用してください。

フェーズ 4: マークダウンを生成

ファイル名: docs/<domain>-screenshots.md (ライブサイト) または docs/app-screenshots.md (ローカル)。

番号付き参照 (1), (2), (3) を説明で使用して、各スクリーンショットに表示される注釈バッジを相互参照します。

# <サイト/アプリ名> - ビジュアルガイド

サイト/アプリの簡潔な説明。

**URL:** <base-url>
**日付:** <今日の日付>

**注釈キー:** 赤 = 主要アクション、青 = 副要素、緑 = コンテンツ領域

---

## <ページ名>

ページを説明する 1～3 文。番号で注釈を参照:
「**検索バー** (1) はオートコンプリートに対応しています。**カテゴリーナビ** (2) を使用して部署を閲覧します。
**ヒーロー バナー** (3) は季節のプロモーションをローテーションします。」

![<ページ名>](screenshots/<filename>.png)

---

フェーズ 5: 環境を比較 (オプション)

ステージングと本番の間の違いをドキュメント化する場合、またはリデザイン前後:

# 2 つの URL 間のビジュアルピクセル差分
agent-browser diff url https://staging.example.com https://prod.example.com

# ベースラインスクリーンショットに対する差分
agent-browser diff screenshot --baseline docs/screenshots/01-homepage-before.png

# アクセシビリティツリーの差分 (構造的変化を検出)
agent-browser diff snapshot

マークダウンに差分スクリーンショットを含めて何が変わったかをハイライト。

フェーズ 6: クリーンアップ

# ネットワークインターセプトを削除
agent-browser network unroute
agent-browser close

リファレンス

• セレクタのヒントとトラブルシューティング: references/selectors.md を参照してください
• ライブサイトのヒント (クッキー、遅延読み込み、レート制限、地理): references/live-sites.md を参照してください