Community画像github.com

before-after ビフォーアフター比較

現在のブランチがベースブランチに対して行ったすべての視覚的変更を、各変更画面・コンポーネント・状態をローカルビルドのベースとブランチから同一データ、ビューポート、テーマでキャプチャし、ピクセルチェックで実際に差分があることを確認した上で、テーブル形式の1枚の画像にまとめます。プルリクエストやレビュー、デザイナー向けのビフォーアフタースクリーンショット、ビジュアルディフ、スクリーンショット比較の依頼があった場合に使用します。画像のキャプチャと合成のみを行い、プロジェクトのコードは編集しません。

before-after ビフォーアフター比較 とは?

このスキル「before-after」は、Gitブランチ間の視覚的変更を自動でキャプチャし、比較画像を生成するClaude Code向けのツールです。ユーザーが「ビフォーアフターのスクリーンショット」「ビジュアルディフ」「変更点の画像」などを要求した際に、両ブランチをローカルビルドし、同一条件(データ、ビューポート、テーマ)で各画面・コンポーネント・状態をスクリーンショットとして取得。ピクセル単位の差分チェックを経て、1枚のPNG画像に表形式でまとめます。対応プラットフォームはCLIベースで、Claude Codeエージェントや同様のAIコーディングエージェント(Cursor, Codexなど)でスクリプトとして実行可能です。スクリプトは `scripts/capture.mjs` と `scripts/compose.mjs` の2つから構成され、ユーザーの `~/Documents/before-after/` ディレクトリに結果を出力します。スキルの品質は変更リストの網羅性に依存するため、差分のトレースから共有コードの影響範囲調査、データ状態やインタラクション状態の網羅、モックデータの利用、トリミングサイズの最適化など、細かなガイドラインが定義されています。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MagnusBrogie/agent-skills/tree/HEAD/before-after

Installed? Explore more 画像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

ビフォーアフター比較

1枚のPNG画像を生成します。各行に視覚的な変更の名前、1行のメモ、ベースのスクリーンショット、ブランチのスクリーンショットを並べた表です。コードを見ていない人でも、その画像だけで何がどのように違うかを理解できるようにします。

画像の品質は変更リストの網羅性に依存します。5つの変更のうち3つしか表示しなかったり、コードによる差分ではなく異なるデータに起因する差分を表示したりすると、読者を誤解させます。作業のほとんどは、すべての視覚的変更を見つけ出し、コードのみが異なる状態で各ペアをキャプチャすることです。

画像の保存場所。 このスキルが生成するすべてのファイルは、ユーザーのDocumentsフォルダ ~/Documents/before-after/<リポジトリ>/<ブランチ>/ に保存されます。ショット、マニフェスト、shots.mjsのコピー、最終的な before-after.png が含まれます。スクリプトはこのフォルダを自動的に選択し、出力パスは受け取りません。ユーザーが ~/Documents/before-after 以外のルートを希望する場合は、BEFORE_AFTER_DIR 環境変数を設定します。これはユーザー自身が設定するものであり、あなたが設定するものではありません。画像は他の場所に書き込まないでください。また、後で移動したりコピーしたりしないでください。スクラッチパッドはベースのワークツリーと shots.mjs のドラフトのみに使用します。同じブランチで後日実行する場合、そのフォルダは再利用されます。

このファイルと同じ scripts/ ディレクトリに2つのスクリプトがあります。capture.mjs がショットを撮影し、compose.mjs が表を構築してチェックします。各スクリプトのヘッダに入力形式が記載されています。開始する前に両方のヘッダを読んでください。

ローカルノート。 このファイルと同じ場所に LOCAL.md というファイルがある場合は、開始する前に読んでください。そこにはユーザーが自身のプロジェクトで使用するデフォルト設定(コマンド、ホスト、アカウント、パス)が記載されており、公開スキルの一部ではありません。そのファイルが対象プロジェクトに関連する場合は、プロジェクトの指示の一部として扱います。関連しない場合は無視してください。

1. 変更を収集する

ベースブランチが指定されていない場合は、プルリクエストのベース(gh pr view --json baseRefName --jq .baseRefName)、次にデフォルトブランチ(git symbolic-ref --short refs/remotes/origin/HEAD)、最後に origin/main を使用します。リモート追跡参照を優先します。未コミットの作業も含めます。

base=$(git merge-base <base> HEAD)
git diff --stat "$base"; git diff "$base"; git status --short   # 追跡されていないファイルも読み込む
git log --oneline "$base"..HEAD

プルリクエストの説明と課題(issue)も、もしあれば読んでください。変更がどの画面を対象としているかが記載されていることが多く、人々が見ると予想するスクリーンショットが含まれていることもあります。

2. すべての視覚的変更をリストアップする

各差分ハンクを、ユーザーが目にするものまで外側にたどっていきます。

  • コード、スタイル、トークン、アイコン、コピー、翻訳を確認する。 これらのそれぞれが候補となります。共有コード(UIコンポーネント、フォーマットヘルパー、CSSトークン)の場合は、その呼び出し元を検索し、それをレンダリングするすべての画面をリストアップします。共有コードの変更は、通常、ブランチが対象とした画面よりも多くの場所で見られることがあります。
  • データ状態。 各画面について、変更されたコードが分岐する各パス(ロード済み、ロード中、空、エラー、値欠落、ゼロと負、長いテキスト、1項目と多数、各モードや設定)を確認します。差分によってレンダリングが変更される状態のみを保持します。
  • インタラクション状態。 ホバー、フォーカス、押下、無効、選択済み、ポップオーバー、メニュー、シート、ダイアログのオープン状態、バリデーションエラーを表示しているフィールドなど。これらはショットの前にステップが必要です(ステップ4)。
  • ブランチで追加または削除された画面。 これらは片側のみの画像になります。行にはもう片方のプレースホルダーが表示されます。
  • プロジェクトがサポートする環境。 変更が異なって見える可能性があるもの(ダークテーマ、モバイルとデスクトップの幅、別のロケール)。

候補を3つのリストに分類します。

  1. 視覚的: 画面に何か違いがあるもの。これらが行になります。
  2. 非視覚的: アクセシビリティツリー、属性、スクリーンリーダーのみのテキスト、動作、コード構造のみに影響する変更。これらは行になりません。レポートに名前を記載し、検討されたことと見逃されていないことを読者が理解できるようにします。ユーザーがそれでも表示を希望する場合は、アクセシビリティツリーの抜粋を画像としてキャプチャし、そのようにラベル付けした行を追加できます。
  3. 不明: 見えないはずだが、何かを移動したり色を変えたりする可能性があるマークアップやクラスの変更(新しいラッパー要素、ポジショニングクラス、入れ替えられたヘルパー)。これらはキャプチャし、ピクセルチェックで判断します。

動き(アニメーション、トランジション、そのタイミング)の変更は静止画像で表示できません。「表示されないもの」としてレポートに記載し、確認方法を説明します。

行を適切にグループ化します。呼び出し元サイトごとではなく、異なる見た目ごとに1行とします。10の画面が同じセルの変更を同じ方法で使用している場合は、そのうちの1つか2つを表示し、残りはメモに名前を記載します。誰かが実際に読むであろうテーブルを目指します。約12行を超える場合は、領域ごとに2番目の画像を作成し、そのように通知します。

視覚的リストと不明リストが両方とも空の場合、ここで停止します。 ユーザーにブランチに視覚的変更がないことを伝え、検討した内容と各項目が視覚的でない理由をリストアップし、画像は生成しません。不明な項目のみがあり、すべてのペアが同一であることが判明した場合も結果は同じで、同一のペアが証拠となります。チェック済みで変更なしとして報告します。

3. ベースとブランチをローカルでビルドする

両側をローカルビルドからキャプチャします。デプロイ環境からは決してキャプチャしないでください。デプロイ環境はワーキングツリーより遅れており、未コミットの作業を表示できません。

  • ブランチ: 最後の変更後の現在のワーキングツリー。

  • ベース: マージベースの別のワークツリー。ユーザーのワーキングツリーには決して触れません。ユーザーのチェックアウトでブランチを切り替えたり、スタッシュしたりしないでください。

    git worktree add --detach <scratchpad>/before-after-base "$base"
    

    そこに依存関係をインストールします。メインチェックアウトの依存関係ディレクトリへのシンボリックリンクは、差分がロックファイルに触れていない場合のみ問題ありません。作業が終わったらワークツリーを削除します(git worktree remove)。

プロジェクトの文書化されたコマンド(README、AGENTS.md、CLAUDE.md、開発ドキュメント、runスキルがあればそれも)を使用します。両側とも同じステージングまたはテストバックエンド、決して本番環境には接続しないでください。どのコマンドがどのバックエンドを対象としているか不明な場合は、ビルド設定を読み、それでも疑問が残る場合は停止して質問してください。キャプチャする前に、各側からの実際のAPIリクエストのホストを確認します。

プロジェクトのプロダクションビルドを静的に配信する方法(buildに続けてpreviewまたは任意の静的サーバー)を、開発サーバーよりも優先します。開発サーバーはホットリロードクライアントとオーバーレイを追加し、ワークツリーごとにウォッチャープロセスが必要になる場合があり、出荷時とは異なるレンダリングになる可能性があります。プロジェクト自身のビルドコマンドではないツールでビルドする場合は、ページがレンダリングされることを確認します。プロジェクトはバンドルを後処理する場合があります。ビルドはユーザーのワーキングツリー内の出力ディレクトリを空にしたり上書きしたりする可能性もあります。これらは生成されたファイルですが、何を再ビルドしたかをレポートに記載し、ビルドが削除したものを開発セットアップが期待する状態に戻します。

キャプチャを信頼する前に、2つのビルドが異なることを確認します。各側の変更された要素のマークアップを読み、その差分の中に変更が見られることを確認します。同じコードを配信する2つのサーバーは、何も証明しない同一のペアを生成します。

2つのビルドをどのように提供するかを選択します。

  • 両方を同時に、2つの空きポートで。 これが最も簡単で、ペアの2つのキャプチャは数秒間隔で取得されます。ログインが不要な画面、またはポート変更後もログインが維持される場合に機能します。Cookieは同じホスト上のポート間で共有されますが、ローカルストレージは共有されず、バックエンドが特定のオリジンのみを受け入れる場合があります。2番目のポートでログイン済みの画面が実際に読み込まれることを確認してから、それに依存します。
  • 同じポートで順番に。 プロジェクトの通常のポートでベースを提供し、--side=before でキャプチャし、停止し、そのポートでブランチを提供し、--side=after でキャプチャします。保存されたログイン状態と許可されたオリジンは両方に適用されます。キャプチャは数分間隔になるため、データはモック化するか、安定していることが分かっている必要があります。

プロジェクトにコンポーネントカタログ(Storybook、「workshop」アプリなど)があり、変更が共有コンポーネントに存在する場合、フルアプリよりも安価で安定してキャプチャでき、通常はログインも不要です。それでも、可能な限り変更ごとに少なくとも1つの実際の画面をキャプチャし、画像がコンテキスト内で表示されるようにします。実際の画面に到達できない場合(テストログインがないなど)、「表示されないもの」の下にその旨を記載します。

4. 同一条件下で各ペアをキャプチャする

スクラッチパッドに shots.mjs を、scripts/capture.mjs のヘッダで指定された形式で書き、プロジェクトルートから実行します。Playwrightが解決され、出力フォルダが正しいリポジトリ名とブランチ名を取得するようにします。

node <this skill>/scripts/capture.mjs <scratchpad>/shots.mjs --before=http://localhost:<p1> --after=http://localhost:<p2>

スクリプトは両方のURLに対して同じ手順を実行します。インストールされたChrome、デバイススケールファクター2、モーションの軽減を使用します。トランジションをオフにし、無限アニメーション(きらめき、スピナー)を最初のフレームにリセットして有限のアニメーションを完了させ、フォントとネットワークの安定を待ち、時間を指定すれば時計をフリーズします。上記のDocumentsフォルダに shots/<スラッグ>.before.png、shots/<スラッグ>.after.png、および manifest.json(ステップ5用)を書き込み、shots.mjs をコピーし、フォルダのパスを最後の行として出力します。--only=<スラッグ> で1行だけ再キャプチャします。失敗したショットは、ページの代わりに表示されたもののビューポート全体の <スラッグ>.<サイド>.FAILED.png を残します。

プロジェクトのエンドツーエンドセットアップに保存されたログイン状態がある場合は、storageState として渡します(プロジェクトのドキュメントで作成方法を確認してください)。Orcaでは、埋め込みブラウザ(orca-cliスキル)も1~2ペアのキャプチャに機能しますが、スクリプトによってペアが再現可能になります。

shots.mjs で正しく設定する必要がある項目:

  • 両側で同じデータ。 ライブデータは2回のキャプチャの間で変動します。価格は変動し、リストは並び替えられます。ショットの mock で画面が依存するレスポンスをモック化することを推奨します。ステージングから1つの実際のペイロードをキャプチャし、両側でそれを fulfill します。2つの制限があります。
    • ブランチがリクエストまたはレスポンスの形式を変更する場合(新しいエンドポイント、新しいフィールド、変更されたデコーダー)、1つのペイロードで両側を提供できません。各側に、そのコードが期待するペイロードを、同じ基礎値から構築して提供し、その旨をサブタイトルに記載します。
    • WebSocketまたはサーバー送信イベント(SSE)で到着するデータは、page.route では処理されません。page.routeWebSocket を使用するか、ストリームが静かな画面や時間を選ぶか、対象でない場合はライブ要素を非表示にします。
  • 意図的に状態に到達する。 ローディング、エラー、値欠落の状態はテストアカウントではほとんど発生しません。mock で生成します(レスポンスを遅延させる、失敗させる、フィールドをnullにする)。リクエストパスとフィールド名は、推測ではなくコードから導出します。steps でインタラクション状態に到達します(ホバー、フォーカス、クリックして開く)。
  • コンテキストを含めて変更部分にトリミングする。 target は、変更が表示され、かつ画面の一部として認識可能な最小の要素に設定します。カード、テーブル、シートなど、ページ全体ではありません。最大でも約650 CSS px幅のトリミングを目指します。これがフルサイズで横に並ぶのに適した幅です。より広いトリミングは縦に積み重ねられ(ビフォーが上、アフターが下)、約1300 CSS pxより広いと縮小されるため、テキストが読みにくくなります。両側で同じターゲットを使用して、トリミングが揃うようにします。
  • 対象ではなく動き続ける要素(ティッカー、時計、遅れて読み込まれるアバター)は、両側の steps でスタイルタグを使用して非表示にします。

5. 合成とチェック

node <this skill>/scripts/compose.mjs <folder>/manifest.json [--diff] [--stack]

画像はマニフェストの隣に before-after.png として書き込まれ、そのパスが出力の最後の行になります。--diff は、変更されたピクセルをマゼンタで表示した画像を行ごとに追加します。変更が小さいか微妙な場合(スペーシング、色、1グリフ)に使用します。変更が明らかな場合は省略します。行の2つのショットのサイズが異なる場合、比較は左上隅で位置合わせされるため、シフト以降のすべてが変更されたとみなされます。行はその旨を通知し、その場合の差分画像は大まかなガイドとしてのみ機能します。

スクリプトは、行の両方のショットを同じスケールで描画します。行ごとの変更ピクセルの割合と各レイアウト方法を出力し、ペアが同一の場合はコード3で終了します。その後:

  1. 同一のペアは、キャプチャが変更を逃した(間違った状態、間違った画面、キャッシュ、実際にはベースではないベースビルド)か、変更が視覚的でないことを意味します。原因を特定します。キャプチャを修正するか、マニフェストから行を削除し、その項目を「チェック済み、ピクセル差なし」として非視覚的リストに移動します。同一ペアの行を絶対に出荷しないでください。
  2. 画像を確認し(PNGを読み取る)、各行をチェックします。見える違いがメモに記載されたものであり、それ以外に何も異なっていないことを確認します。差分で説明できない違い(異なる価格、行の欠落、他の場所でのレイアウトのずれ)は、データの変動または予期しないリグレッションです。再キャプチャするか、ユーザーにリグレッションの可能性として報告します。隠してはいけません。
  3. すべてのショットのテキストが読めることを確認します。 スクリプトからの「テキストが読めない可能性があります」という警告に対しては、より狭くトリミングし、--only を使用してその行を再キャプチャします。
  4. 画像が非常に長い場合は、領域ごとに分割します。ブランチのフォルダ内に領域ごとにサブフォルダを作成し、各サブフォルダに独自の manifest.json(パスは ../shots/... を指す)を配置し、それぞれを合成します。

6. レポート

ユーザーに以下を提供します。

  • PNGの完全な絶対パス。
  • 各行を1行ずつ。
  • 表示されないもの: 非視覚的変更、ピクセルチェックで変更なしと判断された不明な項目、モーションの変更、キャプチャできなかった視覚的変更(とその理由)、表示された行の重複として省略された呼び出しサイト。
  • ピクセルチェックまたは自身の目視で見つかった予期しないもの。
  • ペアがどのように生成されたか(実際のステージングデータ、またはモック化されたレスポンス。カタログか実際のアプリか)。これにより、読者は画像が何を証明しているかを理解できます。

起動した開発サーバーを停止し、ベースのワークツリーを削除します。ショット、shots.mjs のコピー、マニフェストは出力フォルダに残り、後日 --only を使用して1行だけを再キャプチャできるようにします。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

関連スキル