エージェントはプルリクエストを数分で作成できます。そのPRは多数のファイルにまたがり、新しいAPI、データベースのマイグレーション、テストを1つの変更にまとめていることもあります。それをレビューするということは、これらの部品がどのように連携し、アプリケーションの他の部分に何を及ぼすのかを理解するということです。
マージする前に、誰であれ1つの問いに答えなければなりません。自分は、マージしようとしている変更を理解しているか？
プルリクエストに説明文と差分、そしてページ上部のサマリーがそろっていると、この問いは軽く流してしまいがちです。それらは有用な出発点ですが、レビュアーは依然として、説明が実装と一致していることを確認し、PRをマージした場合の影響を理解する必要があります。
私たちがChange Stackを構築したのは、プルリクエストの意図、振る舞い、依存関係をコードそのものと結び付け、レビュアーが変更の意味を理解し、その説明を検証できるようにするためです。
このプルリクエストは何をしようとしているのか？
意図はレビュアーが最初に必要とするものの1つでありながら、差分からは最後まで読み取りにくいものです。作者の頭の中にはあるかもしれませんし、チケットに一部が書かれているかもしれません。しかしプルリクエストの説明文は、実装が固まる頃には古くなっていることがあります。
レビュアーは、変更の目的をその結果という形で言い表せるべきです。たとえば次のようなものです。
- 新しい承認経路を追加する
- レコードの所有権を移す
- 顧客に通知が届くタイミングを変える
Change StackはPRの概要ページから始まり、変更そのものの論理に沿って作業をレイヤーに分解します。レビュアーはPRのサマリーとともに、コードの指摘事項へのリンクや取るべきアクションを受け取ります。
差分では説明できないこと
典型的なファイル単位のレビューでは、レビュアーはアルファベット順に並んだファイル一覧を渡され、そこから変更を再構築するよう求められます。設定の更新がサービスの振る舞いを変えることもあれば、共有関数の変更がそれを使うアプリケーションの他の部分に影響することもあります。個々の変更は読めても、その背景にある文脈は見えにくいままです。
レビュアーは、これらの変更がどう組み合わさるのかを理解するためにPRのサマリーに目を向けるかもしれません。サマリーは意図された振る舞いを説明し、依存関係を指摘できます。しかしその説明を確認するには、その裏にあるコードを見つけなければなりません。
Change Stackは、プルリクエストのセマンティック差分ビューを提供することでこのステップを支援します。さらに、関連する変更をレイヤーにまとめ、説明をそれが指すコードのすぐ隣に配置します。これによりレビュアーは、実装がプルリクエストの主張を裏付けているかどうかを確認できます。
どの振る舞いが変わるのか
目的が明確になったら、レビュアーは実装がアプリケーションの振る舞いをどう変えるかを調べる必要があります。新しいエンドポイントが1つのファイルに現れ、他の5つのファイルから呼び出されているかもしれません。レビュアーは、それらの部分が相互作用したときに何が起こるのか、そしてテストがその振る舞いをカバーしているのかを理解しなければなりません。
CodeRabbit Change Stackでは、変更がレイヤーにまとめられるため、レビュアーは関連する変更をまとめて調べることができます。たとえば1つのレイヤーが、エンドポイントの実装とそのテストをレビューの同じステップに集め、該当するコードにリンクされた説明を添えます。リクエストがアプリケーション内をどう流れるかは、図で示すこともできます。
このPRに何が依存しているのか
変更された部品がどう連携するかを理解したら、次はそれらに他の何が依存しているかを確認する必要があります。たとえばサブスクリプションのステータスを変更すると、PRでは一切触れていない更新処理のバックグラウンドプロセスに影響が及ぶ可能性があります。レビュアーは、そのプロセスが新しいステータスを正しく扱えるかどうかを確認しなければなりません。
Change StackのセキュリティのBlast Radius（影響範囲）は、こうした関係を該当するレイヤーの隣に表示し、レビュアーが読み進めながら依存関係を追えるようにします。この文脈から、マージ前にさらに確認が必要な下流の振る舞いや前提が明らかになることがあります。
コードを見せてほしい
レビューツールは、変更についての洗練された説明を提示してくれることが多くあります。そこで自然に湧く次の問いは、それはどこで起きているのか？ です。
サービスが失敗したリクエストを再試行するのなら、レビュアーはその再試行の経路を開けるべきです。同様に、説明が「この変更は内部APIに限定される」と述べているなら、レビュアーはそのAPIを使うコードを調べ、その境界を確認できるべきです。
Change Stackは説明と指摘事項を差分の正確な範囲にリンクするため、レビュアーは周囲の文脈を見失わずに、それぞれの記述を実装と照らし合わせて確認できます。
このマージで何を引き受けることになるのか
マージの判断は、この試験の最後のピースです。この段階でチームは、振る舞い、依存関係、そしてコードが本番環境に到達した後に残るリスクを引き受けられるだけ、変更を理解しているべきです。
その理解は、実際にマージされるバージョンに対して成り立っていなければなりません。レビュー後に誰かが新しいコミットをプッシュした場合、レビュアーは説明のどの部分が現在のコードをまだ正しく表しているのかを知る必要があります。Change Stackはレビューしたコミットのスナップショットを保持し、そのレビュー以降にPRが変更されたことを示します。
スナップショットは、特定のコミットに対して完了したレビューを表します。PRに対するアクションは、その最新の状態に適用されます。この区別を目に見える形にすることで、レビュアーはコードが自分の確認したバージョンから先へ進んでしまったことに気づけます。
理解を確かめる試験
プルリクエストを承認する前に、レビュアーは次の5つの問いに答えられるべきです。
- この変更は何を達成しようとしているのか？
- アプリケーションの振る舞いはどう変わるのか？
- 変更されたコードは何に依存し、何がそれに依存しているのか？
- コードのどこで、その説明を確認できるのか？
- このバージョンをマージすることで、どのような振る舞い、依存関係、残存リスクを受け入れることになるのか？
Change Stackは、説明、依存関係、関連するコードを1か所に集め、レビュアーがこれらの問いに答えて、変更をマージする準備ができているかどうかを判断できるようにします。
