レビュー は何をしますか?
変更を**正しいものを作ったか(仕様)とうまく作られたか(品質)**の2つの独立した軸で、新鮮な視点、証拠に基づく所見、実際のユーザーが直面するであろう影響の深刻度で判断します。その後、技術的な厳格さをもって所見に対処します。依存やへつらいはありません。
中核となる原則: 変更がコードベースの健全性を確実に向上させ、要求されたことを行っている場合、たとえ自分ならそう書かなかったとしても承認します。実際に読んで確認していない変更は決して承認しないでください。
パイプライン上の位置: spec → plan → build (+ test) → review → merge。
ステップ1: スコープを固定する
- ユーザーがスコープ(PR、ブランチ、コミット範囲、ファイル)を指定します。指定がない場合は、現在のブランチとデフォルトブランチとのマージベース、および未コミットの変更を対象とします。
- 固定点を解決し、他のことを行う前にスコープが空でないことを確認します:
git rev-parse <ref>、git log <ref>..HEAD --oneline、git diff <ref>...HEAD --stat(コミット済みの作業)、git diff --cached --stat(ステージング済み)、git diff --stat(未ステージング)、git status --short(追跡されていないファイル)を使用します。両方の結合をレビューし、未コミットの変更がスコープに含まれる場合は、各レビュアーにその旨を伝えます(レビュアープロンプトにはそのための行があります)。不正な参照、または両方で空のスコープは、ここで失敗します。 - PRの場合は、その説明とリンクされたIssueを読みます。
ステップ2: 意図を収集する
以下の順序で見つけます:変更が実装する仕様と計画(specs/<slug>/、コミット/PR内のリンク、ユーザーが指定したパス)、ビルド台帳のRuling:行、クローズするIssue。意図を2、3文で言い換えます。仕様がない場合は、そのように述べます。その場合、仕様軸はPRの説明とユーザーの合理的な期待に対して判断します。
また、標準も見つけます:CONTRIBUTING.md、CODING_STANDARDS.md、CLAUDE.md/AGENTS.md、lint設定、ADR、用語集。
サイズチェック。 約100行の変更が理想的で、約300行は1つの論理的な変更としては許容範囲、約1000行は適切にレビューするには大きすぎます。その場合は分割(スタック、ファイルグループごと、または垂直スライス)を推奨する所見とします。リファクタリングと機能追加の混合は2つの変更です。
ステップ3: 新しいコンテキストでレビューする
作成者は自分の前提に盲目であり、コードを書いたセッションも同様です。サブエージェントツールが利用可能な場合は、reviewer-prompt.mdを使用して新しいコンテキストでレビュアーを派遣します。レビュアーには、diff(ファイルまたは正確なコマンドとして)、仕様/計画のパス、標準ファイル、台帳の裁定を与えます。決して自分のセッション履歴を与えてはいけません。レビュアーは読み取り専用であり、自分自身のレビュアーを生成しません。
並行して実行することで、一方の軸が他方を覆い隠すことを防ぎます:
- 仕様レビュアー:欠落、過剰、誤解。
- 品質レビュアー:正確性、テスト、設計、セキュリティ、パフォーマンス。
- (オプション、リスクが高いか広範な変更の場合) 影響範囲レビュアー:grepではわからない場所で何を壊すか。
ブランチ全体のレビューには、利用可能な最も高性能なモデルを使用します。サブエージェントツールがない場合は、各軸を自分で別々のパスとして実行し、結果を自己レビューとラベル付けします。これは新しいレビュアーより弱く、ユーザーがそれで十分かどうかを判断します。
自分が書いたばかりのブランチをインラインでレビューすることは、このステップの代わりにはなりません。
仕様軸
diffを要求された内容と比較します:
- 欠落:要件や成功基準がスキップされている、部分的、主張されているが実装されていない。仕様の行を引用します。
- 過剰:誰も要求していない動作、推測的なオプション、フック、抽象化(スコープクリープ、YAGNI)。
- 誤解:正しい機能が間違った方法で構築されている、または間違った問題が解決されている。
- diffから検証不可能:変更されていないコードや複数の変更にまたがる要件。推測せずに確認すべきことをリストアップします。
仕様はビジョンを示す文書であり、網羅的なリストではありません。 仕様に明記されていない場合、合理的なユーザーの期待が要件となります。入力についての記述がないことは、その入力でクラッシュしてもよいという許可にはなりません。
品質軸
テストを最初に読む:意図とカバレッジが明らかになります。
テスト
- 新しい動作ごとに、その動作が壊れた場合に失敗するテストがあるか?可能であれば実験で確認します:変更が追加する条件を反転させ、テストスイートを実行します。これは使い捨てのワークツリーまたはコピーで行い、レビュー対象のチェックアウトが変更されることはありません。グリーンのままの変異は所見です。欠落しているテストに名前を付けます。
- 公開された境界を通した動作であり、内部実装ではない。モックに対するアサーションなし。テスト対象コードによって計算された期待値なし。モックはシステム境界のみ。
- バグ修正には回帰テストがある。スキップまたは無効化されたテストはなし。テスト出力はクリーン。
正確性
- 仕様と一致。エッジケース(null、空、ゼロ、最大、Unicode、並行処理)。ハッピーパスだけでなく、エラーパス。オフバイワン、競合、同期が取れなくなる可能性のある状態。
可読性と単純性
- 名前は物事が何であるか、何をするかを示している。制御フローは明確。これより少ない行数で書けるか?各抽象化はその価値を正当化しているか?(3回目の使用前に一般化しない)
- デッドコード、何もしない変数、
// removedコメント、誰も必要としない互換性シム。 - コメントはなぜを説明し、何をではない。回避策を説明するコメントは、しばしば修正されていない根本原因を示す。
設計
- 既存のパターンに適合。新しいパターンには理由が必要。
- リファクタリングは、読者が保持すべき概念を減らすか、あるいは単に移動するだけか?ブランチ、モード、レイヤーがなくなるバージョンを優先する。
- 共有モジュールに漏れ出る機能ロジック。既存のヘルパーのほぼ重複。無関係なフローに無理やり追加された条件分岐。同じ形状に対する繰り返しのswitch(欠落したモデルまたはディスパッチャー)。最初のものと同期を保たなければならない2つ目のブール値(欠落したステートマシン)。
- 呼び出し元が1つだけのラッパーと中継レイヤー(インライン化する)。必要以上に広い可変状態。
- 境界での検証、内部での信頼。不明瞭な不変条件を隠すサイレントフォールバックなし。不必要な
any/キャストなし。 - ファイルの成長:ファイルを健全なサイズを大幅に超えて押し上げる変更は、まず分割すべき。
セキュリティ
- 信頼できない入力(HTTP、CLI、ファイル、環境変数、LLM出力、サードパーティ応答)は境界で検証。クエリはパラメータ化。出力はエンコード。必要な場所で認証/認可を確認。コード、ログ、VCS外にシークレット。新しい依存関係は正当化され、メンテナンスされ、ライセンス互換性がある。ロックファイルの差分をレビュー。
パフォーマンス
- N+1クエリ、無制限のループやフェッチ、ページネーションの欠落、ブロックする同期処理、ホットパスでの大きなメモリ確保、不要な再レンダリング。可能な場合は定量化(「1k行で1行あたり約50ms」)。
コードの臭いベースライン(判断事項。リポジトリの文書化された基準が優先):不明瞭な名前、重複コード、機能嫉妬、データ群、プリミティブ型への執着、繰り返しのswitch、散弾銃的修正、発散する変更、推測的な一般化、メッセージチェーン、仲介者。
影響範囲軸(リスクが高いか広範な変更)
呼び出し元をリストアップするのが仕事ではありません。grepが一瞬で行います。仕事は、grepではわからない破損を見つけることです:
- 変更が安全である根拠となる唯一の事実を見つけます(「この呼び出しは既にデッドなエントリのみを削除する」)。コードを実行して証明します:実際のライブラリを固定バージョンでインポートし、問題の関数を正確に呼び出すスクリプト。
- シンボル検索が止まる場所を見つけます:ライブラリソースとローカルパッチ、実行タイミング(非同期の順序付け、ティアダウン)、シリアライズ形式(JSON構造、DBカラム、ワイヤプロトコル、同じバイトを読み取る他の言語)、フィーチャーフラグ、3ホップ先のコンシューマ。
- 各リスクについて:どのように壊れるか、
file:line、可能性、コスト、最も安価なチェック。チェック済みで問題なしと確認されたリスクは別にリストアップします。
ステップ4: すべての所見を検証する
正しそうな所見でも、確認するまでは所見ではありません。
- コードに到達する呼び出し元、ガード、テストに対して確認します。それらが除外する場合は所見を破棄します。
- 重要な所見は証明します:失敗するテスト、再現スクリプト、または誤った動作を示すコマンド出力。可能性のある所見よりも、実行によって証明された所見を優先します。
- 既存の欠陥と、この変更によって導入された回帰を別々にラベル付けします。
- 根本原因を共有する所見は統合します。
- 所見ゼロは有効な結果です。 徹底的に見せるために作り出さないでください。
マージをブロックする基準
所見は、証拠によって確立された場合にのみCriticalまたはImportantとなり、マージをブロックします:
- 誤った動作を示す実行(テスト、スクリプト、またはコマンド)、または
- ステップごとにコードを通して誤った出力までトレースされた具体的な入力で、各ステップに
file:lineがあるもの。
この方法で確立できなかったもっともらしい懸念(「これはXを壊すかもしれない」「エッジケースが処理されていない可能性がある」)は、Minorと評価され、未検証とラベル付けされます。ブロックはしません。作成者が確認できるようにリストアップします。
ステップ5: 評価して報告する
評価は、仕様がトリガーに言及しているかどうかではなく、ソフトウェアが出荷された場合の、合理的なユーザーへの影響によって行います。
| 重大度 | 意味 | 必要なアクション |
|---|---|---|
| Critical | セキュリティホール、データ損失、コア機能の破損 | マージをブロック |
| Important | 誤ったまたは脆弱な動作、要件の欠落、テストされていない動作、エラーの無視、有害な重複や設計 | マージ前に修正 |
| Minor | 洗練、小さな単純化、広範なカバレッジ | 作成者の判断。延期する場合は記録 |
| Nit | スタイルの好み | オプション |
| FYI | コンテキスト、アクション不要 | なし |
レバレッジを優先:正確性とセキュリティを最初に、次に構造的問題と見逃された単純化、その後に残り。1つの構造的問題と10のNitsがある場合、構造的問題がレビューの本質です。問題だけでなく、移動を提案します:「このif-chainをkindをキーにしたルックアップに置き換える」「この呼び出し元が1つのラッパーをインライン化する」「utils/date.tsのformatDateを再利用する」。
正直でありましょう。形だけの「LGTM」は無し。実際のバグを「些細な懸念かもしれない」と軟化させない。NitsをCriticalに膨らませない。うまくいっている点を具体的に認めます。
reviewer-prompt.mdのフォーマットを使用します:仕様の評決、長所、重大度ごとの問題(それぞれfile:line、何が間違っているか、なぜ重要か、修正方法、証拠)、影響範囲メモ、判断を保留(検討したが却下した動作とその理由)、および評決:承認、修正付き承認、または変更要求。仕様セクションと品質セクションは分けて保持し、それらを横断して再順位付けしないでください。
評決ルール: 少なくとも1つのCriticalまたはImportantな所見が上記の証拠基準を満たしている場合にのみ変更を要求します。要求されたことを行っており、Minorまたは未検証の懸念のみがある変更は、それらの懸念をリストアップした上で承認されます。正しい変更を却下することは、壊れた変更を承認することと同じくらい作成者のコストになります。
ステップ6: 所見に基づいて行動する(自分が作成者の場合)
レビューフィードバックは評価するための入力であり、実行すべき命令ではありません。
- 反応する前にすべてを読みます。不明な項目がある場合は、何かを実装する前にそれについて質問します。項目は関連していることがよくあります。
- 各項目を技術的な要件として言い換え、コードに対して検証します。これはこのコードベースにとって正しいか?何かを壊すか?現在のコードには理由があったか?レビュアーは完全なコンテキストを持っているか?
- 間違っている場合は、証拠(テスト、
file:line、測定値)を使って反論します。提案が使用されていない「適切な」機能を追加する場合、使用状況を確認します。YAGNIはレビュアーにも適用されます。ユーザーの以前の決定と衝突するものは、ユーザーにエスカレーションします。 - 順序通りに修正します:Critical/ブロック → シンプル → 複雑。各修正は、最初に所見を再現する失敗テスト(
test経由)を作成し、次に修正、そしてグリーンの完全なスイートを実行します。1回の集中した修正パスであり、無限ループではありません。 - 修正しないMinorは、最終メッセージの「延期」リストに入れます。修正しないと決定した所見は、理由とともに記録された決定です。
- パフォーマンス的な同意はしません。 「まったくその通りです!」「良い指摘です!」、感謝の言葉はなし。変更した内容を述べます(「修正:空の行がヘッダーのみのCSVを出力するようになりました;テスト
exports header for empty view」)、またはコードがそのままである理由を述べます。反論して間違っていた場合は、1行で述べて修正します。
GitHubでは、トップレベルのコメントではなく、インラインコメントスレッドに返信します。
マージ前(完了条件)
- すべての仕様成功基準が満たされ、実行中のシステムで検証済み
- 新しい動作には、変更なしでは失敗するテストがある。完全なスイートがグリーンで、出力はクリーン
- 未解決のCriticalまたはImportantな所見がない。延期は理由とともに記録済み
- デッドコード、デバッグ出力、コメントアウトされたブロックがない。変更はタスクに限定されている
- Lint、型チェック、ビルドがパスする
- マイグレーション、設定、フラグが考慮されている。リスクの高い変更にはロールバックパスが存在する
- 公開インターフェースとユーザーに見える動作が文書化されている。元に戻すのが難しい決定にはADR
- コミットメッセージとPR説明は、独立した用語で、何が変更され、なぜ変更されたかを述べている
- プロジェクトで必要な場合、人間が承認した
よくある正当化
| 考え | 現実 |
|---|---|
| 「テストが通るから大丈夫」 | テストは間違った設計、セキュリティホール、誤読した仕様を捕捉しない。 |
| 「私が書いたから正しい」 | 同じ作成者、同じ盲点。新鮮な視点を得よ。 |
| 「AI生成コードはおそらく大丈夫」 | 間違っているときに自信満々でもっともらしい。より多くの精査が必要であり、より少なくではない。 |
| 「リファクタリングでよりクリーンになった」 | 読者が同じ数の概念を保持しているなら、移動しただけである。 |
| 「後でクリーンアップする」 | 後でやることはほとんどない。今修正するか、明示的に課題として登録せよ。 |
| 「仕様はその入力に言及していない」 | 沈黙は許可ではない。ユーザーが得るものによって評価せよ。 |
| 「レビュアーがMinorと言ったからMinor」 | 影響で再評価せよ。 |
| 「修正は明らかだからテストは不要」 | 失敗するテストこそが、所見が本物であり、今は存在しないことの唯一の証明である。 |
| 「レビュアーはおそらく正しい」 | 最初にコードに対して検証せよ。 |
危険信号
- 読んだ証拠のない「LGTM」
file:lineのない所見、または呼び出し元やガードを確認せずに主張された所見- 仕様と品質の所見が1つのランク付けされたリストに統合されている
- 正確性のバグの上にNitsが埋もれている
- レビュアーが作成者のセッション履歴を渡された
- 最初に失敗テストなしでレビュー所見を修正する
- いくつかのフィードバック項目を実装し、他の項目を…
[翻訳のため省略]