Claude Codeにスクショを貼ってUIのバグを直す：Playwright MCPで「変更→確認」を回す実践

CSSのちょっとした崩れ、レスポンシブで折り返したボタン、ダークモードだけ読めなくなる文字色。こういう「見た目のバグ」は、テキストで説明するのが地味に面倒です。「ヘッダーの右上のアイコンが少し下にずれてて…」と打つより、スクショを1枚貼ったほうが伝わりやすい場面が多いです。

この記事では、Claude Code に スクリーンショット/画像を渡して見た目の崩れを伝える 方法と、Playwright MCP でブラウザを操作させて再現・確認させる やり方、そして両者を組み合わせた 視覚的な検証ループ（変更→スクショ→確認） を、実際のコマンド付きで整理します。

対象読者は、すでに Claude Code を使っているフロントエンド/Web開発者です。

1. なぜ「画像」がUIバグに効くのか

Claude Code はテキストだけでなく 画像を読める（マルチモーダル）。これがUIデバッグでは効いてきます。

• レイアウト崩れ・色・余白・はみ出しは、言葉より画像のほうが正確に伝わりやすい
• 「あるべき姿（デザインカンプ）」と「現状（実際の画面）」の2枚を並べて差分を説明させられる
• エラーダイアログやコンソールのスクショをそのまま読ませられる

ポイントは、画像はあくまで「現状の証拠」 として渡し、修正対象のコード（該当コンポーネントやCSS）も一緒に見せること。画像だけだと「どのファイルを直すか」までは特定しづらいので、ファイルパスやクラス名を添えると当たりが付きやすくなります（効果は対象アプリや構成により異なります）。

2. Claude Code に画像を渡す3つの方法

画像の渡し方は主に3つあります。

1. ファイルパスをプロンプトに書く（全プラットフォームで安定）
2. ドラッグ&ドロップ（全プラットフォームで動作）
3. クリップボードから貼り付け（環境依存・後述）

一番確実なのは パス指定 です。

./screenshots/header-broken.png を見てください。
スマホ幅(375px)でヘッダー右上のメニューアイコンが
ロゴと重なっています。src/components/Header.tsx の
レイアウトを直してください。

クリップボード貼り付けの注意点

クリップボードからの貼り付けは便利ですが、環境によって挙動が違う ので過信は禁物です（特定環境での断定ではなく、各環境で挙動差がある点に注意、という話です）。

• macOS: クリップボード貼り付けは比較的安定して動く（Ctrl+V）
• Windows / Linux: ターミナルの Ctrl+V は既定の動作とぶつかって無反応になりやすく、Claude Code 側では貼り付けに Alt+V が割り当てられています。それでも Win+Shift+S などで取った生のクリップボード画像はうまく渡せないことがあり、GitHub の Issue でも挙動が議論されています。ファイルに保存してパスを渡す/ドラッグ&ドロップが確実

迷ったら 「ファイルに保存してパスを書く」 に倒すのが、環境を問わず安定します。Windows なら、スクショをいったん screenshots/ フォルダに保存してパスで渡す運用が無難です。

3. Playwright MCP でブラウザを操作させる

「スクショを手で撮って貼る」のも手軽ですが、Claude Code 自身にブラウザを操作させて、再現と確認まで任せられる とループが締まります。これを担うのが Playwright MCP（Microsoft 公式の @playwright/mcp）です。

セットアップ

Claude Code への追加は1コマンドです。

claude mcp add playwright npx @playwright/mcp@latest

追加後、/mcp で接続状態を確認できます。

提供される主なツール

Playwright MCP には複数のブラウザ操作ツールが含まれます。UIデバッグでよく使うのは次あたりです。

• browser_navigate — URLを開く（例: localhost:3000）
• browser_snapshot — ページのアクセシビリティスナップショットを取得（要素の役割・テキストを構造化して返す）
• browser_take_screenshot — 画面/要素のスクショを撮る
• browser_resize — ビューポートサイズを変更（レスポンシブ確認に役立つ）
• browser_click / browser_type — クリックや入力で状態を再現

ここで設計上の特徴があります。Playwright MCP は 既定ではピクセルではなくアクセシビリティツリー（構造化データ）で動く という点です。browser_snapshot のドキュメント自身が「スクリーンショットより優れている（better than screenshot）」と述べているとおり、要素の特定や操作は基本スナップショット主体で、スクショは 人間/モデルが見た目を目視確認したいとき に使う、という棲み分けになります。

座標ベースのクリック（browser_mouse_click_xy など）はオプトインで、--caps=vision を付けたときだけ有効になります。通常は不要です。

4. 視覚的な検証ループ（変更→スクショ→確認）

ここが本題。バグ修正は 一発で直る保証がない ので、ループにするのが実践的です。

ループの基本形

1. localhost:3000/pricing を開いて(browser_navigate)
2. 幅375pxにリサイズして(browser_resize)
3. スクショを撮って(browser_take_screenshot)現状の崩れを確認
4. 原因のCSS/コンポーネントを直す
5. 同じ手順で再度スクショを撮り、直ったか確認
6. 直っていなければ4に戻る

これをそのままプロンプトとして渡せます。

Playwright MCP で http://localhost:3000/pricing を開いて、
ビューポートを 375x812 にリサイズしてスクショを撮ってください。
料金カードが画面からはみ出していたら、
src/styles/pricing.css を修正して、もう一度同じ条件で
スクショを撮り、はみ出しが解消したか確認してください。

Claude Code は browser_navigate → browser_resize → browser_take_screenshot を実行し、撮ったスクショを自分で読んで判断し、CSSを直してから再度撮影して比較する、という流れを回せます。「撮る」「直す」「また撮る」を本人にやらせるのがこのやり方の肝です（うまく回るかは対象画面の作りにもよります）。

「あるべき姿」を基準として渡す

デザインカンプがあるなら、それを基準画像として最初に渡すと判断の手がかりになります。

docs/design/pricing-mock.png が正しいデザインです。
現状(スクショ)と見比べて、余白・フォントサイズ・
カードの角丸が一致するように pricing.css を寄せてください。
変更ごとにスクショで差を確認してください。

状態を作ってから確認する

ホバー・モーダル・エラー表示など「操作しないと出ない崩れ」は、browser_click / browser_type で状態を作ってから撮らせます。

ログインフォームで空のまま送信ボタンを押して、
バリデーションエラーが表示された状態でスクショを撮ってください。
エラーメッセージが入力欄に重なっていないか確認します。

5. うまく回すためのコツと注意点

実際にやってみると詰まりやすいポイントがいくつかあります。

• dev サーバーを先に起動しておく。browser_navigate の前にアプリが立ち上がっていないとページが開けません。Claude Code に npm run dev を別途起動させるか、自分で起動しておく
• URLとビューポートを明示する。「スマホで崩れる」だけだと幅が曖昧。375x812 など具体値を指定すると再現が安定する
• スナップショットとスクショを使い分ける。要素の有無やテキスト確認は browser_snapshot（軽い・構造的）、見た目の崩れは browser_take_screenshot。なんでもスクショにすると無駄が多い
• 修正対象ファイルを指定する。画像だけだと直す箇所の特定がブレやすい。該当コンポーネント/CSSのパスを添える
• ループの終了条件を書く。「はみ出しが消えるまで」のように停止条件を明示すると、延々と微調整し続けるのを防ぎやすい
• クリップボード貼り付けに頼り切らない。前述のとおり環境依存。確実性重視ならパス渡し
• 認証が要る画面は、ログイン手順（操作）も Playwright MCP に踏ませるか、ログイン後のURLを直接開く必要がある

これらは環境やアプリ構成によって効き方が変わります（「必ずこうなる」というものではありません）。まずは小さい画面1枚から試すのがおすすめです。

まとめ

• 見た目のバグは 画像で伝える のが速い。渡し方は パス指定が最も安定（クリップボード貼り付けは環境依存）
• Playwright MCP を入れると、Claude Code が ブラウザを開く・リサイズする・スクショを撮る まで自走できる
• 変更→スクショ→確認のループを本人に回させ、「あるべき姿」の基準画像と修正対象ファイルを添えると当たりが付きやすい
• 要素確認は browser_snapshot、見た目確認は browser_take_screenshot と使い分ける

手で撮って貼るところから始めて、慣れたら Playwright MCP でループ化する、という順で導入すると無理がありません。

---

Claude Code をもっと活用したい人向けに、無料で使えるスキルを4つ公開しています（GitHub）。よければ覗いてみてください。
👉 https://github.com/noguso245-jpg/claude-code-skills-starter

Claude Code / AI開発まわりの発信は X @k___n___t_1125 でやっています。