エージェントとの協働について語られる助言の多くは、エージェントの理解を最適化することに重点を置いています。コンテキストファイル、MCPサーバー、文書化されたスキルなど、エージェントがコードベースについて推論できるよう、適切な情報を与えるためのものです。一方で、エージェントが変更を加えているシステムを人間が理解し続けられるようにすることについては、ほとんど語られていません。

Addy Osmaniが、AI生成コードの隠れたコストである理解負債について、とてもよい記事を書いています。AIは、人間がコードを評価できる速度をはるかに上回る速さでコードを生成します。その差によって、チーム自身のコードベースに対する理解が空洞化していきます。

私たちはエージェントの理解を最適化する一方で、人間の理解を損なっています。この隔たりがきっかけとなり、自分がどのように仕事をしてきたのか、そしてコードベースを健全に保つための理解を失わずに速く進むには、まず何を整えておく必要があるのかを、じっくり考えるようになりました。

コードレビューが果たしていた役割

レビューは単なる品質保証ではありません。チーム全体に理解を広げる仕組みです。誰かがあなたのコードを、承認できるほど注意深く読む。そのとき、その人は何が変わったのか、なぜ変えたのかについてのメンタルモデルを築いています。これが、チーム全体で自分たちのコードベースの状況を把握し続けるための仕組みです。

エージェントはコードを悪くすることでこの仕組みに負荷をかけるのではありません。レビューのプロセスが想定していたよりも速くコードを生成することで、負荷をかけます。特にコードベースの中でも、テストで十分にカバーされ、よく理解されている部分なら、速く進んでエージェントを信頼するのが正しい場合もあります。しかし、うまくいかなかったときの影響は積み重なります。理解が不十分な変更が一つ増えるたびに、すでにずれ始めているメンタルモデルを前提に新しいコードを推論することになるため、次のレビューは意味を失っていきます。

試してみて学んだこと

この問題にぶつかったとき、最初に考えたのはプロセスでした。エージェントによる大きな変更セットを、筋の通った一部分をそれぞれ担い、個別にデプロイできるような、小さく順序づけたMRに分けるのです。高速再生したセッションをスローモーションで見直すようなものです。確かに効果はあります。コミットを一つずつレビューできるように並べ替えた大きなMRは、問題なくマージされました。変更を読みやすくし、筋の通ったストーリーを示すことは、常に正しい方向性です。

ただ、レガシーコードベース上には、ドラフトのまま積み重なったMRが5本あります。変更内容は理解しています。しかし、既存のテストカバレッジが、壊れる可能性のある副作用や機能上の挙動まで検出してくれるとは信頼できません。その確信がない以上、全体の下には手動検証を暗黙に求める期待が存在します。これは、まだ対処していないリスクをレビュアーに背負わせることです。

プロセスによって変更を読みやすくすることはできます。そこに存在しないセーフティネットの代わりにはなりません。

いま必要な理解とは

行単位の理解ではありません。もうそれは現実的ではないですし、そうであるかのように振る舞えば、一部のレビューが単なる茶番になるだけです。かといって、何も理解しなくてよいわけでもありません。3つのレベルで考えるとうまくいくと思います。

1つ目は振る舞いです。期待どおりに動くのか。ここで、テストカバレッジがチームにとって最も重要な投資になります。ユーザーが実際にたどる経路上の、現実の振る舞いをカバーする本物のカバレッジ。そして、コンパイル時に型エラーを検出する型安全性です。コンパイラとテストスイートが役割を果たしていれば、レビュアーはすべての行を追う必要がありません。カバレッジが薄い箇所や、チームが手動テストに頼ってきた箇所こそ、エージェントによる高速化が「速さ」ではなく「怠慢」になり始める場所です。

2つ目はアーキテクチャです。変更がどのように動くのかを大まかに理解し、システムのメンタルモデルを更新できるのか。これはエージェントが直接手助けできる部分です。変更セットにおける意味のある判断を要約するようエージェントに頼んでみてください。機械的な変更ではなく、人間が評価する必要のある選択です。どの代替案を検討したのか、どこに自明でない判断があるのか、コードウォークスルーで作者なら何を指摘するのか。これをMRの説明文の土台にします。私はこの作業をエージェントスキルにまとめました。自分のワークフローに組み込めます。構造化されたMRの説明文と、レビューして利用できるコミット構成の推奨を生成し、エージェントが生成した変更セットをレビュアーにとって読みやすくするのに役立ちます。

3つ目は規約です。チームで合意した規約をコードが満たしているのか。これらの多くはリンターで自動的に処理できます。リンターに任せられるものはすべて、人間のレビュアーが注意を向ける必要のないものです。リンターで検出できないものについては、以前エージェントスキルについて書きました。エージェントがコードを書く際の指針にできるほど規約を十分に文書化できているなら、レビューするエージェントの指針にもできるほど文書化できているはずです。

作業の筋道を示す

よい作者であることは、これまでも常に重要でした。いまはそれ以上に重要です。レビュアーはあなたのエージェントとのセッションに参加していません。何をしようとしていたのか、どのトレードオフを検討したのか、エージェントが下した判断のうちどれを意識的に採用したのかについて、周辺的な文脈も持っていません。その文脈はdiffからは伝わりません。意識して伝えなければなりません。

つまり、人間のレビュアーに判断してもらう必要があるアーキテクチャ上の決定を明示し、何が変わったのか、なぜ変えたのかを説明するということです。コミットの構成について慎重に考え、コードを読む前から、レビューで変更のストーリーが明確になるようにするということです。そして、エージェントが生成したものを自分が理解していると示す説明を書くということです。明確に説明できないなら、受動的な委任に切り替わってしまった可能性があります。

Addyが引用しているAnthropicの研究では、AIを受動的な委任に使い、積極的に関わり続けることなくコードを生成させていたエンジニアは、AIを思考の道具として使っていたエンジニアに比べ、理解度テストの成績が大幅に低かったことがわかっています。エージェントはエンジニアの代わりにはなりません。エージェントは道具です。動くというだけでなく、何をしているのか、なぜそうしているのかを理解する必要があります。その理解こそが、レビュアーに提供すべきものです。レビュアーがゼロから再構築するのに任せるのではなく、そこへ導いてください。

すべての変更が同じリスクを持つわけではなく、同じ深さのレビューを必要とするわけでもありません。その点を明確にすることも、よい作者であることの一部です。Ship / Show / Askは、そのための有用な枠組みです。変更の性質と、チームですでに築かれている信頼に応じて、レビューのレベルを調整できます。

速く進むために必要なこと

ドラフトのままになっている5本のMRは、プロセスやコードの理解が原因で止まっているのではありません。セーフティネットが存在しないために止まっています。まず果たすべき義務は、それを出荷前に直すことであって、出荷後に直すことではありません。

しかし、作者としての作業なしに堅牢なテストスイートだけがあっても、レビュアーが何も壊れていないことを確認できるだけです。何が変わったのか、なぜ変わったのか、そしてエージェントが下した判断のうち、どれを自分が意識的に採用したのかを理解することとは違います。エージェントは速度を与えてくれます。その速度を本物にするのは、動くというだけでなく、何を作ったのか、なぜ作ったのかを説明できることです。