Addy Osmaniは先週、AI生成コードの隠れたコストであるcomprehension debtについて、素晴らしい記事を書きました。中核となる考え方はこうです。AIは人間が評価するよりもはるかに速くコードを生成するため、そのギャップが静かにチームの自分たちのコードベースに対する理解をくり抜いていく、ということです。
私も強く共感しましたが、特に目についたのは、業界がこの問題にどう対応しているかにおける具体的な非対称性です。エージェントの扱いに関するほとんどの助言は、エージェントの理解（comprehension）を最適化しています。コンテキストファイル、MCPサーバ、文書化されたスキル、そしてエージェントがあなたのコードベースを推論できるように適切な情報を投入すること。重要な問題は他にもありますが、そこについての議論はずっと少ないのです。すなわち、人間が、エージェントが変更しているシステムを引き続き理解できるようにすることです。
私たちはエージェントの理解を最適化している一方で、人間の理解は静かに失われていきます。このギャップが、私に「これまでどう働いてきたか」そして「コードベースを健全に保つ理解を失わずに速く動けるようになる前に、実際に何が整っている必要があるのか」を慎重に考えさせました。
レビューが実際にやっていたこと
レビューは単なる品質保証ではありません。それは、理解がチーム内に広がっていく仕組みです。誰かがそれを承認するのに十分なほど丁寧にあなたのコードを読めば、何が変わり、なぜそうなったのかについての頭の中のモデル（メンタルモデル）を構築しています。これが、チームが自分たちのコードベースに対して集団としての方向性を保ち続けるためのメカニズムです。
エージェントは、このメカニズムに圧力をかけます。コードを悪くすることでではなく、レビュー工程が対応できるように設計されていた速度よりも速いペースでコードを生成することでです。うまくいっている（十分にカバーされ、十分に理解されている）コードベースの領域では、速く進めてエージェントを信頼する判断が正しいこともあります。しかし失敗したときの影響は連鎖的に膨らみます。理解が不十分な変更が一つあると、次のレビューの意味は薄れていきます。なぜなら、新しいコードを、すでにずれ始めているメンタルモデルに照らして推論していくことになるからです。
試してみて学んだこと
これに直面したとき、私の最初の直感はプロセスでした。大きなエージェントの変更セットを、段階的に並べた小さなシーケンスのMRに分割します。各MRはストーリーの一部として首尾一貫していて、それぞれ単独でデプロイ可能にします。速送りセッションのあとにスローモーション再生が来るようなものです。そこには確かに何かあります。コミットを整理して1つずつレビューできるようにした大きなMRは、摩擦なくマージされました。変更を読みやすくし、首尾一貫したストーリーとして語ることが常に正しい本能であるのは間違いありません。
ただし、いま私にはレガシーなコードベース上でドラフト状態の積み上げられたMRが5つあります。変更が何をするかは理解していますが、起こりうる副作用や、壊れる可能性のある機能上の振る舞いを既存のテストカバレッジが確実に捕捉してくれるとは信じていません。その信頼がないと、全体の下に「暗黙の手動検証を期待する」状態が生まれてしまい、これは、あなたがまだ対処していないリスクをレビュー担当者に背負わせることを意味します。
プロセスは変更をより読みやすくできます。しかし、そこに存在しないセーフティネットの代わりにはなれません。
今こそ「理解」を必要とするものは何か
以前のように行ごと（line-by-line）で追うのはもう現実的ではありません。そうでないことを振りまくと、いくつかのレビューが単なる舞台（theatre）になります。しかし、それはゼロという意味でもありません。私は、理解は3つのレベルで成立すると思います。
1つ目は振る舞い（behavioural）です。期待どおりに動くか、ということです。ここでテストカバレッジは、チームが投資として最も重要なものになります。ユーザーが実際にたどる経路に沿って実際の振る舞いをカバーする、実在のカバレッジが必要です。あわせて、コンパイル時に型エラーを検出する型安全性も重要です。コンパイラとテストスイートが役割を果たしていれば、レビュー担当者はすべての行を追跡する必要はありません。カバレッジが薄い場所、あるいはチームが手動テストに頼ってきた場所がまさに、その時点で「エージェントのスピード」はスピードではなく「怠慢（negligence）」に変わってしまう地点です。
2つ目はアーキテクチャ（architectural）です。変更が全体としてどう機能するのかを、広い視点で理解できているか、そしてシステムについてのメンタルモデルを更新できるか、ということです。これはエージェントが直接手助けできる領域です。変更セットに含まれる意味のある判断（meaningful decisions）を要約するように、エージェントに依頼してください。機械的な変更ではなく、人間が評価する必要のある選択を対象にします。検討された代替案は何か、非自明な判断がどこにあるか、コードウォークスルーで著者がどこを指摘するだろうか——それをMRの説明の土台として使います。私はこれを、あなたのワークフローにそのまま投入できるagent skillとしてパッケージしました。これは、構造化されたMR説明と、レビューして活用できるコミット構造の推奨を生成し、エージェントが作った変更セットをレビュー担当者にとって読みやすくするのに役立ちます。
3つ目は標準（standards）です。コードが、チームが合意した規約（コンベンション）を満たしているか、ということです。リンティングは多くの部分を自動的に処理してくれます。リンタに押し込めるものが1つ減るほど、人間のレビュー担当者が注意を向ける必要が1つ減ります。リンティングでは検出できないものについては、私は以前agent skillsについて書きました。あなたの標準が、エージェントがコードを書く際にガイドできるほど十分に文書化されているなら、それは同様に、エージェントがそれをレビューする際にもガイドできるほど十分に文書化されているはずです。
作業内容を示す
良い著述（authorship）は常に重要でした。今はさらに重要です。レビュー担当者はあなたのエージェントのセッションに同席していませんし、あなたが何をしようとしていたのか、どんなトレードオフを考えたのか、そしてあなたが意識的に「残した」判断は何かについて、周辺の理解（ambient understanding）がありません。その文脈はdiffを通じて引き継がれません。あなたが意図的に移植しない限り、それは失われます。
つまり、人間の目が必要なアーキテクチャ上の判断を明示することです。何が変わったかだけでなく、なぜそうしたのかも説明すること。誰かがコードを読む前から、変更のストーリーが読みやすくなるようにコミット構造について慎重に考えること。エージェントが生み出したものを理解していたことが分かる説明を書くことです。なぜなら、それを明確に説明できない場合、「受け身の丸投げ（passive delegation）」に切り替えてしまっているリスクがあるからです。
Addyが引用しているAnthropicの研究では、エンジニアがAIを受け身の丸投げに使い、つまり積極的に関与せずにコードを生成させるだけにしていた場合、思考テスト（comprehension tests）で大きく低いスコアになったことが分かりました。AIを思考ツールとして使った人たちとは有意に差がありました。エージェントはエンジニアを置き換えません。これは道具です。そして、それが動くというだけでなく、何をしていて、なぜそうしているのかを理解する必要があります。その理解こそが、あなたのレビュー担当者が得るべきものです。スクラッチから再構成させるのではなく、その方向へ導いてあげましょう。
すべての変更が同じリスクを持つわけでもなく、同じ深さのレビューを必要とするわけでもありません。そして、それを明示することもまた良い著述（authorship）の一部です。Ship / Show / Askは、そのための有用な枠組みであり、変更の性質と、チーム内で既に確立されている信頼に基づいて、レビューのレベルを調整していくことを可能にします。
「速さ」に本当に必要なもの
ドラフト状態の5つのMRは、プロセスが原因でも、私のコード理解が原因でもありません。セーフティネットが存在しないことが原因で止まっています。まず最初の義務として、それを直すことです。出荷した後ではなく、出荷する前に。
しかし、著述（authorship）の仕事をせずに堅牢なテストスイートがあるだけなら、レビュー担当者が「壊れていないこと」を確認できる、という意味にとどまります。変更が何で、なぜ変わったのか、あるいはエージェントがあなたの意識的な判断として「残すことにした」ことは何か、という理解とは同じではありません。エージェントはあなたにスピードを与えます。そのスピードを本物にするのは、それが動くというだけでなく、あなたが何を作り、なぜ作ったのかを説明できることです。
