11月3日、River Lynn Baileyが「Accelerate your understanding of unfamiliar code with AI Part 2」と題した記事を公開した。この記事では、AIを使って未知のコードベースを素早く把握する際に陥りやすい「理解した気になる罠」と、それを回避するための具体的な習慣について詳しく紹介されている。
「わかった気」は測定されている
新しいコードベースに初日でAIを投入すると、驚くほどスムーズに全体像が見えてくる。だがその感覚は、ダニング＝クルーガー効果における「自信のピーク（Peak of Confidence）」そのものだ。
この錯覚は数値で裏付けられている。
- METRの調査: 熟練開発者がAI利用で「20%速くなった」と感じたが、実際は19%遅くなっていた
- Anthropicの調査: 新しいライブラリをAI支援で学んだエンジニアの理解度テストのスコアは**50%、AI非利用グループは67%**。コード生成をAIに完全に委任したグループが最低スコアだった
- Pratherらの研究: 初心者プログラマーがAIを使って課題を終えた後、「能力があるという錯覚」を持って終了した
元凶はシンプルだ。AIの説明から得られる「理解した感覚」は、理解の証拠ではない。
グラウンディングがなければ説明は危うい
AIがコードを説明する際、実際のコードを参照せずにトレーニングデータのパターンから回答を生成することがある。その説明が「どこか別のコードベースでは正しい」ものである可能性を否定できない。
AIによるコードベース探索に関する研究も、言語モデルの「グラウンディングの欠如と構造化されたビューとの統合不足が効果を制限する」と指摘している。
説明がファイル名と行番号を示しているなら、開いて確認できる。示していないなら、それは答えではなくリードとして扱うべきだ。
最重要の習慣：自分でコードを読む
自信のピークにいるときに最も重要な規律は、説明に名前が挙がったエントリーポイントを自分で開いて、説明通りに動作することを確認することだ。
初日にすべてを検証する必要はない。ただし、これから依存する部分については確認しておく。コードとAIの説明が食い違っている箇所は、後から作業を始めたときに必ず落とし穴になる。
ピークで陥りやすい3つのパターン
1. 読む作業をAIに委任する
タイピングをAIに任せるのは意図的な選択になり得るが、読む作業を委任するのは別の話だ。Anthropicの調査が示す通り、最も多く委任したグループが最低スコアだった。
2. 自信たっぷりな説明を正しい説明と混同する
説明の「自信」は文体の特性であり、内容の正確さの指標ではない。
3. 「わかりきっているから」とメモを省略する
初日はすべてが自明に感じられる。しかし別のセッションで同じことを聞けば、説明は変わって出てくる。説明を保存し、検証しながら修正していくことが、後続の文書化（連載第4回のテーマ）の土台になる。
AIは使い倒す、ただし「アンカー」を効かせる
AIを使い控えるべきという話ではない。初日にヘビーに使うのは正しい判断だ。上記3つのパターンを意識しながら、説明を常にリポジトリに紐付けておくための習慣が重要になる。
- プロジェクトの全体像を先に渡す ― 何も聞く前に、モデルにプロジェクトの構造を把握させる
- 具体的な対象を指定する ― ファイル、ディレクトリ、モジュール、プルリクエストなど名前で指せるものを対象にする
- 最初に「なぜ」を聞く ― コードが存在する理由、そう設計された理由を先に把握する方が、「どう動くか」のウォークスルーより速く全体を掴める
対象が大きすぎて一度に説明しきれない場合は分割する。まずエリア全体の説明を得て、次にチケットが触れる各部分を個別に絞って聞く。
具体的なツール：Han
Test Doubleがオープンソースで公開している Han は、上記の習慣に対応したClaude Codeのスキルセットだ。
- /project-discovery: リポジトリの言語・フレームワーク・ツール・構成をスキャンし、
CLAUDE.mdまたはAGENTS.mdに参照用サマリーを書き込む。以降のセッションはここから始まる - /code-overview: ファイル・ディレクトリ・モジュール・ワークフロー・プルリクエストを対象に実ソースを読み、「なぜ」を先頭に置いたオーバービューを生成する。対象が大きすぎる場合はスキップした部分を明示するので、絞り込んで再実行できる
- /ddd-analysis: ドメイン駆動設計（DDD）の原則を用いてリポジトリ全体の境界づけられたコンテキストとドメイン言語をマッピングする。語彙が不慣れな場合の探索専用で、リストラクチャリングの提案は行わない
また、Claude Codeが提供するExplanatory出力スタイルは、コーディング中に実装上の選択やコードパターンについての短い「Insights」を付加してくれる。ピーク時の補助としては適切な量感だ。
「理解の谷」が来る前に
コードを変更すると、手元の説明の精度は下がる。説明が向いていたのはオリエンテーションであり、オリエンテーションはそのまま変更の根拠にはならない。それに気づいた瞬間が「気づきの谷（Valley of Realization）」への入り口だ。
理解はレイヤーで積み上がる。最初のレイヤーは制御フロー、つまり「何が何を、どの順で呼ぶか」だ。AIの説明はこのレイヤーを素早く与えてくれる。データフロー、設計の意図、コード全体のモデルは、実際に手を動かして初めて得られる。
連載第3回では、AIをメンターとして使いながら自分自身で変更を書いていく作業について取り上げる予定だ。
詳細はAccelerate your understanding of unfamiliar code with AI Part 2を参照していただきたい。
