ユーザーガイドのスクリーンショットの作成・更新をClaude Code + Playwright MCPで自動化した話
はじめに
担当しているプロジェクトのユーザーガイドを運用しています。UI刷新時に200枚以上のスクリーンショットを手動で撮り直す、という苦行を経験しました。さらに追い打ちをかけるように、多言語対応で英語版が追加され、スクリーンショットの枚数は2倍に。
Claude Code のカスタムコマンドと Playwright MCP を使って、スクリーンショットの撮影から画像加工、Markdownへの挿入まで自動化しました。
「スクリーンショットは載せない」という選択肢
そもそも、スクリーンショットを載せないことで解決しているサービスもありますよね。
- 「UIは頻繁に変わるので、テキストだけで説明します」
- 「最新の画面はログインして確認してください」
アジャイル開発で頻繁にUIが変わる中、ドキュメントのスクリーンショットをメンテナンスし続けるのは大変です。
でも、ユーザー目線で考えると、スクリーンショットがあるドキュメントは圧倒的にわかりやすいと思います。
「メニューを開いて設定を選択」と書かれていても、画像がないと「どこ？」となりがちですし、特に初めて使うユーザーにとって、画像は大きな安心材料になります。
スクリーンショットを載せたいけど、メンテナンスコストが高すぎて諦めている——そんな状況を打破するために、自動化に取り組みました。
自動化してよかったこと
運用を始めてまだ日は浅いですが、すでに効果を実感しています。コマンドを実行したら別の作業をしている間に終わっています。終わったら結果を確認します。画像のスタイル（余白、枠線、ドロップシャドウ）も自動で統一されます。
手動撮影だと、変なところにフォーカスが当たっていたり、ブラウザを全画面にしたときの「全画面表示を終了するには Esc キーを長押しします」が写り込んでいたりして撮り直し、ということがよくありました。自動化すればフォーカス解除やUI準備も毎回同じ手順で実行されるので、こういったミスがなくなります。
おまけ：マニュアル用のテストデータも作れる
Playwright でブラウザを操作できるということは、スクリーンショット撮影用のテストデータも自動で作れるということです。
例えば「データが3件登録された一覧画面」のスクリーンショットを撮りたい場合：
- データを3件作成（Playwrightでフォーム入力→保存を3回）
- 一覧画面に移動
- スクリーンショット撮影
これも全部自動です。手動でテストデータを用意する手間がなくなりました。
Claude Code + Playwright MCP による自動化
事前準備：Playwright MCP のセットアップ
Playwright MCP は、
AIアシスタントからブラウザを自動操作するための MCP（Model Context Protocol）サーバーです。
Claude Code の .mcp.json に以下の設定を追加するだけです。npx 経由で自動的にインストール・起動されるので、事前のインストール作業は不要です。
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@anthropic-ai/playwright-mcp@latest", "--headless"]
}
}
}
--headless を指定するとブラウザを非表示で実行します。ブラウザを表示して動作を確認したい場合は --headless を削除してください。
これで Claude Code から browser_navigate、browser_click、browser_screenshot などのツールが使えるようになります。
構成
Claude Code
├── カスタムコマンド（.claude/commands/*.md）
│ ├── refresh-screenshots.md # 既存画像の更新
│ └── capture-screenshots.md # 新規画像の追加
├── Playwright MCP（ブラウザ自動操作）
└── ImageMagick（画像加工）
自動化した作業フロー
以下の処理はすべてカスタムコマンド（.claude/commands/*.md）に記述します。サンプルは後述の「カスタムコマンドのサンプル」を参照してください。
1. ログインの自動化
// ログインページに移動（基本認証がある場合は URL に認証情報を含める）
playwright_navigate: url=https://{BASIC_USER}:{BASIC_PASS}@example.com/signin
// フォーム入力
playwright_type: ref=<メールアドレス入力欄>, text={LOGIN_EMAIL}
playwright_type: ref=<パスワード入力欄>, text={LOGIN_PASS}
playwright_click: ref=<ログインボタン>
認証情報はファイルに外出しして、コマンド実行時に読み込む設計にしました。
# .credentials
BASIC_USER=username
BASIC_PASS=password
LOGIN_EMAIL=user@example.com
LOGIN_PASS=password
2. 機密情報の自動マスク
メールアドレスなどの機密情報をスクリーンショット撮影前にJavaScriptでDOMを直接書き換えます。以下のコードをカスタムコマンドに記述しておくと、撮影前に自動で実行されます。
// メールアドレスをマスク
document.body.innerHTML = document.body.innerHTML.replace(
/[\w.-]+@[\w.-]+\.\w+/g,
'user@example.com'
);
手動でやっていた頃は、画像編集ソフトで黒い四角を重ねて隠していました。位置がずれたり、四角のサイズが揃わなかったり、地味にストレスでした。
DOMを書き換えてから撮影する方式ならマスクされた状態で撮影できるので後処理が不要です。
3. ヘッダー/フッター除去もできる
ナビゲーションヘッダーを含めたくない場合は、撮影前にDOMから削除することもできます。以下のコードをカスタムコマンドに追加します。
// ヘッダー・フッターを削除
const header = document.querySelector('header');
if (header) header.remove();
4. 画像加工もできる
撮影した画像に余白や枠線を追加したい場合は、ImageMagickなどのツールで加工できます。
私の環境では、既存のスクリーンショットと同じスタイル（白い余白、グレー枠線、ドロップシャドウ）を適用しています。
# トリム＋白い余白＋グレー枠線を追加
convert screenshots/{name}.png \
-trim +repage \
-bordercolor white -border 20x20 \
-bordercolor '#cccccc' -border 1x1 \
output.png
# ドロップシャドウを追加
convert output.png \
\( +clone -background '#00000040' -shadow 80x3+2+2 \) \
+swap -background white -layers merge +repage \
output.png
実際のコマンド実行イメージ
ユーザーガイドのリポジトリで Claude Code を開き、カスタムコマンドを実行します。
# 既存のスクリーンショットを更新（元の画像を参考に同じ画面を撮影）
/refresh-screenshots https://example.com/docs/user-guide/feature-a/
# 画像がないページにスクリーンショットを追加(リポジトリ内のソースコードを指定)
/capture-screenshots src/content/docs/user-guide/feature-b
ユーザーガイドのURLを渡すと、Claude Code がページ内の画像を分析し、同じ画面を撮影してリポジトリの画像ファイルを更新します。新規追加の場合は、ページの内容からどの画面を撮るべきか判断し画像を挿入します。フォームへの入力値もドキュメントの説明文から推測します。
カスタムコマンドの詳細
画像をどこに追加するか
新規追加の場合、以下の基準で「画像が必要なページ」を判定しています：
- UI操作キーワードを含む: 「クリック」「選択」「入力」「ボタン」などの記述がある
- 画像参照がない: Markdownに
` 形式）を特定
3. 各画像がどの画面のスクリーンショットか分析
### Step 2: ログイン・スクリーンショット撮影
認証情報は `.credentials` ファイルから読み込む。
playwright_navigate: url=https://{BASIC_USER}:{BASIC_PASS}@example.com/signin
playwright_type: ref=<メールアドレス入力欄>, text={LOGIN_EMAIL}
playwright_type: ref=<パスワード入力欄>, text={LOGIN_PASS}
playwright_click: ref=<ログインボタン>
# ビューポートを十分な高さに設定
playwright_resize: width=910, height=1400
# 対象画面に移動してスクリーンショット撮影
# 元の画像と同じ状態（フォーム入力値など）を再現
### Step 3: 画像の後処理
# トリム＋余白＋ドロップシャドウを追加
convert {撮影した画像} -trim +repage \
-bordercolor white -border 20x20 \
-bordercolor '#cccccc' -border 1x1 \
{出力先}
### Step 4: 元の画像を置き換え
撮影した画像で既存の画像ファイルを上書きする。
## 注意事項
- 元の画像と同じ状態を再現すること
- 機密情報（メールアドレス、ID等）は撮影前にマスクする
capture-screenshots.md（新規画像の追加）
---
allowed-tools: mcp__playwright__*, Bash(convert *), Bash(identify *), Bash(mkdir *)
---
# スクリーンショット追加
画像がないユーザーガイドページにスクリーンショットを追加します。
## 引数
- `$ARGUMENTS`: ユーザーガイドページのURL または ローカルファイルパス
## 画像が必要なページの判定基準
- **画像が必要**: UI操作手順、フォーム入力の説明、設定画面の解説
- **画像が不要**: 概念説明のみ、テキストベースのFAQ、リリースノート
## 実行手順
### Step 1: ページ内容を分析・スクリーンショット計画を作成
1. ページの内容を読み取り、どの画面のスクリーンショットが必要か計画
2. 計画をユーザーに提示して確認を取る
### Step 2: ログイン・スクリーンショット撮影
（refresh-screenshots.md と同様）
### Step 3: 画像の後処理
（refresh-screenshots.md と同様）
### Step 4: Markdownファイルを更新
計画した挿入位置に画像参照を追加:
## 注意事項
- フォームにはサンプルデータを入力してから撮影
- 機密情報は必ずマスクする
- 撮影後は画像を目視確認する
まとめ
スクリーンショットの管理は、ユーザーガイド運用において最も面倒で、かつミスが起きやすい作業の一つです。
Claude Code のカスタムコマンドと Playwright MCP を組み合わせることで：
- 撮影から加工まで自動化
- 画像スタイルの統一
- コマンド実行後は放置でOK
次にUIが刷新されても、もう怖くありません！
使用技術：
