vercel-labs/dogfood

Dogfood（ドッグフーディング）

ウェブアプリケーションを体系的に探索し、問題を発見して、すべての発見事項に対して完全な再現証拠を含むレポートを生成します。

セットアップ

ターゲットURLのみ必須です。その他のパラメータには適切なデフォルト値があり、ユーザーが明示的に上書きを指定しない限りはデフォルトを使用してください。

パラメータ	デフォルト	上書き例
ターゲットURL	(必須)	vercel.com, http://localhost:3000
セッション名	ドメインをスラッグ化（例：vercel.com -> vercel-com）	--session my-session
出力ディレクトリ	./dogfood-output/	Output directory: /tmp/qa
スコープ	アプリ全体	Focus on the billing page
認証	なし	Sign in to [email protected]

ユーザーが「dogfood vercel.com」のように言った場合は、デフォルトのまますぐに開始してください。認証が必要だが認証情報が不足している場合を除き、確認の質問はしないでください。

常にagent-browserを直接使用してください。npx agent-browserは使わないでください。直接バイナリを使用すると高速なRustクライアントが使えます。npxを使うとNode.js経由でルーティングされ、大幅に遅くなります。

ワークフロー

1. 初期化        セッション、出力ディレクトリ、レポートファイルをセットアップ
2. 認証          必要に応じてサインインし、状態を保存
3. 方向付け      開始ポイントに移動し、初期スナップショットを取得
4. 探索          ページを体系的に訪問し、機能をテスト
5. 文書化        問題が見つかるたびにスクリーンショットと録画を実施
6. ラップアップ  サマリーカウントを更新し、セッションを閉じる

1. 初期化

mkdir -p {OUTPUT_DIR}/screenshots {OUTPUT_DIR}/videos

レポートテンプレートを出力ディレクトリにコピーし、ヘッダーフィールドを記入します。

cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md

名前付きセッションを開始します。

agent-browser --session {SESSION} open {TARGET_URL}
agent-browser --session {SESSION} wait --load domcontentloaded

2. 認証

アプリがログインを必要とする場合：

agent-browser --session {SESSION} snapshot -i
# ログインフォームのリファレンスを特定し、認証情報を入力
agent-browser --session {SESSION} fill @e1 "{EMAIL}"
agent-browser --session {SESSION} fill @e2 "{PASSWORD}"
agent-browser --session {SESSION} click @e3
# 以下を対象アプリのログイン後URL、テキスト、またはJS条件に置き換えてください。
agent-browser --session {SESSION} wait --url "{POST_LOGIN_URL_PATTERN}"
# または:
# agent-browser --session {SESSION} wait --text "{POST_LOGIN_TEXT}"
# agent-browser --session {SESSION} wait --fn "{POST_LOGIN_CONDITION}"

OTP/メールコードが必要な場合：ユーザーに確認し、応答を待ってからコードを入力します。

ログイン成功後、後で再利用できるように状態を保存します。

agent-browser --session {SESSION} state save {OUTPUT_DIR}/auth-state.json

3. 方向付け

アプリの構造を把握するために、初期の注釈付きスクリーンショットとスナップショットを取得します。

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/initial.png
agent-browser --session {SESSION} snapshot -i

メインのナビゲーション要素を特定し、訪問するセクションをマッピングします。

4. 探索

確認すべき項目の完全なリストと探索チェックリストについては、references/issue-taxonomy.mdを参照してください。

戦略 — アプリケーションを体系的に進める：

• メインナビゲーションから開始します。各トップレベルセクションを訪問します。
• 各セクション内で、インタラクティブ要素（ボタンクリック、フォーム入力、ドロップダウン/モーダルを開くなど）をテストします。
• エッジケース（空の状態、エラーハンドリング、境界値入力）をチェックします。
• 現実的なエンドツーエンドのワークフロー（作成、編集、削除の流れ）を試します。
• 定期的にブラウザコンソールのエラーを確認します。

各ページで：

agent-browser --session {SESSION} snapshot -i
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/{page-name}.png
agent-browser --session {SESSION} errors
agent-browser --session {SESSION} console

どの程度深く探索するかはあなたの判断に委ねます。コア機能により多くの時間を費やし、周辺ページには少なめにします。ある領域で問題のクラスターを見つけた場合は、より深く調査します。

5. 問題の文書化（再現第一）

ステップ4と5は同時に行います。1回のパスで探索と文書化を行います。問題を見つけたら、探索を中断し、すぐに文書化してから次に進んでください。アプリ全体を先に探索してから後で文書化してはいけません。

すべての問題は再現可能でなければなりません。問題を見つけたら、単にメモするだけでなく、証拠で証明してください。目標は、レポートを読んだ人が何が起こったのかを正確に見て、それを再現できることです。

問題に適した証拠レベルを選択してください：

インタラクティブ/動作上の問題（機能、UX、アクション時のコンソールエラー）

これらは再現にユーザー操作が必要です。動画とステップごとのスクリーンショットを使用した完全な再現を行います。

1. 再現動画を開始します 再現の前に：

agent-browser --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.webm

2. 人間のペースで手順を進めます。 アクション間で1〜2秒待機し、動画を見やすくします。各ステップでスクリーンショットを撮影します。

agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png
sleep 1
# アクションを実行（クリック、入力など）
sleep 1
agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png
sleep 1
# ...問題が現れるまで続ける

3. 問題が発生した状態をキャプチャします。 閲覧者が見えるように少し待ち、注釈付きスクリーンショットを撮影します。

sleep 2
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}-result.png

4. 動画を停止します：

agent-browser --session {SESSION} record stop

5. レポートに番号付きの再現手順を書き、各手順が対応するスクリーンショットを参照するようにします。

静的/ロード時に表示される問題（タイポ、プレースホルダーテキスト、テキストのクリッピング、位置ずれ、ロード時のコンソールエラー）

これらは操作なしで表示されます。単一の注釈付きスクリーンショットで十分です。動画や複数ステップの再現は不要です。

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}.png

簡単な説明を書き、レポートでスクリーンショットを参照します。再現動画はN/Aに設定します。

---

すべての問題に対して：

1. すぐにレポートに追記します。 問題を後でまとめて処理しないでください。見つけたものはその都度書き込み、セッションが中断された場合に何も失われないようにします。

2. 問題カウンターをインクリメントします（ISSUE-001、ISSUE-002、...）。

6. ラップアップ

5〜10個の十分に文書化された問題を見つけることを目標とし、その後ラップアップします。証拠の深さが総数よりも重要です。完全な再現が可能な5つの問題は、あいまいな説明の20の問題よりも優れています。

探索後：

1. レポートを再読し、サマリーの重大度カウントを実際の問題と一致するように更新します。すべての### ISSUE-ブロックが集計に反映されている必要があります。
2. セッションを閉じます：

agent-browser --session {SESSION} close

3. ユーザーにレポートの準備ができたことを伝え、発見事項を要約します：問題の総数、重大度別の内訳、最もクリティカルな項目。

ガイダンス

• 再現がすべてです。 すべての問題には証拠が必要ですが、証拠のレベルは問題に合わせてください。インタラクティブなバグには動画とステップごとのスクリーンショットが必要です。静的なバグ（タイポ、プレースホルダーテキスト、ロード時に見える表示の不具合）は、注釈付きの単一スクリーンショットのみで十分です。
• 証拠を収集する前に再現性を確認してください。 動画の録画やスクリーンショットの撮影前に、問題が少なくとも1回の再試行で再現可能であることを確認します。一貫して再現できない場合は、有効な問題ではありません。
• 静的な問題には動画を録画しないでください。 タイポやクリッピングされたテキストに動画は不要です。ユーザー操作、タイミング、状態変化が関係する問題に動画を取っておきます。
• インタラクティブな問題では、各ステップをスクリーンショットで記録します。 前、アクション、後をキャプチャし、誰かが一連の流れを完全に見られるようにします。
• スクリーンショットに対応する再現手順を書きます。 レポートの番号付き各ステップは、対応するスクリーンショットを参照する必要があります。読者はブラウザに触れずに視覚的に手順を追うことができる必要があります。
• 適切なスナップショットコマンドを使用します。
  • snapshot -i — クリック可能/入力可能な要素（ボタン、入力欄、リンク）を見つけるため
  • snapshot（フラグなし） — ページコンテンツ（テキスト、見出し、データリスト）を読むため
• 徹底的に行いますが、判断力を働かせます。 テストスクリプトに従っているのではなく、実際のユーザーのように探索しています。何かおかしいと感じたら、調査します。
• 発見事項はインクリメンタルに書き込みます。 問題を発見するたびにレポートに追記します。セッションが中断された場合でも、発見事項は保持されます。すべての問題を最後にまとめて処理しないでください。
• 出力ファイルを決して削除しないでください。 セッション中にスクリーンショット、動画、レポートをrmしてはいけません。セッションを閉じて再開してもいけません。前方に進み、後戻りしないでください。
• 対象アプリのソースコードを読まないでください。 ユーザーとしてテストしており、コードを監査しているわけではありません。テスト対象アプリのHTML、JS、設定ファイルを読まないでください。すべての発見事項はブラウザで観察したものから得られなければなりません。
• コンソールを確認します。 多くの問題はUIには見えませんが、JSエラーや失敗したリクエストとして現れます。
• ロボットではなく、ユーザーのようにテストします。 一般的なワークフローをエンドツーエンドで試してください。実際のユーザーがクリックするであろうものをクリックし、現実的なデータを入力します。
• 人間のようにタイプします。 動画録画中にフォームフィールドに入力する場合は、fillではなくtypeを使用します。typeは1文字ずつ入力します。fillは動画録画外で速度が必要な場合にのみ使用します。
• 再現動画は人間向けのペースにします。 アクション間にsleep 1、最終結果のスクリーンショットの前にsleep 2を追加します。動画は1倍速で視聴可能である必要があります。レポートを確認する人間は、瞬間的な状態変化のぼやけではなく、何が起こったのかを見る必要があります。
• コマンドは効率的に使用します。 独立した複数のagent-browserコマンドは、1回のシェル呼び出しでまとめて実行します（例：agent-browser ... screenshot ... && agent-browser ... console）。スクロールにはagent-browser --session {SESSION} scroll down 300を使用します。keyやevaluateでスクロールしないでください。

リファレンス

リファレンス	いつ読むか
references/issue-taxonomy.md	セッション開始時 — 何を探すべきか、重大度レベル、探索チェックリストを確認する

テンプレート

テンプレート	目的
templates/dogfood-report-template.md	出力ディレクトリにレポートファイルとしてコピーする