手法1：変更を教える説明を作る

前の章では、AIエージェントに任せて理解を後回しにすると、あとで人間が仕事に参加できなくなるという問題を見ました。ここからは、その問題に対する具体的な技法を見ていきます。最初の技法は、コードの変更そのものを、人間に教える機会にすることです。

差分を見せるだけでは足りない

AIエージェントは、大きなコード変更を人間より速く作れます。しかし、変更が正しいかを確認できても、その変更が何を意味するかを理解できるとは限りません。ファイル名と赤・緑の行だけを並べた生のコード差分（raw diff）は、変更された場所は示します。けれども、読者が必要とする背景や、変更同士の関係までは自動的に示しません。

話し手が提案する コード解説（code explainer） は、短く整えた差分ではありません。ある変更を理解するために、その読者向けに作られた小さな学習課程です。最初に必要な背景を説明し、次に変更の目的と考え方を示し、そのあとで実装の詳細へ進みます。

補足： これは「人間が必ずすべての行を順番に読むべきだ」という意味ではありません。目的は、行を一つずつ追うこととは別の道から、システムの働きと変更の意味をつかむことです。

図1：赤と緑のコード差分の下に、人物と矢印を使った説明用の図が置かれています。

このスライドは、単なる赤・緑の比較と、それを人間に理解させるための説明とを対比する発表用グラフィックです。周囲の人物や矢印は、差分を読む行為を学習可能な説明へつなぐイメージとして読めます。ただし、実際の解説文書の正確なレイアウトやコード実装までは、この映像から確認できません。動画の00:06:58で見る

Zenガーデンの変更を一つの物語にする

話し手が見せる具体例は、Zenガーデンのゲームです。このゲームは、上から見た表示（top-down）から、アイソメトリック表示（isometric）へ変わりました。アイソメトリック表示は、2Dの画面上で奥行きがあるように見せる表現です。

ここで大切なのは、解説が「このファイルのこの行が変わった」という一覧で終わらないことです。先にゲームのエンジンや座標の考え方を置くと、読者は、なぜ庭の見え方を変える必要があるのか、どの部分の関係が変わるのかを考えられます。話し手は、こうした解説をHTML、Markdown、または共同編集できるNotion文書として作る実践を紹介しています。

図2：「Code explainer doc」と題されたNotion風の文書が、Zenガーデンの表示変更を説明しています。

このスライドには、Zenガーデンを上から見た表示からアイソメトリック表示へ変えるための文書が見えます。したがって、コード解説が変更の背景と目的を含む文書として提示されていることは確認できます。一方、細かい実装の文章は小さいため、具体的なアルゴリズムやファイル構成が示されているとは断定できません。動画の00:07:46で見る

まず背景を作る

この解説文書は、いきなり変更行から始まりません。話し手の例では、まずゲームエンジン、座標系、いくつかのサブシステムを紹介します。ここでいう座標系は、画面上の物体の位置をどのように表すかという基本的な仕組みです。サブシステムは、ゲームの中で特定の役割を受け持つ部分です。

この背景があると、読者は変更を孤立した行の集まりとしてではなく、既存の仕組みの中の出来事として見られます。たとえば、座標の扱いを先に知っていれば、画面の見え方を変える変更が、位置や描画の関係に触れていると考えやすくなります。背景は飾りではありません。あとで出てくる詳細を解釈するための土台です。

図3：変更の前に、Phaser 3、座標系、平面キャンバスについて説明する背景文書が示されています。

見えているスライドは、Phaser 3というゲームエンジンと、平面のキャンバス、そしてシーンを描画する部品についての概要を置いています。つまり、変更されたコードを読む前に、どの環境でその変更が働くのかを説明しています。細かい本文は小さく、すべてを正確には読めないため、ここから具体的な実装内容を推測してはいけません。動画の00:08:01で見る

共同文書なら理解を一人で終わらせない

解説を共同編集できる文書にすると、理解は作成者だけのものではなくなります。チームメートは文書のその場所にコメントを書き、分からない点を質問できます。別の人は、その質問への答えや自分の考えを同じ場所に追加できます。

この仕組みには、二つの効果があります。第一に、変更を読む人が、自分の疑問を記憶して別の場所で尋ねる必要が減ります。第二に、質問と答えが文脈つきで残るので、あとから読む人も同じ説明を使えます。これは、AIにコードを書かせたあと、人間を会話から外すのではなく、人間どうしが同じ変更について考えるための場所を作る方法です。

この技法の流れ

この章の実践を、次の順番にまとめられます。

1. 変更の背景を示します。 ゲームエンジン、座標系、サブシステムなど、読者が必要とする土台を説明します。
2. 変更の意味を説明します。 Zenガーデンの表示が上から見たものからアイソメトリック表示へ変わる、というように、何を変えたいのかを言葉にします。
3. 詳細へ進みます。 背景と目的を手がかりにして、変更されたコードを読みます。
4. 共同で理解を深めます。 HTMLやMarkdown、Notion文書など、読者がコメントや質問を残せる形で共有します。

これは、コード差分を捨てる方法ではありません。差分を、読者が理解できる順番と文脈の中へ置き直す方法です。AIエージェントが大量のコードを作るほど、この順番が重要になります。変更された行をすべて見せても、読者がその変更を使って次の判断やアイデアを出せなければ、理解の機会は失われるからです。

まとめ

話し手の第一の技法では、エージェントのコード変更を「納品物」だけでなく「授業」にします。背景を先に置くことで、実装の詳細を読むためのモデルを作ります。Zenガーデンの例では、上から見た表示からアイソメトリック表示への変更を、その背景とともに説明します。そして、HTML、Markdown、共同編集できるNotion文書によって、個人やチームがその理解を深められるようにします。

この章での中心的な考えは、差分を見せることと、変更を理解できるように教えることは同じではないという点です。次の原則では、この説明の順番をさらに絞り、実装の細部より先に変更の直感と目的を示します。

不確実性： 話し手が説明した解説文書そのものや実際のコードは提供されていません。そのため、この章では、確認できた目的、背景、表示例だけを扱い、文書の正確な構成や実装の詳細は補っていません。