今のボトルネックはコードではなく理解にある

Code is no longer the bottleneck. Understanding is.の日本語訳です。

コーディングエージェントは、ソフトウェア開発における希少だったものを変えました。

もっともらしい変更を作成する時間は短くなっています。それでもチームは変更を受け入れるべきか、システムをどう変えるのか、次に何を作るべきかを決めなければなりません。テストが通っただけでは、これらの問いに答えられません。

この差こそが、説明可能性のギャップです。モデルはより多くのコンテキストを扱い、並列に作業できます。人の理解は同じようには伸びません。ボトルネックはコードを作ることから、その方向を決められるほど深く理解することへ移ります。変更を説明できなくなると、チームはシステムを形作る側から、生成物を受け入れる側へ回ります。

多くのレビュー画面はファイルや行、コメントという最も低いレベルから始まります。これらは欠かせない根拠ですが、1つのシステム変更がルートやプロバイダ、テンプレート、テスト、設定を横断する際の出発点としては適していません。

レビューには、より高い抽象度が必要です。ただし、要約を信じるだけでは不十分です。意図からシステムの挙動へ、さらにコードへと下り、すべての主張をdiffまで追跡できる経路が必要です。

人の判断を働かせる「理解」

レビュアーの仕事は、変更ファイルを数えることではありません。答えるべき問いは別にあります。

• システム全体で何が変わったのか
• システムの、どの部分が一緒に動くのか
• 境界と前提はどこにあるのか
• 人が注意を向けるべき場所はどこか
• この設計をシステムの一部にすべきか

テスト、静的解析、エージェントは実装の細部をさらに検証できます。それでも境界は妥当か、トレードオフに価値があるか、システムをどの方向へ進めるかは人が決めます。

変更の意図がなければ、レビュアーに残るのは承認か拒否だけです。意図があれば設計を改善して前提を疑い、その変更を次の判断へつなげられます。

レビュアーが毎回ファイルツリーから変更を組み立て直すべきではありません。この作業には時間がかかり、各自が別の解釈を作ると議論も難しくなります。レビューは、チームが一緒に検証できるモデルを示すべきです。

差分は根拠であって、読む順序ではない

リポジトリのパスは、コードがどこにあるかを示します。しかし、複数のファイルがなぜ一緒に変わったのか、どのファイルから読むべきかまでは説明しません。

リポジトリは実装単位でコードをまとめ、レビュアーは挙動と判断の単位で考えます。1つの挙動がルートやプロバイダー、設定、テンプレート、テストを横断することもあります。

差分は正確な根拠です。そこに、有用な読む順序が必要です。

1つの変更と2つの読む順序

CodeRabbitは先日、関連する編集をシステムの挙動に基づく名前付きのパスにまとめ、各パスを正確なファイルと行へつなぐレビュー画面「Change Stack」をリリースしました。TanStack/cliのプルリクエスト#490は認証、環境の扱い、テンプレート、パッケージ設定、テストにまたがる45ファイルの実際の変更で、その見方を示します。

GitHubは、このプルリクエストを45の変更ファイルとして示します。Change Stackは同じ差分を、関連するシステムの挙動に基づく6つのレビューパスにまとめます。どちらもコードは変えず、出発点だけ変えます。

2つの画面は異なる問いに答えます。GitHubはコードがどこで変わったかを示し、Change Stackはどの変更を一緒に判断すべきかを提案します。

6つのパスは、PRに対する結論ではありません。どのコード範囲を1つの思考単位として扱うかという主張であり、レビュアーはその主張自体を疑えます。

システムの挙動が有用な単位

Change Stackの1つのパスは、10のファイルを1つのサインインフローとして結びます。レビュアーが判断すべき挙動は、どの1ファイルにも収まりません。ルートやプロバイダー、コールバック、設定、テストの間に存在します。

この図は、コードと照らして検証するためのモデルです。最初の問いは、これはどんなフローかではなく「このフローは正しく完全で、安全か」となります。

作成者・レビュアー・メンテナーは、差分から別々の解釈を抱えるのではなく、同じフロー案を見ながら疑問を出せます。

地図はコードへ戻れなければならない

きれいな要約で終わるなら、抽象化は簡単です。難しいのは、根拠まで追跡できることです。

このレビューではPRから変更レイヤー、レイヤーからシステムのフロー、さらに意味単位、ファイル、行へと移動できます。レビュアーは挙動を高い視点で判断し、それぞれの主張を実装と照らせます。

各レベルにはそれぞれの役割があります。意図は変更の理由、システムの挙動は部品の関係、レイヤーはレビューの境界を示します。意味単位は関数やルート、型を特定してファイルと行が根拠になります。

上位レベルをなくすと、レビュアーは座標からシステムを組み立て直さなければなりません。下位レベルをなくすと、確かめられない説明を信じるよう求めることになります。

レビュー画面はスタックになる

コーディングエージェントの生成量が増えても、大きな差分や長い要約だけでは作業を管理できません。どちらもレビュアーにシステムの再構築を任せます。役に立つモデルは確認、修正、そして議論ができます。

レビュー画面に必要なのは、きれいな要約ではなくスタックです。各レベルが別の問いに答え、すべてのレベルがコードへつながるのです。

どの表現も、それだけでは十分ではありません。意図や挙動、正確な根拠の間を、つながりを切らずに移動できることに価値があります。

目標は、読むコードを減らすことではありません。ゼロからモデルを作る代わりに、筋の通ったモデルをコードと照らすことへ時間を使うことにあります。機械が変更を整理して経路を示します。モデルは正確か、境界は妥当か、その方向へ進む価値があるかは、人が決めるのです。

差分は今も重要な根拠です。Change Stackは、その根拠を判断に使える形に整理します。

マージ済みPRをGitHubで確認する · 同じPRをChange Stackで見る