エージェントとの協業に関するアドバイスの多くは、エージェントの理解度を最適化することに焦点を当てています。contextファイル、MCPサーバー、ドキュメント化されたスキルなど、エージェントがコードベースについて推論できるよう正しい情報を与えることに主眼が置かれています。一方で、エージェントが変更を加えているシステムを人間がきちんと理解し続けられるかという議論は、はるかに少なくなっています。

Addy Osmaniはcomprehension debt（理解の負債）について素晴らしい記事を書いています。AIが生成するコードに潜む隠れたコストのことです。AIは人間が評価できるスピードをはるかに上回る速さでコードを生成し、そのギャップがチーム自身のコードベースに対する理解を空洞化させていきます。

私たちはエージェントの理解を最適化する一方で、人間の理解はすり減っています。このギャップこそが、自分の働き方について改めて慎重に考えるきっかけとなり、健全なコードベースを支える理解を失わずに速く動くために、まず何を整えておくべきかを考えさせてくれました。

コードレビューが担っていたこと

レビューは単なる品質保証ではありません。理解をチーム全体に広めるための仕組みです。誰かがあなたのコードを承認できるほど丁寧に読むとき、その人は何がなぜ変わったのかというメンタルモデルを構築しています。それこそが、チームが自分たちのコードベースに対して集合的に向き合い続けるためのメカニズムなのです。

エージェントは、コードの質を下げることでこのメカニズムに圧力をかけているわけではありません。レビュープロセスが想定していた処理能力を超える速さでコードを生成することで、圧力をかけているのです。ときには速く動いてエージェントを信頼することが正しい判断のこともあります。とりわけカバレッジが十分で、よく理解されている領域ではそうです。しかし、それがうまくいかなかったときの影響は複利的に積み重なります。十分に理解されない変更が一つ増えるたびに、次のレビューは、すでにズレ始めているメンタルモデルを前提に新しいコードを推論することになるため、その意味が薄れていくのです。

試行錯誤から学んだこと

この問題に直面したとき、最初に思いついたのはプロセスで解決することでした。エージェントによる大きな変更セットを、物語として一貫性があり、それぞれが単独でデプロイ可能な、小さく順序立てられたMRに分割するのです。高速で進めた作業のあとでスローモーション再生するようなイメージです。これには一定の効果があります。コミットを整理して一つずつレビューできるようにした大きなMRは、滞りなくマージされました。変更を読みやすくし、一貫した物語を語ることは、常に正しいアプローチです。

しかし一方で、レガシーなコードベースに対する5つのスタックされたMRがいまだにドラフトのまま積み残されています。変更内容が何をするものかは理解していますが、副作用や壊れる可能性のある機能的な振る舞いを、既存のテストカバレッジが捉えてくれるとは信じられていません。その確信がない限り、その裏側には手動での検証が暗黙のうちに期待されることになり、それは自分が向き合っていないリスクをレビュアーに背負わせることを意味します。

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

今、理解することは何を意味するのか

もはや一行一行を追うような理解は現実的ではありませんし、できると装っても一部のレビューは形骸化するだけです。かといって、何もしないということでもありません。理解は3つのレベルで成り立つと考えています。

1つ目は挙動です。期待通りに動くかどうか。ここで最も重要な投資となるのがテストカバレッジです。ユーザーが実際にたどるパスをカバーする、挙動を本当に検証するカバレッジ、そしてコンパイル時に型エラーを検出する型安全性です。コンパイラとテストスイートがきちんと機能していれば、レビュアーはすべての行を追う必要はありません。カバレッジが薄い場所や、これまで手動テストに頼ってきた場所こそ、エージェントの速度が単なる速さではなく、怠慢になり始める場所なのです。

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

3つ目は規約です。コードがチームで合意した規約を満たしているかどうか。この多くはLintによって自動的に処理でき、Linterに任せられるものは、人間のレビュアーが注意を払うべき事柄から一つ減らせることになります。Lintでは捉えきれないことについては、以前agent skillsについて書いたことがあります。もし規約がエージェントにコードを書かせるのに十分なほど明確に文書化されているなら、そのエージェントにコードをレビューさせるのにも十分なはずです。

思考過程を示す

良いオーサーシップ（書き手としての責任）は常に重要でした。今はそれがさらに重要になっています。レビュアーはあなたのエージェントとのセッションに同席していたわけではなく、あなたが何を達成しようとしていたのか、どんなトレードオフを検討したのか、エージェントが下した数々の判断のうちどれを意識的に採用したのかといった、背景にある文脈を持ち合わせていません。その文脈は差分だけでは伝わりません。意図的に渡す必要があるのです。

それは、人間のレビュアーによる確認が必要なアーキテクチャ上の意思決定を明示し、何がなぜ変わったのかを説明することを意味します。レビュアーがコードを読む前から変更の物語が明確になるよう、コミット構成を注意深く考えることも含まれます。そして、エージェントが生成したものを自分が理解したことを示す説明を書くことです。もし明確に説明できないのであれば、能動的な関与から受動的な委任へと切り替わってしまったリスクがあるからです。

Addyが引用しているAnthropicの調査では、AIを受動的な委任のために使ったエンジニア、つまりAIにただコードを生成させて能動的に関わり続けなかったエンジニアは、AIを思考の道具として使ったエンジニアに比べて、理解度テストのスコアが著しく低かったことが示されています。エージェントはエンジニアの代替ではありません。あくまで道具であり、それが何を、なぜ行っているのかを、単に動くかどうかだけでなく、理解し続ける必要があります。その理解こそが、レビュアーが当然得られるべきものであり、ゼロから再構築させるのではなく、そこへ導くことがあなたの役割なのです。

すべての変更が同じリスクを伴うわけでも、同じ深さのレビューを必要とするわけでもありません。その違いを明示することも、良いオーサーシップの一部です。Ship / Show / Askは、変更の性質やチームとの間にすでに築かれている信頼に基づいてレビューのレベルを調整するための有用なフレームワークです。

速く動くために必要なもの

ドラフトのまま積み残されている5つのMRは、プロセスやコードに対する私の理解が足りないせいで止まっているのではありません。セーフティネットがないから止まっているのです。それが最初に果たすべき義務であり、リリースした後ではなく、リリースする前に修復すべきものなのです。

しかし、オーサーシップの取り組みなしに堅牢なテストスイートだけがあっても、レビュアーは「何も壊れていない」ことを確認できるだけです。それは、何が変わったのか、なぜ変わったのか、エージェントが下した判断のうちあなたが意識的に残したものは何なのかを理解することとは別問題です。エージェントはあなたに速度をもたらします。その速度を本物にするのは、単に動くということだけでなく、何をなぜ作ったのかを説明できることなのです。