UIリファレンスキャプチャ
コードは構造、スタイル、文字列、アイコンを提供します。しかし、ランタイムで何が起こるか(バックエンドが何を返すか、どの順序で表示されるか、実際のアプリがどのくらい待つか)は提供せず、他社のUIについても何も語りません。このスキルは、固定された優先順位に従ってリファレンスでこれらのギャップを埋めます。決して誰かの個人ブラウザで即興で操作することはありません。
この最後のルールには経緯があります。このスキルの元となったプロダクションでは、エージェントがレビューアのログイン済みブラウザにアクセスしてライブアプリをキャプチャすることが許可されていました。ライブフローはハングし、エージェントはレビューアが停止を指示した後も「クリーンアップ」ステップを続け、テストワークスペースに不要なアイテムを残し、セッションは約68分後に何も使えるものが構築されずに悪い形で終了しました。同じキャプチャは後でセッションのトランスクリプトから数分で復元されました。まずオフラインリファレンス、ブラウザはユーザーが明示的に要求し、孤立した環境でのみ使用し、停止が指示されたらすぐに停止します。
格納場所
- 入力(レコーディング、エクスポート、ユーザーが提供したスクリーンショット):到着次第、
products/<slug>/references/<name>/にコピーします。ダウンロードフォルダとOSの一時キャプチャフォルダはクリーンアップされます。元のプロダクションでは、あるレコーディングはシステムが削除するはずだったフォルダにありました。macOSのレコーディング名には、AM/PMの前に狭い改行なしスペース(U+202F)が含まれています:名前を入力するのではなく、globで検索してください。 - 作業材料(数千のフレーム、復元されたキャプチャ、生のOCR):すべてのリポジトリの外にあるスクラッチフォルダ(例:
$TMPDIR/pvs-<slug>-<name>/)。 - 保存する価値のある結果(OCRタイムライン、実際のデータを切り取ったキーフレーム、分析):
references/<name>/に保存し、SOURCES.mdから引用します。
実際のワークスペースのレコーディングとキャプチャには、実際の顧客名、メールアドレス、電話番号、内部ID、他のユーザーの会話が含まれます。これらはworkbenchリポジトリに決して入れず、ビデオにも表示しません:セクション1のステップ6に変更が必要なものをリストしています。
テクニックの選択
| 持っているもの | テクニック | 読むもの |
|---|---|---|
| プロダクトの画面録画 | 1. 録画を分析する | references/recording-analysis.md |
| アプリを見た過去のセッション | 2. トランスクリプトからキャプチャを復元する | このファイル、セクション2 |
| ローカルで実行できるアプリ | 3. 本番環境と同様にビルドしたローカルインスタンス | references/local-instance.md |
| 他社のプロダクト | 4. Web調査、公開ソースのみ | references/third-party-ui-prompt.md |
| 何もない(電話、エンドカード、生成テキスト) | キットからデザインし、マークする | product-truth (mock) |
この順序で試してください。誰かに録画を依頼する前に、セクション2を確認してください:キャプチャがすでに存在する可能性があります。4つのうちどれも機能しない場合は、その旨を伝えてください。レビューアのブラウザにフォールバックしないでください。
1. 画面録画を分析する
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/ui-reference-capture/scripts"
W="$TMPDIR/pvs-acme-board" # スクラッチ、リポジトリ外
bash "$S/frames.sh" references/board/rec.mov "$W" --fps 10 --logical-width 1440
bash "$S/ocr.sh" "$W/logical" "$W/ocr.jsonl" # macOSのみ
"$PVS_HOME/bin/pvs-py" "$S/ocr_events.py" "$W/ocr.jsonl" references/board/ocr-timeline.txt --fps 10 \
--region "panel=0.6,0,1,[email protected]"
"$PVS_HOME/bin/pvs-py" "$S/grid.py" sheet "$W/overview.png" "$W/logical" --every 20 --cols 4
frames.shは小さなサムネイル(変更検出用)と、アプリの論理幅(Retina録画は2x:論理幅はピクセル幅の半分)のフレームを書き出します。これにより、1フレームピクセルは再構築されたアプリの1CSSピクセルになります。ocr.shはocr.swift(Apple Vision)をキャッシュフォルダに一度コンパイルし、フレームごとに1行のJSONを書き出します。Linuxでは「unsupported」で終了します:代わりにコンタクトシートを読んでください。ocr_events.pyはフレームごとのOCRを安定したスパンstart-end [region] textに変換します。このタイムラインは、実際のアプリが表示する正確な文字列とそのタイミングを提供し、ビデオを目で推測するよりも優れています。grid.py sheetはコンタクトシートを作成します:2秒ごとの概要、次にフェーズごとに10fpsの高密度シート。grid.py overlayは測定のためにフレームに論理ピクセルグリッドを描画します。- キーフレームを
references/<name>/frames/<t>-<state>.jpgとして保存します(実際のデータは切り取ります)。 references/<name>/analysis.mdをreferences/recording-analysis.mdの構造で書き込みます:正確な文字列を含む実際のタイムライン、測定されたモーション(パネルが開くまでの時間、カーソルが止まる時間)、「ビデオのため変更必須」テーブル(実際の名前、メール、電話、ワークスペース、内部ID、長い待機時間、DockなどのOSクローム)、および誰かがそれらの上に構築する前に提起すべきプロダクトギャップ(ストーリーに必要なステップが録画で失敗していることを示す)。
録画は待機時間を圧縮することでギャップを隠します。短縮したすべての待機時間を記録してください。
2. 過去のセッションからキャプチャを復元する
Claude Codeセッションでツールが返したすべての画像(ブラウザスクリーンショット、ウィンドウキャプチャ、読み込んだ画像)およびチャットに貼り付けられたすべての画像は、そのセッションのJSONLに保存されています。
"$PVS_HOME/bin/pvs-py" "$S/recover_transcript_images.py" ~/.claude/projects/<project>/<session>.jsonl \
[--from-line N] [--tool screenshot]
出力フォルダを指定しない場合、新しい一時フォルダに書き出し、gitワークツリー内のフォルダは拒否します。これらのキャプチャは実際のアカウントを示しているためです。index.tsv(ファイル、時刻、ツール、入力)を書き出すので、必要な画面を見つけることができます。コンタクトシート(grid.py sheet <out> <dir> --labels name)でレビューし、実際のデータを切り取ったクリアされたものだけを references/<name>/ にコピーします。元のプロダクションでは、1本のビデオ全体が117枚の復元画像とコードから構築されました。
3. 本番環境と同様にビルドしたローカルインスタンス
アプリがユーザーのマシンで実行できる場合の最も信頼性の高いリファレンス:本番コミットから本番ビルド引数でビルドし、架空のデータでシードし、すべての共有システムから隔離し、ヘッドレスブラウザでキャプチャします。開始する前に references/local-instance.md を読んでください。ユーザーは自分のアプリを実行することに同意する必要があり、ユーザーのアカウントや共有データベースは決して使用しません。
4. サードパーティUI
他社の画面については、references/third-party-ui-prompt.md を使用して調査サブエージェントを起動します:公開ソースのみ(公式ドキュメント、ヘルプセンター、プレスキット、マーケティングスクリーンショット、ベンダー所有の公開埋め込みデモ)、ログインは不可、送信や予約も不可、約30分。すべての値は、検証済み、測定済み、または推測済みとしてマークされて戻ってきます。プロダクトに独自のコンポーネントがある場合(チャットアプリのプレビューをレンダリングするプロダクトにはプレビューコンポーネントがあります。チャットアプリを再構築する代わりにそれを使用します)、それを優先します。サードパーティの画面全体は、実際の統合を証明する場合にのみ表示します。それ以外の場合は、プロダクト内でロゴとバッジを使用します。
パリティ:再構築が一致することを証明する
"$PVS_HOME/bin/pvs-py" "$S/pair.py" snapshots/nocam-12.4s.png references/board/frames/12.4-board.png \
640 40 1100 300 "$W/pair-board-header.png" --ref-scale 2 --logical-width 1440 --render-width 1920
カメラをスケール1でスナップショット(#camera{transform:none!important} を使用したコンポジションのコピー)を撮り、両方から同じ論理ボックスをクロップして、それらを重ねます。スクリプトはチャネルごとの平均絶対差を出力します。値が下がり止み、重ねた画像にオフセットがなくなるまで反復します。アプリのピクセルで測定し、明示的に変換します:スケールの混乱は誤った座標の繰り返し原因でした。
ルールとその理由
- 決してレビューアの個人ブラウザやプロファイルを使用しない、およびそこから取得したもの(フォント、アイコン、ストレージ)も使用しない。誰かが停止と言ったら、クリーンアップも含めてすべてのブラウザアクションを即座に停止する。
- 決してログインしない、トークンやブラウザストレージを読み取らない。 キャプチャにログインが必要な場合、その人は自分のセッションで自分のパスワードを入力するか、キャプチャは行われない。
- 復元および録画された素材はプライベートに保つ。 まず一時フォルダ、トリミングされたコピーのみ。
- すべての推測値をマークする。 半分が推測されたリファレンスは、どの半分かを明示しなければならない。