interface-review

インターフェースレビュー

このスキルは画面ではなく、変更をレビューします。対象範囲を確定し、変更されたファイルから影響するサーフェスをたどり、差分の変更前後を両方読み、すべての指摘事項を分類します。

対象範囲、分類、変更に限定したレポートはこのスキルが担当します。ドメインのルールは better-* スキルに属します。重要度、統合、網羅性、上限、判定は better-interface が担当し、このスキルからレビューを引き継ぎます。

正確性、テスト、セキュリティ、パフォーマンスはプロジェクト全般のコードレビューに属します。そのような懸念事項は一度だけ挙げ、そのレビューを参照して、ここでは扱いません。

コードベースではなく、変更をレビューする

作者が尋ねているのは「これを悪化させていないか」です。変更が引き起こしたことを報告し、変更によって単に触れただけのものについては、ほとんど言及しないでください。既存の指摘が3件なら親切ですが、30件では別のレビューになり、誰も依頼していないものになります。

意見をまとめる前に、差分全体を読んでください。ざっと目を通しただけの差分では、次のハンクですでに修正されているコードについて指摘してしまいます。

1. まず変更の対象範囲を確定する

呼び出し全体が対象です。したがって、/interface-review pr 482 はプルリクエスト482をレビューします。対象範囲の確定には、受け付ける対象と、それぞれの解決方法が記載されています。

対象が指定されていない場合は、次の順に確認し、最初に当てはまった時点で終了します。

1. HEAD が git merge-base origin/<default-branch> HEAD より先にあります。この場合、その範囲に加えて未コミットの変更もレビューし、コミット数と未コミットのファイル数をそれぞれ示します。
2. 作業ツリーに変更があります。この場合、未コミットの変更をレビューします。
3. どちらにも当てはまりません。レビューする変更はありません。変更がない場合は、作り出さずに尋ねるに従います。

解決した範囲のベースコミットを $BASE として記録し、対象範囲のブロックに明記してください。このスキルと参照先にあるすべてのコマンドで、この値を使用します。

除外するパスに従って、ロックファイル、スナップショット、生成物、ベンダーコード、バイナリを除外し、除外したものを明記してください。除外後に何も残らなければ、変更なしとして扱います。

2. 変更がない場合は、作り出さずに尋ねる

マージベースより先にあるコミットがなく、作業ツリーもクリーンなら、レビューする変更はありません。自分の判断で HEAD~1..HEAD に切り替えることは絶対に避けてください。最後のコミットはたまたま取り込まれたものであり、マージや他の人の作業であることもよくあります。

レビュー対象なしに記載された事実を集めて示したうえで、次の選択肢を提示し、返答を待ちます。

• 現在のブランチのオープンなプルリクエスト。存在する場合は、まずこれを提示します。コミットがすでに取り込まれたブランチは変更なしと判定されますが、そのプルリクエストこそがユーザーの意図した対象である場合があります。
• 最後のコミットである HEAD~1..HEAD。短縮SHAと件名を示し、レビュー対象が何になるかユーザーに分かるようにします。
• ユーザーが指定する対象。たとえば pr <n>、ブランチ、参照、範囲などです。
• リポジトリ全体のインターフェース監査。これは変更レビューではありません。対象範囲ブロック、ステータス、既存の指摘事項セクションを含めず、リポジトリ全体を対象とするレビューとして better-interface に引き継ぎます。

除外によって対象範囲が空になった場合は、選択肢を提示する際に除外したファイルを明記してください。何もレビューしていないのに Approve と報告することは絶対に避けてください。

3. 差分はサーフェスではない

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

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

両方のホップを通じて確認するコンシューマーは、合計5件までとし、対象範囲の確定にあるルールに従って順序付けます。網羅したと誤解されないよう、確認対象から外した件数も明記してください。

4. 削除された行を読む

変更後の状態ではリグレッションは見えません。各ハンクの - 側を削除シグナルと照らし合わせて確認してください。

シグナルは手掛かりであり、指摘事項ではありません。削除がリグレッションとなるのは、変更内で何も置き換えられていない場合に限られ、その判断は該当ドメインのスキルが担います。対応するものが見当たらない削除は担当者に振り分け、そのスキルが確認した内容だけを報告し、ステータスを Regression としてください。

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

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

• Introduced：変更によって発生しました。
• Regression：変更によって、それまで正しかったものが損なわれました。
• Pre-existing：変更前から存在し、変更によって悪化していません。

ステータスは場所ではなく原因に基づいて付けてください。変更行が原因の指摘事項は、変更されたトークンを使用する未変更の箇所に現れる場合も含め、どこに現れても Introduced または Regression です。変更によって発生も悪化もしていない指摘事項は、ハンクから3行しか離れていなくても Pre-existing です。

行が変更前から存在していたかを確認するには、レビュー対象範囲を指定して blame を実行します。^ 接頭辞は、ベース以降変更されていない行を示します。

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

未コミットの作業では、範囲指定を外してください。Not Committed Yet と表示される行、または $BASE..HEAD 内のコミットに帰属する行は、変更に含まれます。

6. 変更を明示された意図に照らして評価する

プルリクエストのタイトルと本文、リンクされた課題、コミットメッセージを読んで、インターフェースが説明どおりの機能を提供しているかを確認してください。

これにより、表面的なレビューでは見落とされる不完全な変更を見つけられます。表面的なレビューでは、存在する状態だけを確認するためです。欠けている状態を探してください。

• 新しいバリエーション、サイズ、テーマが、一部の状態にしか適用されておらず、ホバー、フォーカス、アクティブ、無効、読み込み中、選択済みの状態には適用されていない。
• 新しいユーザー向け文字列が、プロジェクトで管理している翻訳カタログに登録されていない。
• 新しいコンポーネントに、空、読み込み中、エラー、無効、狭い幅の状態がない。
• ピアとなるコントロールがすでにある別の画面には追加されているコントロールが、ある画面にだけ追加されている。

スコープの逸脱は報告しないでください。変更が余計なことまで行っているかどうかはプロセス上の問題であり、インターフェースの問題ではありません。

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

スコープブロック、影響を受ける画面、すべての指摘事項のステータスを better-interface に渡し、以下の形式で報告してください。

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

作業ツリーを変更しない

変更レビューでは、チェックアウトも含め、読み取り専用で操作してください。git fetch は .git のみを書き換えるため許可されています。gh pr checkout、git checkout、git switch、git stash は、作者が開いているファイルを書き換えるため、決して実行してはいけません。プルリクエストの参照を取得し、その場で読み取ってください。

ここでは、better-interface の 検証可能な項目を検証する に代わり、レンダリング検証はオプトインです。プロジェクトに手軽なプレビューがある場合、またはユーザーがレンダリングを含むレビューを求めた場合を除き、視覚および実行時に関する主張には 未検証 と明記してください。working と branch の場合、チェックアウトはすでにヘッドを指しているため、その場でレンダリングしてください。それ以外の対象では、git worktree add /tmp/review-<n> refs/remotes/pr/<n> のような方法で独立したワークツリーを作成し、完了後に削除してください。

終了する前に

誤り	修正
HEAD がマージベースより先に進んでいるのに、スコープブロックが未コミットのファイルのみを対象にしている	ブランチの差分範囲と未コミットの変更を、両方の件数とともに確認します
ユーザーが選んでいない HEAD~1..HEAD のレポート	事実を伝え、変更がない場合は、変更を作り出さずに質問するに記載された選択肢を提示します
Surfaces expanded に、変更された共有コンポーネントの利用箇所が含まれていない	利用箇所まで展開し、確認対象から外したものを明記します
削除された aria-label、outline、または prefers-reduced-motion について、指摘も注記もない	削除されたシグナルを通じて担当者に引き継ぎます
削除された属性が差分の別の箇所に再び現れている Regression の指摘	まず同等の置き換えを確認します
変更されたトークンの影響を受けた未変更の利用箇所に対する指摘を Pre-existing としている	その変更が原因なので、Introduced または Regression です
変更原因が示されていない、すべてのハンクの範囲外の行を Introduced としている	レビュー対象の差分範囲と照らして原因を特定します
コマンドログに gh pr checkout または git switch がある	ref を取得し、git show でファイルを読み取ります
引用した行が git show <head-ref>:path と一致しない	スコープブロックで指定した head ref に基づいて引用します

レビュー出力の形式

まずスコープブロックを記載します。

項目	値
対象	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 件は未展開

その後に better-interface のカバレッジ表を続けます。変更範囲内に根拠がないドメインは Not reviewed: no evidence in the change scope とします。これはカバレッジに関する記述であり、抜け漏れを示すものではありません。

続いて、すべての指摘を分類するに従って Status 列を設けた指摘を記載します。

重大度	ドメイン	ステータス	場所	変更前	変更後	理由
HIGH	アクセシビリティ	Regression	src/Dialog.tsx:42	この変更で aria-label="Close" が削除されました	アイコンのみのコントロールに aria-label="Close" を復元します	この変更前には閉じるコントロールにアクセシブルな名前がありましたが、変更後はなくなっています

Introduced または Regression の指摘がない場合は、表を省略して「この変更に対応が必要なインターフェース上の指摘はありません。」と記載します。

続いて Pre-existing の指摘を、重大度の高い順に最大 3 件まで、今回の変更に起因するものではないことを明確にして記載します。該当する指摘がない場合は、このセクションを省略します。

重大度	ドメイン	場所	問題
MEDIUM	タイポグラフィ	src/Toolbar.tsx:7	数値バッジにプロポーショナル数字が使われています。今回の変更より前から存在します

検証結果と判定は、better-interface の形式に従って記載します。