workflow-progress-screenshots

ワークフロー：進捗スクリーンショット

ユーザーは見た目で成果を判断するため、ほとんどすべてのスレッドでスクリーンショットを求めます。

• 「スクリーンショットを引き続き送ってください」
• 「各パスでスクリーンショットを送ってください」
• 「それらのスクリーンショットを見せてもらえますか？」
• 「まだスクリーンショットが見当たりません。どこにありますか？」

変更内容の説明は、実際に見せることとは違います。スクリーンショットに言及しても、送らなければ送ったことにはなりません。

ルール

1. 説明するのではなく、送ってください。 ホストのファイル送信ツール（SendUserFile、またはレポートへの画像のインライン挿入）を使い、ユーザーの目の前に画像を表示してください。文章にパスを書くだけでは不十分です。

2. 求められる前に、作業を進めながら送ってください。 ユーザーが早い段階で方向修正できるよう、意味のあるパスのたびに画像を送ってください。

   • 最初に動作するバージョン；
   • 大きな修正のたび；
   • スコアリングループを回すたび。

   すべてを最終レポートまで取っておかないでください。ただし、送りすぎにも注意してください。保存のたびではなく、各パスにつき小さな一式にしてください。

3. 開始時、重要な場面、結果を撮ってください。 変更に変更前と変更後がある場合は、同じフレーミングで次の3枚を撮影してください。変更前の状態、操作中（ホバー、照準中、アニメーションの途中、パネルが開く場面など）、そして結果です。修正の場合は、バグと修正後の状態を見せてください。

4. 実際のレンダリングだけを使ってください。 モックアップやイメージではなく、実際のページ、ゲーム、アプリを撮影してください。レビュー用フィクスチャ、URL フラグ、デバッグフックを使って状態を設定し、説明だけで済ませないでください。

5. 送信前に画像をすべて確認してください。 次のような場合は撮り直してください。

   • 余計なトーストやホバーピンがある；
   • アートの読み込みが途中、またはフォントが欠落している；
   • シーンが違う、または数値が古い。

   キャプションの内容が画像に写っていない場合、それは証拠になりません。

6. 画像が何を証明するか、キャプションに書いてください。 画像1枚につき1行で、何が変わり、何を確認できるかを示してください。例：「変更前：ヒントは『範囲外』と表示。変更後：『命中率90％・5ダメージ』と表示。」

7. 正確にラベル付けしてください。 「ヘッドレスブラウザーでのキャプチャ」または「ブラウザーのビューポート」と明記してください。390×844 のビューポートは、スマートフォンサイズのブラウザーチェックであり、端末でのテストではありません。スクリプトによる場面や演出された瞬間は、その旨を記載してください。

8. 比較には同じフレーミングを使ってください。 変更前と変更後で、同じビューポート、カメラ、状態を使ってください。compare.py で横に並べてください。

キャプチャ方法

• アプリ内ブラウザーペインは、表示中であれば使用できます。非表示のペインでは requestAnimationFrame が停止し、古いフレームや黒いフレームが返るため、その場合はヘッドレスキャプチャを使ってください。
• ヘッドレス： scripts/capture.mjs <url> <out.png> を使い、WIDTH／HEIGHT、MOBILE=1、WAIT_FOR="<ready expression>"、SETTLE=<ms>、クリック、オープン、スクロールを行う JS ステップを指定します。ページのエラーが出力されるため、壊れたページを撮影してしまわずに済みます。
  • デスクトップは 1600×900、スマートフォンサイズのビューポートは MOBILE=1 で 390×844 にします。
  • WebGL または 3D シーンでは SETTLE=3000～5000 にします。ヘッドレスではレンダリングに時間がかかり、早すぎる撮影ではモデル、フォント、アイコンが写りません。
  • キャプチャは一度に1つずつ実行してください。負荷の高いマシンでヘッドレス Chrome を並列実行すると、プロトコルエラーやフレームの取りこぼしが発生します。
• 横並び比較： scripts/compare.py out.jpg before.png "Before" after.png "After" を使うか、開始時、重要な場面、結果の3パネルにします。
• 動き： 静止画では動きがわかりません。エフェクト中の短い連続フレームを撮影し、アプリでページの時計を操作できる場合は遅くしてください。または、フレームを並べた画像を送ってください。
• プロジェクトで特定のキャプチャツール（たとえば「Codex browser を使う」）が指定されている場合は、それを使用してください。
• キャプチャスクリプトと出力は、アプリの再起動時に消去されるスクラッチパッドではなく、プロジェクト内の Git の無視対象フォルダー（qa/captures/ など）に保存してください。

最終レポート

• 変更内容の要約の後に、キャプション付きでスクリーンショットをそれぞれインライン表示してください。
• どの画像がヘッドレスキャプチャか、またスマートフォンでの確認にどのビューポートを使用したかを記載してください。
• キャプチャできなかったものがあれば、そのことと理由を記載してください。説明で代用しないでください。