11月19日、River Lynn Baileyが「Accelerate your understanding of unfamiliar code with AI」と題した記事を公開した。Test DoubleのシニアソフトウェアコンサルタントであるBaileyによる「未知のコードベースとAI」をテーマにしたシリーズのPart 4にあたり、AIツールを使いながら未知のコードベースへの理解を着実に積み上げ、開発速度を回復させるための実践的な習慣と落とし穴について詳しく紹介されている。
「AIを使うと速い」という感覚は幻かもしれない
AIコーディングツールは確かに作業を速める。しかし、その「速さの感覚」が実際の生産性と一致しているかどうかは別問題だ。
METR(機械知能評価研究所)の調査では、熟練のオープンソース開発者がAIを使って20%速くなったと感じた一方、実測では19%遅かったという結果が出た。速さの感覚は、実際の速さの証拠にならない。
この逆説は、AIが生成したコードや説明を検証する習慣が失われたときに起きる。Baileyは、この問題に対して「検証ループ(verification loop)」という習慣を中心に据えることを提唱する。
検証ループが理解の差を生む
Qiaoらの研究論文では、15人の大学院生が既存のコードベースにGitHub Copilotあり・なしで機能を実装した。Copilotを使ったグループは実装が速く、エラーも少なかった。しかし、コードベースへの理解度テストのスコアはCopilotの有無で変わらなかった。
差をつけたのは「ツールを使ったかどうか」ではなく「生成されたコードを立ち止まってレビューしたかどうか」だった。理解度の高い学生は、低い学生に比べてCopilotの生成コードを約5倍の頻度でレビューしていた。
Anthropicによる調査も同じ方向を示している。AIを使ったエンジニアの理解度テスト平均は50%、手でコードを書いたグループは67%だった。ただしAI利用者のうち、AIに概念的な質問をしたり生成コードの説明を求めたりしたグループは65%以上を記録した。AIに作業を丸投げしたグループは40%未満にとどまった。
つまり、AIの出力を問い直した人だけが理解を深めた。
Slope of Growth:「分かってきた」段階でこそ検証を手放さない
記事の核心概念が「Slope of Growth(成長の坂)」だ。これはシリーズ全体を通じたロードマップの中で、未知のコードベースに対して「分かってきた」という感覚が戻り、開発速度が上向き始める段階を指す。Part 4はこの段階に特化した内容であり、速さの感覚が回復したまさにそのタイミングで検証習慣を手放してしまうリスクを中心に論じている。
この段階では、AIに再び大量の作業を任せることが可能になる。ただし、以下の条件が揃っている場合に限る。
- 変更が入るコードと概念を、自分で一歩ずつ踏み込んで理解している
- AIが間違いを犯したときに気づける状態になっている
- 対象システムがどう動き、なぜその変更を行うのかを把握している
この条件を満たしたうえで、AIが生成したコードは「他の誰かのプルリクエスト」と同じように扱う。ファイルを開いて、実際のコードと照合して確認する。その作業が速くなっているのは、どこを見ればいいかを知っているからだ。
理解をドキュメントとして残す
個人の頭の中やチャット履歴に理解が留まっている限り、次にそのコードに触れる人(数ヶ月後の自分かもしれない)は同じコストを払い直す。AIは同じコードを毎回少し違う形で説明するため、ドキュメントがなければ理解の再構築を繰り返すことになる。
対策は、理解をリポジトリかドキュメント管理システムに書き込むことだ。そのドキュメントをCLAUDE.mdまたはAGENTS.mdから参照すれば、以降のすべてのセッション(人間でもAIエージェントでも)が参照できる。Claude Codeはセッション開始時にCLAUDE.mdを読み込み、@pathインポートをコンテキストに展開する。毎回コンテキストに含めたい場合は@docs/your-feature.mdと記述すれば自動的に読み込まれる。なお、CLAUDE.mdやメモリ機能の詳細はClaude Codeの公式ドキュメントを参照されたい。
また、ドキュメントはコードが変われば陳腐化する。定期的にソースコードと照合して修正する必要があり、AIツールで更新を自動化できる部分はそうすべきだと記事は述べる。
ドキュメントのメンテナンスは「バスファクター(プロジェクトが危機に陥る前に離脱が許容される人数の指標)」の向上にも直結する。コードの理解が一人の頭の中にしかなければ、その人が離れた瞬間に知識は失われる。
ツール:han
記事はドキュメント作業の自動化を支援するオープンソースのClaude Codeスキル集「han」を紹介している。主なスキルは以下の通りだ。
- /project-documentation: コードを読んでフィーチャーやコンポーネントのドキュメントを生成し、
CLAUDE.mdに参照を追加する - /project-documentation-to-confluence: 同じ処理を行いConfluenceページとして公開する
- /architectural-decision-record: 意思決定の背景・却下した代替案・理由をADR(アーキテクチャ決定記録)として残す
- /coding-standard: プロジェクトのコーディング規約を作成・更新する
- /edit-for-readability: ドキュメントの文章を「結論を先に」の構造に書き直す
ただし記事は「スキルは検証ループを置き換えない」と明示している。生成されたドキュメントもコードに関するひとつの主張に過ぎず、他の主張と同じ扱いをする。ファイルを開いて、書かれていることを確認する。
Slope of Growthでの落とし穴まとめ
記事が挙げる「Slope of Growth」段階における主な落とし穴は以下の3点だ。
- 新たに築いた検証ループを手放す: 速さの感覚が戻ったタイミングで検証をやめてしまいがち
- ソースではなく記憶からドキュメントを書く: 自分の誤解がそのままドキュメントに固定されるリスクがある
- ドキュメントをメンテナンスしない: コードと乖離したドキュメントは最終的に誰にも読まれなくなる
詳細はAccelerate your understanding of unfamiliar code with AIを参照していただきたい。




