ProofShot徹底解説｜AIが書いたUIを動画で自動検証するCLIツールの使い方

AIコーディングエージェントはコードを書けるが、生成したUIが実際に正しく表示されているかを「見る」ことができない。ProofShotは、この「目の見えないエージェント」問題を解決するオープンソースCLIツールだ。ブラウザテストを動画で記録し、スクリーンショットとエラーログをバンドルして、人間が数秒でレビューできる証跡を自動生成する。

この記事ではUIデザインに特化して解説します。デザインシステム・UI生成全般は デザインシステムとは？仕組み・構成要素・有名事例をエンジニア向けに完全解説 をご覧ください。

AIエージェントの「盲目」問題とProofShotの立ち位置

AIコーディングエージェントの最大の弱点は、UIの視覚的な検証ができないことだ。エージェントがログインフォームを実装しても、ボタンの位置がずれていたり、CSSが崩れていたり、コンソールにエラーが出ていたりしても気づけない。生成されたコードがコンパイルを通ってテストもグリーンなのに、画面を開くと真っ白——そんな経験をした開発者は多いはずだ。

従来、この検証は人間が手動でブラウザを開いて目視確認するしかなかった。レビュー工程ごとにローカルでサーバーを立ち上げ、ブラウザで数回クリックし、問題があればエージェントに戻して再度確認する。この往復が重くなるほどAIエージェントの価値は相対的に下がる。

ProofShotはこの工程を自動化する「検証レイヤー」だ。ブラウザを制御するのではなく、ブラウザ制御ツールの上に立ち、動画記録・エラー検出・GitHub PR連携までを1本のCLIに束ねる。

「AIエージェントは目が見えない。だから人間がレビューで目になる。その目になる工程を、もう自動化してしまおう」——ProofShotのREADMEはこの思想を明確に打ち出している。

主要な機能を整理するとこうなる。

• 動画記録: セッション全体をWebM形式で録画
• スクリーンショット: 重要な操作ステップごとにキャプチャ
• エラー検出: コンソールエラーとサーバーログを10以上の言語で自動検出（JavaScript、Python、Ruby、Go、Java、Rust、PHP、C#など）
• インタラクティブビューア: タイムライン付きのHTMLビューアで動画とログを同期再生
• PRアップロード: proofshot pr コマンドでGitHub PRにインラインコメントとして証跡を投稿

Claude Codeの全機能まとめで紹介されているようなAIコーディングエージェントと組み合わせることで、コード生成から検証までのループを閉じることができる。

ProofShotのインストール手順とセットアップ

ProofShotはNode.jsベースのCLIツールで、npmでグローバルインストールする。導入コマンドは2行で完結する。

npm install -g proofshot
proofshot install

最初のコマンドでCLIとagent-browser（ヘッドレスChromium含む）がインストールされる。2番目のコマンドで使用中のAIコーディングツールを自動検出し、ユーザーレベルでスキルをインストールする。

スキルはユーザーレベル（~/.claude/skills/ など）にインストールされるため、プロジェクトごとの設定は不要だ。一度インストールすれば全プロジェクトで利用できる。

proofshot install は以下のエージェントに対応している。

インストールオプションも柔軟に指定できる。CIで特定エージェントのみ有効化したい場合や、既存スキルを上書き更新したい場合に役立つ。

proofshot install --only claude    # Claude Codeのみにインストール
proofshot install --skip cursor    # Cursorをスキップ
proofshot install --force          # 既存のインストールを上書き

3ステップの検証ワークフロー：start / test / stop

ProofShotの検証は start → test → stop の3段階で動作する。この分離が重要で、録画と操作と終了処理を明確に切り離すことで、AIエージェントがどのフェーズにいるかを迷わず判断できるようになっている。

# 1. start -- ブラウザを起動し、録画とサーバーログのキャプチャを開始
proofshot start --run "npm run dev" --port 3000 --description "Login form verification"

# 2. test -- AIエージェントがブラウザを操作
agent-browser snapshot -i                                    # インタラクティブ要素を確認
agent-browser open http://localhost:3000/login               # ページに遷移
agent-browser fill @e2 "[email protected]"                    # フォームに入力
agent-browser click @e5                                      # ボタンをクリック
agent-browser screenshot ./proofshot-artifacts/step-login.png # スクリーンショットを撮影

# 3. stop -- 動画+スクリーンショット+エラーを証跡としてバンドル
proofshot stop

スキルファイルがこのワークフローをエージェントに教えるため、ユーザーは「proofshot でこの機能を検証して」と指示するだけでよい。エージェントが自動的に start → test → stop の流れを実行する。

各セッションで生成されるアーティファクトは ./proofshot-artifacts/ にタイムスタンプ付きフォルダとして保存される。AIエージェントは録画そのものに触れず、ProofShotが裏でffmpeg相当の録画とログ集約を担う。

「SUMMARY.md を読めば動画を再生しなくてもエラー有無が分かる」——これがProofShotのレビュー高速化の核心だ。人間は概要だけ見て、疑わしい箇所だけ動画のタイムスタンプに飛べばよい。

Playwright MCPとの比較：ProofShotの差別化ポイント

「Playwright MCPやChrome DevTools MCPがあるのに、なぜProofShotが必要なのか？」という疑問は当然だ。結論から言うと、それらはブラウザの制御ツールであり、ProofShotは検証ワークフローツールだ。役割が異なる。

ProofShotはagent-browserの上に位置する検証レイヤーだ。セッション管理、サーバーログキャプチャ、エラー検出、動画トリミング、タイムスタンプ同期、インタラクティブビューア、PRアップロードワークフローを追加する。ブラウザの基本操作はagent-browserが担当している。

使い分けの指針はシンプルだ。

• ライブデバッグやDOM検査 → Playwright MCPまたはDevTools MCP
• 証跡のバンドルとPRレビュー → ProofShot
• ブラウザ操作のみ（録画・検証を自分で組みたい） → agent-browser単体

OpenHandsのようなAIコーディングエージェントと組み合わせれば、コード生成 → ブラウザ検証 → PRアップロードまでを自動化できる。Browser Useとも役割が補完的で、エージェント側のブラウザ操作ライブラリがProofShotの入力源になる構図だ。

主要コマンドリファレンスと実践的な使い方

ProofShotのCLIコマンドを用途別に整理する。よく使うのは start / stop / pr の3つだが、exec と diff を知っておくと回帰テストやセッションログ連携で効く。

proofshot start – 検証セッションの開始

proofshot start                                        # サーバーが既に起動している場合
proofshot start --run "npm run dev" --port 3000         # サーバーを起動してログもキャプチャ
proofshot start --description "Verify checkout flow"    # レポートに説明を追加
proofshot start --url http://localhost:3000/login       # 特定のURLを開く
proofshot start --headed                                # ブラウザを表示（デバッグ用）
proofshot start --force                                 # 前回クラッシュの残りセッションを上書き

--run オプションが特に便利だ。開発サーバーの起動とログキャプチャを同時に行えるため、サーバー側のエラーも見逃さない。Next.jsのビルドエラーやRails側の500エラーもまとめて server.log に集約される。

proofshot stop / exec / diff / pr / clean

# セッション停止
proofshot stop              # セッション停止してブラウザを閉じる
proofshot stop --no-close   # セッション停止、ブラウザは開いたまま

# agent-browserへのパススルー（セッションログに自動記録）
proofshot exec click @e3
proofshot exec screenshot step-checkout.png

# ビジュアル差分（回帰テスト用）
proofshot diff --baseline ./previous-artifacts

# PRへのアップロード
proofshot pr              # 現在のブランチからPRを自動検出
proofshot pr 42           # 特定のPR番号を指定
proofshot pr --dry-run    # Markdownをプレビュー（投稿はしない）

# アーティファクトの削除
proofshot clean

proofshot pr は特筆すべき機能だ。現在のブランチで記録した全セッションを検出し、スクリーンショットと動画をアップロードし、フォーマット済みコメントをPRに投稿する。ffmpeg がインストールされていれば、WebM動画をMP4に自動変換するため、GitHubのコメント欄でそのまま再生できる。

ForgeCodeのようなターミナルベースのAIコーディングツールでも、シェルコマンドが実行できる環境であればProofShotを同様に利用できる。

サンプルアプリで試すProofShotの検証フロー

ProofShotのリポジトリには、実際に動作を確認できるサンプルアプリが3種類用意されている。ドキュメントを読むより、手元で1回動かしてみるのが最短ルートだ。

git clone https://github.com/AmElmo/proofshot.git
cd proofshot
npm install && npm run build && npm link

# サンプルアプリのセットアップ
cd test/fixtures/sample-app
npm install

サンプルアプリのディレクトリでAIエージェントを開き、以下のようにプロンプトを入力する。

Verify the sample app with proofshot. Start on the homepage, check the hero section, navigate to the Dashboard and check the metrics, then go to Settings and update the profile name. Screenshot each page.

エージェントはスキルの指示に従って自動的に start → test → stop を実行する。生成されたアーティファクトを viewer.html で開けば、動画とログが同期再生される。

エージェントなしで自動テストスクリプトを実行することも可能だ。ProofShot自体の挙動確認やCI検証には、こちらの方法が手早い。

bash test-proofshot.sh

test/fixtures/ には3種類のサンプルアプリが含まれている。

実行後、proofshot-artifacts/ ディレクトリに動画・スクリーンショット・レポートが生成される。READMEにはGIFでデモが貼られているため、期待される出力との比較も容易だ。

導入前後のレビューフロー比較

ProofShotの導入により、AIエージェントが生成したUIの検証フローが根本的に変わる。特にリモートチームやオープンソースプロジェクトでは、PRレビュアーがローカル環境を構築せずに検証結果を確認できる点が大きい。

「手元で動かす前提」から「PRを開くだけで動画で確認できる」に変わる。この一歩が、AIエージェントによるPRを量産できるかどうかの分岐点になる。

導入前のレビューフロー:

1. エージェントがコードを生成
2. 人間がローカルでサーバーを起動
3. ブラウザで手動操作して目視確認
4. 問題があればエージェントに修正を依頼
5. 再度手動で確認（繰り返し）

ProofShot導入後のレビューフロー:

1. エージェントがコードを生成
2. エージェントが proofshot start → テスト → proofshot stop を自動実行
3. 人間は viewer.html または PRコメントで動画とログを確認
4. 問題があればエージェントに修正を依頼（証跡付き）

手動でブラウザを開いて操作する必要がなくなり、レビュー時間が大幅に短縮される。特にリモートワークやCI/CD環境では、PRに証跡がインラインで付与されることで、レビュアーがローカル環境を構築せずに検証結果を確認できる点が大きなメリットだ。

「レビュアーがリポジトリをcloneしなくても、PRコメントの動画を再生するだけで検証が終わる」——この状態がProofShotの目指すゴールだ。

ライセンス・拡張性・今後の位置づけ

ProofShotはベンダーロックインやクラウド依存がない。すべてローカルで完結し、MITライセンスで提供されている。エラー検出パターンの追加も src/utils/error-patterns.ts を編集するだけで対応可能だ。

エラーパターンを拡張すると、Next.jsの特殊なビルドエラーや、Rails/Djangoの例外スタックトレースも自動検出対象にできる。以下はエラーパターン拡張のミニマルな例だ。

// src/utils/error-patterns.ts (抜粋)
export const ERROR_PATTERNS = [
  { name: "JavaScript",  pattern: /Uncaught (?:Type|Reference|Syntax)Error/ },
  { name: "Python",      pattern: /Traceback \(most recent call last\)/ },
  { name: "Ruby",        pattern: /\(.*Error\).*\n.*from/m },
  { name: "Next.js RSC", pattern: /Error: React .*? Server Components/ },
  // 独自のエラーパターンを追加
  { name: "MyApp",       pattern: /\[MyApp\] fatal:/ },
];

AIコーディングエージェントの活用が広がるなか、生成されたコードの品質検証は今後さらに重要になる。単に「動くコード」を書くだけでなく、「動いている証拠」をPRに残すことが標準的な期待値になりつつある。ProofShotは、その検証プロセスを自動化・標準化する実用的な選択肢だ。

📌 まとめ

ProofShotは、AIコーディングエージェントの「目が見えない」という根本課題に、動画とログのバンドルで答えを出したCLIツールだ。Playwright MCPやDevTools MCPのような制御ツールの代替ではなく、その上に重ねる検証レイヤーとして設計されている点が重要で、既存のエージェント環境を壊さずに導入できる。

• 1コマンドで導入：npm install -g proofshot と proofshot install だけ
• 3ステップワークフロー：start / test / stop でエージェントが自動実行
• PRレビューの革命：proofshot pr で動画・ログ・エラーをPRコメントに投稿
• ローカル完結：MITライセンス・クラウド送信なし・オンプレ可
• 拡張しやすい：エラーパターンは TypeScript 1ファイルで編集可能

AIエージェントによるコード生成を本番運用に乗せたい開発者は、まずサンプルアプリで1回録画を回してみるとよい。viewer.html を開いた瞬間に、このツールが何を解決しているかが体感できる。

参照ソース

• ProofShot GitHub リポジトリ
• agent-browser（Vercel Labs）
• ProofShot npm パッケージ
• ProofShot error-patterns.ts（エラー検出パターン）