argos-pr-review

Argos PR レビュー

Argos はビジュアルテストプラットフォームです。CI ビルドごとにスクリーンショットをキャプチャしてベースラインと比較し、スナップショットごとの差分を生成します。changes-detected のビルドは、人間（またはあなた）が各変更について、意図したものか、リグレッションか、不安定なキャプチャかを判断するのを待っています。

Argos のビルドは PR レビューの入力の一つとして扱い、唯一の判断材料にはしないでください。まず PR のタイトル、説明、リンク先のイシュー、コードの差分から意図された UI の変更を推測し、そのうえで Argos を使って、レンダリング結果がその意図どおりか確認してください。

ツールと認証

argos CLI を使って Argos を操作します。トークンの仕組みとフラグについては、argos-cli スキルを読み込んでください。簡単に言うと、build get／build snapshots にはプロジェクトトークン（ARGOS_TOKEN／--token）が必要です。レビューやコメントの投稿には個人アクセストークン（--token／argos login）が必要です。解析時には必ず --json を使い、トークンの値は絶対に表示しないでください。PAT を利用できない場合は投稿せず、結論と根拠をユーザーに提示してください。CLI からレビューを送信することはできません。

ワークフロー

1. ビルドを確認する — argos build get <ref> --json。ステータスから判断します。

   ステータス	意味／次の手順
   accepted / no-changes	すでに承認済み／ビジュアル差分なし — レビュー不要
   pending / progress	まだ準備できていません — いったん停止し、まだレビューできないことを報告します
   changes-detected	判断が必要です — スナップショットを取得します
   rejected / error / aborted/ expired	原因を理解するまでは承認しないでください

2. 変更点を取得する — argos build snapshots <ref> --needs-review --json。 各差分について、url（差分マスク）、base.url（変更前）、head.url （変更後）、head.metadata に加え、不安定さの兆候である test.metrics と、 変更がある場合は change.occurrences / change.ignored（手順 3 で使用）を確認します。

3. 推測した意図と照らして各差分を判断する：

   • 意図的な変更 — コードの変更内容に合致し、問題なくレンダリングされています。

   • リグレッション — レイアウトの崩れや重なり、クリッピング、状態／テーマ／ルートの誤り、コンテンツの欠落、または対応するテスト削除がないスナップショットの削除です。

   • 不安定なキャプチャ — 独立した 2 つの兆候を比較し、両者が一致する場合は、確度を示して不安定と判断します。

     • テスト履歴 — test.metrics.flakiness（0 は安定、1 は不安定）と change.occurrences（メトリクスの対象期間に、この同一の差分が再発した回数）。高い不安定度スコアや変更の繰り返しは、その差分がこの PR の変更ではなく、環境によるノイズであることを示す強い根拠です。stability（変更なしで完了したビルド）、consistency（変更が同一の状態で繰り返されるか）、uniqueChanges は、スコアの理由を説明します。change.ignored: true はすでに不安定だと判明しており、自動承認されています。リグレッションとして解釈してはいけません。
     • 今回のキャプチャ — スピナー／スケルトン、まだ読み込まれていない非同期コンテンツ、アニメーション中、変動する動的な値、head.metadata.test.retry > 0、またはブラウザー間で score／head.url が同一（どちらも同じ一時的な状態をキャプチャした場合）。retries（設定された再試行回数）は、それ自体では兆候になりません。

     逆に、安定したテスト（flakiness が 0 に近く、stability が高く、今回が初めての変更）で変更が発生した場合は、意図的な変更または実際のリグレッションである可能性が高くなります。見た目だけを根拠に不安定と判断して無視しないでください。build snapshots --metrics-period <24h|3d|7d|30d|90d> で対象期間を調整します（デフォルトは 7d）。

4. 差分を指定してコメントする — エージェントによるレビューで最も価値の高い成果です。 二択での承認／却下は簡単ですが、具体的で対象箇所が明確なフィードバックこそ、エージェントによるレビューを読む価値のあるものにします。問題のある差分ごとに、問題点と修正方法を明記したコメントを、そのスナップショットに紐づけて投稿します。

   argos comment create <ref> --token <pat> --diff <screenshotDiffId> \
     --body "Loader still visible — capture runs before data loads. Wait for settled content (or mark the loader aria-busy)."
   

   • <screenshotDiffId> は build snapshots --json の差分 id です。
   • --anchor-lines <from,to> または --anchor-point <x,y> （0～1 の正規化値）で領域を指定します。--reply-to <commentId> でスレッドに返信します。
   • --draft を使うと、コメントを保留中のレビューにまとめ、次の手順で一括送信できます。

5. レビューを送信する（または PAT が利用できない場合はその旨を報告します）：

   • 承認：argos review create <ref> --token <pat> --event approve
   • 変更をリクエスト：argos review create <ref> --token <pat> --event reject --body "<summary>"
   • 中立的なメモのみ：--event comment --body "<summary>"
   • ビルド番号の参照（URL ではありません）には、--project owner/project を追加します。
   • 今後のビルドをブロックしないよう、再発が確認されたフレークを無視します： argos change ignore <change.id> --token <pat> --project owner/project （change unignore で元に戻せます）。メトリクスで確認されたフレークだけを無視してください — 実際の差分を回避するために使ってはいけません。修正方法がある場合はコードの修正を優先します (references/flaky-fixes.md)。
   • 推測される意図、レビューしたスナップショット、根拠を最初に述べます。PR ではビルド URL と影響を受けるスナップショット名を記載し、フレークについてはシグナルを示して修正を提案します。

参考資料

• references/baseline.md — ベースラインの選択と孤立ビルドの動作（レビューがどのベースラインを使用したかに依存する場合に読み込みます）。
• references/flaky-fixes.md — 不安定なキャプチャに対する具体的なコード修正（aria-busy、data-visual-test、アニメーションの安定化）。