コーディングエージェントが普及するにつれ、ソフトウェア開発において希少なものは変化している。もっともらしいコード変更を生成するのにかかる時間は減少したが、チームはその変更が適切か、システムをどう再形成するか、次に何をすべきかを決定しなければならない。テストに合格してもそれらの問いに答えられない。これが「説明可能性のギャップ」である。モデルはより多くのコンテキストを扱い、並行して作業できるが、人間の理解力は同じようにはスケールしない。ボトルネックはコードの作成から、それを十分に理解して指示することへと移行する。チームが変更を説明できなくなると、システムを形作ることをやめ、出力を受け入れるだけになる。
ほとんどのレビューインターフェースはファイル、行、コメントから始まる。その証拠は不可欠だが、1つのシステム変更がルート、プロバイダ、テンプレート、テスト、設定にまたがる場合、そこから始めるのは不適切だ。レビューにはより高い抽象度が必要だが、盲目的な信頼を求める要約ではない。意図からシステム動作、コードへと至り、すべての主張が差分にトレース可能なパスが必要である。
理解が判断力を活性化させる。レビューアの仕事は変更されたファイル数を数えることではない。システムレベルで何が変わったか、システムのどの部分が一緒に動くか、境界や前提条件はどこか、人間の注意を引くべきものは何か、この設計をシステムの一部とすべきか。テストや静的解析、エージェントは実装の詳細を検証できるが、境界が妥当か、トレードオフが価値あるか、変更がシステムを有用な方向に導くかを決めるのは人間である。
変更の動作モデルがなければ、レビューアは承認か拒否しかできない。モデルがあれば、設計を改善し、前提に挑戦し、変更を次の判断につなげることができる。レビューアがファイルツリーから毎回変更を再構築する必要はない。その作業は遅く、個別の再構築は議論を困難にする。レビューはチームに共有モデルを提供し、それをテストできるようにすべきである。
差分は証拠であって、経路ではない。リポジトリパスはコードの場所を示すが、なぜ複数のファイルが一緒に変更されたか、どのファイルを先に読むべきかは説明しない。リポジトリは実装ごとにコードをグループ化するが、レビューアは動作と決定について考える。1つの動作がルート、プロバイダ、設定ファイル、テンプレート、テストを横断することがある。差分は依然として正確な証拠だが、有用な読み取り順序が必要である。
同じ変更、2つの読み取り順序。CodeRabbit は最近「Change Stack」を導入した。これはシステム動作に基づいて関連する編集を名前付きパスにグループ化し、各パスを正確なファイルと行にリンクするレビュービューである。TanStack/cli のプルリクエスト #490 では、認証、環境処理、テンプレート、パッケージ設定、テストにわたる45ファイルの変更を、Change Stack はシステム動作に基づく6つのレビューパスに整理する。2つのビューは異なる質問に答える：GitHub はコードがどこで変更されたかを示し、Change Stack はどの変更を一緒に判断すべきかを提案する。
有用な単位は動作である。Change Stack の1つのパスが10個のファイルを1つのサインインフローにまとめる。レビューアが判断すべき動作を1つのファイルが含むことはない。それはルート、プロバイダ、コールバック、設定、テストの間に存在する。システム動作図はレビューアにモデルを提供し、コードと照らしてテストできる。最初の質問は「このフローは何か？」ではなく、「これは正しく、完全で、安全か？」になる。著者、レビューア、メンテナーは同じ提案フローに挑戦でき、差分に対する3つの個人的解釈を持ち歩く必要がない。
マップはコードに戻らなければならない。抽象化は洗練された要約で終われば安価だが、トレーサビリティはより難しい。このレビューでは、レビューアはプルリクエストから変更層へ、層からシステムフローへ、フローからセマンティックエンティティ、ファイル、行へ移動できる。高レベルで動作を判断し、その後実装に対して各主張を検証できる。抽象化は双方向が開かれている場合にのみ有用である。意図を回復するためにズームアウトし、コードに対してマップを検証するためにズームインする。各レベルには1つの役割がある：意図は変更が存在する理由を説明し、システム動作は部品の相互作用を示し、層はレビュー境界を設定し、セマンティックエンティティは関数、ルート、型を命名し、ファイルと行は証拠を提供する。上位レベルを削除すればレビューアは座標からシステムを再構築しなければならず、下位レベルを削除すれば検証できないストーリーを信じるよう求められる。
レビューインターフェースはスタックになるべきであり、よりきれいな要約ではない。コーディングエージェントがより多くの大きな差分を生成するにつれ、長い要約は作業を管理可能にしない。どちらもレビューアにシステムの再構築を強いる。有用なレビューモデルは検査、修正、議論が可能でなければならない。各レベルは異なる質問に答え、すべてのレベルがコードに接続されている。単一の表現で十分なものはない。価値は意図、動作、確実な証拠の間をチェーンを断ち切らずに行き来することにある。目標は読むコードを減らすことではなく、コードを読む時間を、ゼロからモデルを構築する代わりに、一貫したモデルをテストするために使うことである。機械は変更を整理しパスを公開できる。人間はモデルが正確か、境界が妥当か、方向性が価値あるかを決定する。差分は依然として基本事実であり、スタックはそれを判断に利用可能にする。