interface-review

コードそのものだけでなく、変更をレビューする

差分は見た目だけのものではありません。変更によって削除された行も追加された行と同じくらい重要であり、変更が及ぼす影響のすべてが、触れたファイルだけに収まることはほとんどありません。

このスキルが担当するのは変更範囲のみです。対象の解決、変更ファイルから影響範囲への展開、差分の両側の確認、各指摘の分類を行います。ドメインルールは better-* スキルが担当します。モード、重大度、統合、網羅性、上限、出力形式、判定は better-interface が担当し、このスキルからレビューを引き継ぎます。ここでそれらのルールを重複させたり、上書きしたりしないでください。

正確性、テスト、セキュリティ、パフォーマンスは、プロジェクト全般のコードレビューが担当します。懸念事項は一度だけ指摘して、先へ進んでください。

クイックリファレンス

カテゴリ	使用する場面
範囲の解決	対象とコマンド、デフォルトブランチ、マージベース、PR とフォークの参照、リポジトリの状態、レビュー対象がない場合、リネーム、除外、利用側への展開
削除された手掛かり	ハンクの - 側で確認することと、各削除を担当するスキル

基本原則

1. まず変更範囲を解決する

モードの解析は better-interface が担当します。モード以降はすべて対象です。そのため、/interface-review quick pr 482 は、プルリクエスト 482 の quick レビューです。受け付ける対象と各対象に対応するコマンドについては、範囲の解決を参照してください。

対象の指定がない場合は、次の順に確認し、最初に一致した時点で止めます。

1. HEAD が git merge-base origin/<default-branch> HEAD より先にある場合、その範囲および未コミットの変更を対象にします。コミット数と未コミットのファイル数は分けて記載します。
2. 作業ツリーに変更がある場合、未コミットの変更を対象にします。
3. どちらにも当てはまらない場合、レビューする変更はありません。原則 2 に従って、ここで止めて確認を求めます。

確認の順序は重要です。先に作業ツリーを確認すると、たった 1 つのフォーマット変更によって 12 コミットのブランチが見落とされる一方で、報告では全体を網羅したとされてしまう可能性があります。

ロックファイル、スナップショット、生成物、ベンダーコード、バイナリを除外し、何を除外したかを明記します。除外後に範囲が空になる場合も、別の経路で原則 2 に該当します。除外したファイルを明記して、確認を求めてください。

2. 変更がない場合は、作り出さずに確認を求める

作業ツリーに変更がなく、マージベースより先にあるコミットもない場合、ユーザーは存在しない変更のレビューを依頼しています。自分の判断で HEAD~1..HEAD にフォールバックしてはいけません。最後のコミットはたまたま取り込まれたものであり、多くの場合はマージコミットか、別の人の作業です。それを対象にした報告では、ユーザーが意図したものについての報告と区別できません。

確認できたリポジトリの状況を伝えてから、選択肢を提示し、返答を待ってください。使用するコマンドについては、レビュー対象がない場合を参照してください。

• 最後のコミット：短い SHA と件名を添えて HEAD~1..HEAD を示し、ユーザーが選択する前にレビュー対象を確認できるようにします。
• ユーザーが指定する対象：pr <n>、ブランチ、参照、範囲のいずれか。原則 1 に従って解決します。
• リポジトリ全体のインターフェース監査：これは変更レビューではありません。リポジトリ全体を対象にしたレビューとして better-interface に引き継ぎ、このスキルの範囲ブロック、ステータス、既存項目セクションは省略します。変更がなければ、すべての指摘が既存のものであり、分類しても情報が得られないためです。

確認を求める前に、現在のブランチにオープン中のプルリクエストがあるか確認し、あれば最初にそのプルリクエストを提示します。ブランチのコミットがすでにベースに取り込まれている場合、変更なしと判断されますが、そのプルリクエストこそがユーザーの意図した対象である可能性は変わりません。

除外後に範囲が空になる場合も、経緯が異なるだけで同じ状況です。何もないレビューを Approve として報告するのではなく、除外したファイルを伝えて同じように確認を求めてください。

3. 差分はサーフェスではありません

変更されたファイルは証拠であり、レビュー対象そのものではありません。そのファイルが描画される影響範囲がレビュー対象です。そこをレビューしてください。

デフォルトでは、影響範囲を1ホップ分広げます。つまり、直接のインポーターと呼び出し元です。デザイントークン、テーマ値、共有プリミティブについては、1行の変更が製品全体に及ぶため、2ホップ目まで広げます。

スコープ解決のルールに従って順序付けし、コンシューマーは最大5つまでレビューしてください。範囲を広げなかったコンシューマー数も明記してください。際限のない確認では、裏付けられないカバレッジの主張が生まれます。打ち切りを明記しなければ、完全に見えて実際にはそうではないレポートになります。

4. 削除された行を読む

変更後の状態では回帰は見えません。各ハンクの-側を削除されたシグナルと照らし合わせて読んでください。

シグナルは手がかりであり、指摘事項ではありません。変更内で何も置き換えられていない場合に限り、削除は回帰です。その判断はドメインスキルが担います。一致する代替が見つからない削除はそれぞれ担当者に回し、そのスキルが確認したものだけを報告してください。その後、ステータスをRegressionに設定します。これは、作者が新たなミスをしたのではなく、動作していたものを壊したことを示します。

5. すべての指摘事項を分類する

各指摘事項に次のいずれかのステータスを付けてください。

• Introduced：変更によって生じました。
• Regression：変更によって、以前は正しかったものが損なわれました。
• Pre-existing：変更箇所のコードに存在しますが、この変更によるものではありません。

ファイル上の位置ではなく、差分で変更された箇所に基づいてステータスを付けてください。変更されていない行は、ハンクから3行しか離れていなくてもPre-existingです。重要な場合は、ベースの参照先と照合してください。

git blame -L <line>,<line> "$BASE" -- path/to/file

すべての指摘事項をステータス付きで引き継ぎ、better-interfaceに上限と判定のルールを適用させてください。

6. 変更を明示された意図と照らし合わせる

プルリクエストのタイトルと本文、リンクされた課題、コミットメッセージを読み、インターフェースが主張どおりのものを提供しているかレビューしてください。

これにより、不完全な変更を見つけられます。サーフェスレビューでは、存在する状態を調べるだけで、ここで重要なのは状態が存在しないことなので、検出できません。

• 新しいバリアント、サイズ、またはテーマが一部の状態にしか適用されていない：ホバー、フォーカス、アクティブ、無効、読み込み中、選択済み。
• 新しいユーザー向け文字列が追加されているのに、プロジェクトが管理する翻訳カタログに項目がない。
• 新しいコンポーネントに、空、読み込み中、エラー、無効、または狭い幅での状態がない。
• あるサーフェスにはコントロールが追加されているのに、同様のコントロールがすでにある兄弟サーフェスには追加されていない。

スコープクリープは報告しないでください。変更がやりすぎかどうかはプロセス上の問題であり、インターフェースの問題ではありません。

7. レビューをbetter-interfaceに引き継ぐ

スコープ、影響を受けるサーフェス、差分の変更前と変更後の両方を確認したうえで、スコープブロックと、各指摘事項のステータスを添えてレビューをbetter-interfaceに引き継いでください。better-interfaceはドメインスキルに振り分け、重大度を適用し、内容を統合し、上限を適用して、判定を下します。これには、変更にスコープを絞ったレビューセクションに記載されたルールも含まれます。

better-interfaceを利用できない場合は、解決したスコープとファイル一覧を報告し、不足しているスキルとしてその名前を挙げて終了してください。重大度の尺度、上限、判定を独自に作ってはいけません。

8. 作業ツリーは変更しない

変更レビューは、チェックアウトを含め、読み取り専用です。プルリクエストの参照先はフェッチし、チェックアウトはしないでください。git fetchは.gitのみに書き込むため、使用が許可されています。gh pr checkout、git checkout、git switch、git stashは、作者が開いているファイルを書き換え、ローカルの編集と競合したり、それらを破棄したりするため、いかなるモードでも使用できません。

レンダリングの検証は任意です。プロジェクトに手軽なプレビュー手段がある場合、またはユーザーがレンダリングを含むレビューを求めた場合を除き、視覚と実行時に関する主張には未検証と記してください。その場合は分離されたワークツリー（git worktree add /tmp/review-<n> refs/remotes/pr/<n>）を使用し、完了後に削除してください。これならチェックアウトとは異なり、作者の作業ツリーに手を加えません。そのため、ここではチェックアウトを代替手段として使用できません。

よくある間違い

間違い	修正方法
ブランチではなく、作業ツリーにある意図しない単独の編集をレビューする	作業ツリーより先に merge-base を確認し、両方の件数を報告します
変更がないため、最後のコミットをレビューする	リポジトリの事実を伝え、最後のコミット、指定した対象、またはリポジトリの監査を提案します
変更箇所を利用する側を確認せずにレビューする	1 階層先まで展開し、トークンとプリミティブについては 2 階層先まで展開して、確認を省略した箇所を明記します
差分の + 側だけを読む	- 側を検索し、削除されたアクセシビリティ、フォーカス、モーション、テキストのシグナルを確認します
同等の置き換えをリグレッションとして報告する	削除箇所の担当スキルに回し、そのスキルが確認した内容だけを報告します
削除を新たな間違いとして報告する	Regression としてステータスを付け、以前は動作していたことを作者に知らせます
変更箇所の近くにある行に Introduced のステータスを付ける	差分が触れた箇所に基づいてステータスを付け、ベース ref に対する git blame で確認します
レビューのためにプルリクエストをチェックアウトする	ref を取得し、その場でレビューします
レビュー対象の ref に存在しない行番号を引用する	スコープブロックに記載された head ref に照らして引用します
モード、重大度、上限、出力形式、または判定をここで再説明する	better-interface に委ねます
レポートに正確性、テスト、またはセキュリティに関する指摘を含める	懸念点を一度だけ記載し、プロジェクトのコードレビューを参照して、その指摘は除外します

レビュー出力形式

4 つの変更範囲に関する追加項目を含む形式は、Change-Scoped Reviews セクションも含めて better-interface が定めています。記載どおりに従い、ここには何も追加しないでください。

このスキルでは、次のスコープブロックを使用します。

項目	値
対象	branch、working、staged、pr 482、または入力された範囲
ベース ref	origin/main の a1b2c3d
head ref	refs/remotes/pr/482 の e4f5g6h
コミット	コミット済み 7 件、未コミットのファイル 2 件
スコープ内のファイル	除外後 12 件
除外対象	pnpm-lock.yaml、src/__snapshots__/：ロックファイルとスナップショット
展開したサーフェス	CheckoutPage、SettingsPanel。さらに Button の利用箇所 3 件は展開せず

原則 5 に従い、すべての指摘にステータスを付けます。

better-interface の Verification には、実行した git コマンドと gh コマンド、およびその結果を正確に記載します。.git への書き込み（fetch、deepen、set-head、worktree を含む）をすべて記載し、原則 8 の読み取り専用の主張を監査できるようにしてください。