コード生成が速くなるほど、自分のプロダクトが分からなくなる。AIエージェントの「理解負債」
AIエージェントへ実装を委ねるほど、設計判断や復旧に必要な理解が失われる「理解負債」。研究と個人開発の経験から、理解を保つための判断基準と実践を整理します。
以前、AIで開発コストが下がった結果、この1年で92個のプロジェクトに手を出し、個人開発が迷走した話を書きました（hfm.tokyo）。
あのとき増えたのは、プロジェクト数だけではなく、自分が深く理解していないコードも増えていました。
1年前は壁打ちしながらコードの実装方針を決めていたところ、
僕は最近、CodexやClaude Codeを使っていますが、AIの性能アップによって、主にゴールと理解できるライブラリやアーキテクチャを組み合わせた仕様設計を伝えたあと、実装の多くをAIエージェントへ任せています。
エージェントがコードを書く。
テストを実行する。
lintと型チェックを通す。
僕は差分を読み、問題がなさそうならマージする。
コードは動いているんです。
それでも、少し前に追加した処理を変更するとき、AIにコードベースを調査させ、どこを直すべきか説明してもらわないと、全体像がつかめないことがほとんどになります。
自分のリポジトリにあるのに、CodexやClaude Codeを閉じると、大量のディレクトリ・ファイルがエディタのVS Codeには存在していて、それをチェックするのが億劫になってしまいます。コードが急に他人のコードのように見えるからです...。
Redditのr/ExperiencedDevsに投稿された「The code comprehension trap」を読んで、いや、まさにこれだなと思いました。
投稿者は過去半年間、Claude CodeとOpus系モデルを使い、ほぼ全面的にAIエージェント中心の開発を続けてきたそうです。
その結果として出した結論は、かなり重いものでした。
AIコーディングの本当のコストは、トークンではない。コードベースへの理解で支払っている。
AIに実装を任せること自体が問題なのではありませんno
問題は、コードだけでなく、その実装過程で発生する小さな設計判断、失敗、探索、比較まで一緒に外注し、人間側にシステムの因果関係が残らなくなることです（Reddit）。
AIが書いたコードをレビューしているうちに、判断までAI製になる
AIエージェントを使った開発では、最初に人間が仕様や設計を書きます。
たとえば、次のような仕様です。
- ユーザーがファイルをアップロードできる
- アップロード後にバックグラウンド処理を実行する
- 処理が完了したらユーザーへ通知する
- 失敗した場合は再実行する
ここまでは人間が決められます。
しかし、実装へ落とす過程では、仕様に書かれていない判断が大量に発生します。
ファイルの状態をどこへ保存するのか。
同じ処理が二重に実行されたらどうするのか。
通知に失敗した場合、処理全体を失敗とみなすのか。
再実行回数をどこで管理するのか。
途中でプロセスが停止した場合、どの状態から復旧するのか。
これらは小さな判断に見えますが、積み重なるとシステムの振る舞いそのものになります。
AIエージェントは、既存コードと与えられた仕様から、それらの空欄を埋めて実装します。
人間は完成後の差分を読みます。
そのときに見えているのは、AIが下した判断の最終結果だけです。
なぜその構造を選んだのか。
ほかにどんな選択肢があったのか。
何を制約として判断したのか。
どこで既存コードと矛盾したのか。
実装中にどんなエラーが起き、どう修正したのか。
こうした途中経過は、差分からほとんど見えません。
さらに怖いのは、そのAI生成コードが、次の仕様を考えるときの前提になることです。
AIが以前作った構造を見て、人間もAIも「既存システムはこの設計になっている」と考えます。
その設計が妥当かどうかを再検討せず、次の機能を上へ積み重ねます。
最初の小さな判断ミスが、次の仕様、次のプロンプト、次の実装へ受け継がれていく。
Redditの投稿者は、これを「誤った前提によって仕様が汚染されていく状態」として説明しています。
コードの負債だけではありません。
判断の前提そのものが、少しずつ壊れていきます。
差分を読むだけでは、実装したときと同じ理解は残らない
自分でコードを書くとき、実際に学んでいるのは構文だけではありません。
既存コードを探し、依存関係を調べ、どこに処理を置くか考えます。
最初に考えた方法がうまくいかず、別の方法を試します。
エラーが出たら原因を予測し、ログを読み、仮説を修正します。
動いたあとも、ほかの機能を壊していないかを確認します。
この探索と失敗の過程で、頭の中にシステムのモデルが作られます。
たとえば「このデータはここで作られ、この処理を通り、この状態になったあと、このイベントを発生させる」という因果関係です。
コードの細かな内容を忘れても、どこを調べればよいかは覚えています。
ところが、AIが完成したコードを出し、人間が差分だけを読む場合、この過程が抜け落ちます。
AIが実装する
↓
人間は完成後の差分を読む
↓
探索、比較、失敗、修正を経験しない
↓
コードは読めるが、因果関係が頭に残らない
↓
レビューが妥当性の確認ではなく、違和感探しになる
↓
過去のAI出力が次の設計の前提になる
コードを読めることと、コードを理解していることは同じではありません。
説明を読んだ直後は、理解できたように感じます。
でも、AIを閉じて「この処理が途中で失敗したら、データはどんな状態になるのか」と聞かれると答えられない。
これはレビューというより、AIが出した説明に納得しているだけです。
AIのコード生成速度が、人間の理解速度を超えると、理解していないコードが在庫のように積み上がっていきます。
AIへ委譲した人ほど、デバッグ能力が残らなかった
2026年に公開された「How AI Impacts Skill Formation」という研究では、Pythonを1年以上使っている52人を、AI支援ありとなしの2グループに分け、未経験の非同期処理ライブラリ「Trio」を使った課題へ取り組ませています。
AI支援グループはGPT-4oを使い、コード生成や質問ができました。
その後、AIを使わず、概念理解、コード読解、デバッグ能力を測るテストを行っています。
結果として、AI支援グループでは作業時間の統計的に有意な短縮が確認されなかった一方、理解度テストでは27点満点中4.15点、17％相当の差が出ました。
最も大きな差が出たのは、デバッグに関する問題です（arXiv）。
ただし、AIを使った人が全員、理解できていなかったわけではありません。
研究者はAIの使い方を、いくつかのパターンに分類しています。
AIへコード生成やデバッグを全面的に委譲したグループは、理解度テストの平均が40％未満でした。
一方、AIに概念を質問した人、生成されたコードについて説明を求めた人、自分の理解を確認する質問をした人は、平均65％以上を記録しています。
同じAIを使っていても、結果がかなり違います。
違いは、AIを使ったかどうかではありません。
思考をAIへ委譲したか、思考するためにAIを使ったかです。
さらに興味深いのは、AIが生成したコードをコピーして貼り付けた人と、同じコードを手で入力した人の間で、理解度テストの得点に明確な差が確認されなかったことです。
指を動かしてコードを入力すれば、理解できるわけではありません。
理解を左右したのは、なぜこのコードになるのかを考え、エラーに遭遇し、自分で原因を推測することでした（arXiv）。
もちろん、この研究は約1時間の新しいライブラリ学習を対象にしたものであり、数カ月から数年のプロダクト開発を直接検証したものではありません。
研究者自身も、今後はAIコーディングエージェントを使った長期的な技能形成を調査する必要があるとしています（arXiv）。
それでも、「AIを使うと必ず能力が落ちる」のではなく、全面委譲するほど理解が残りにくくなるという構造は、Redditの投稿者が経験した問題と一致します。
技術的負債より見つけにくい「理解負債」
Addy Osmaniは、この問題を**理解負債（Comprehension Debt）**と呼んでいます。
理解負債とは、コードベースに存在するコードの量と、人間が本当に理解しているコードの量との間に広がる差です（O’Reilly）。
技術的負債なら、コードを調べることで見つけられます。
重複が多い。
依存関係が複雑になっている。
テストが不足している。
変更するたびに別の場所が壊れる。
こうした問題は、コードや開発指標に表れます。
理解負債は、もっと見つけにくい。
テストは通っています。
コードカバレッジも高い。
PRの数も増えています。
リリース速度も上がっています。
それでも、そのコードについて責任を持って説明できる人がいません。
しかも、コードを確認している本人が「自分は理解している」と思っているため、問題として認識されにくい。
僕は、理解負債が次の3段階で進むと考えています。
| 段階 | 起きること |
|---|---|
| 理解負債 | データや処理の流れを、自分の言葉で説明できない |
| 判断負債 | 複数の設計案を比較し、どちらが適切か判断できない |
| 所有権の消失 | 障害や大きな仕様変更のとき、誰も責任ある判断を下せない |
最初は、コードの一部が分からないだけです。
次第に、過去のAI出力を前提に設計するようになります。
最後には、AIへ聞かなければコードベースを移動できず、AIの回答が妥当かどうかも判断できなくなります。
リポジトリの所有者は存在します。
でも、システムの知的な持ち主がいません。
これが、理解負債の最も危険な状態です。
AIモデルがもっと賢くなれば、解決するのか
Redditの投稿では、AIのコンテキストウィンドウや記憶の限界も問題として挙げられています。
以前解決したバグをエージェントが参照できず、別の場所で同じバグを再発させる。
人間もコードベース全体を把握していないので、なぜ再発したのか分からない。
現在のAIエージェントでは、確かに起こり得る問題です（Reddit）。
ただ、理解負債の原因をAIのコンテキスト不足だけにすると、本質を外します。
モデルのコンテキストは今後も広がるでしょう。
長期メモリやコード検索も改善します。
プロジェクト全体を高い精度で理解するモデルが登場する可能性もあります。
それでも、AIが理解していることと、人間が理解していることは別です。
モデルが正確になるほど、人間がコードへ介入する機会は減ります。
普段の実装、テスト、修正はAIが行い、重大な障害が起きたときだけ人間が呼び戻される。
しかし、人間は日常的にその作業をしていないため、最も難しい状況で必要になる技能を失っています。
これはAIコーディングだけの新しい問題ではありません。
Lisanne Bainbridgeは1983年の論文「Ironies of automation」で、自動化は人間の問題を消すのではなく、異常時の対応を人間へ残すことで、かえって難しい問題を生み出す場合があると論じています（ScienceDirect）。
日常的な処理は自動化されている。
人間は監視するだけです。
ところが、通常とは異なる事態が発生した瞬間、自動化されたシステムを深く理解していない人間に、最も難しい判断が要求されます。
AIエージェントで実装し、障害時だけ人間が引き継ぐ構造は、僕にはこの自動化の皮肉とほとんど同じに見えます。
AIが賢くなれば、AI側の理解不足は減らせます。
人間側の理解不足は、AIの性能向上だけでは解決できません。
「重要なコードは手書きすべき」は半分だけ正しい
Redditの投稿者は、理解負債への解決策として、重要なビジネスロジックを自分で手書きすることを挙げています。
数学の参考書を読むだけではなく、実際に問題を解かなければ身につかないのと同じだという主張です（Reddit）。
これは半分正しいと思います。
自分で実装すれば、問題の分解、既存コードの探索、失敗、デバッグを強制的に経験します。
特に、次のような領域では、自分で実装過程へ深く関わる価値があります。
- 課金と決済
- 認証と認可
- ユーザーデータの削除
- DBマイグレーション
- 並行処理
- 冪等性
- 残高や在庫
- プロダクト固有の重要な業務ルール
一方で、「自分でタイプしたから理解している」とは限りません。
人間が書いたコードにも、偶然動いているもの、よく分からないままコピーしたもの、ライブラリの挙動を誤解したものがあります。
先ほどの研究でも、AI生成コードを手で入力するだけでは、理解度の明確な改善につながりませんでした。
また、経験豊富なエンジニアは、すべてのコードを自分で書くわけではありません。
チームメンバーへ実装を委譲し、モジュール内部の全行を知らなくても、インターフェース、責任範囲、データの流れを理解してシステムを設計します。
Redditのコメント欄でも、モジュール境界と重要なインターフェースを理解していれば、内部実装をすべて把握する必要はないという反論が出ていました。
手でコードを書くことと、システムを理解することは同じではないという指摘もあります（Reddit）。
したがって、境界線は、
AIが書いたか、人間が書いたか
ではありません。
そのコードについて、人間が説明し、変更の影響を予測し、障害時に調査できるか
です。
手書きは、理解を取り戻すための有効な方法です。
ただし、すべてを手書きに戻す必要はありません。
理解できているかを確認し、理解できない重要部分だけを、自分で調査し直す。
場合によっては、自分で書き直す。
手書きは原則ではなく、理解テストに失敗したときの強制的な学習手段として使うのがよさそうです。
ソロ開発・ソロプレナーでは、理解負債がそのまま事業負債になる
会社の開発チームなら、自分が理解していないコードを、ほかの誰かが理解している可能性があります。
設計した人。
実装した人。
レビューした人。
運用している人。
障害対応を経験した人。
ソロ開発では、その誰かが存在しません。
AIエージェントが何人もの開発者のように動いても、次の責任はすべて一人の人間に残ります。
顧客の要望を、どの機能へ反映するのか。
料金体系を変えたら、どこへ影響するのか。
ユーザーのデータが消えたとき、復旧できるのか。
決済の二重実行をどう防ぐのか。
プロダクトの方向転換に合わせ、データモデルを変えられるのか。
将来、別の開発者へ引き継げるのか。
AIは調査と実装を手伝えます。
でも、その判断の結果について、事業上の責任を引き受けることはできません。
理解負債が増えると、機能開発が遅くなるだけではありません。
大きな変更をするのが怖くなります。
どこが壊れるか分からないので、既存構造を変えず、その上へ新しい処理を追加する。
コードが複雑になる。
さらに理解しにくくなる。
そして次の変更も避ける。
最終的には、顧客から得た学びをプロダクトへ反映できなくなります。
AIによって実装速度は上がっているのに、事業の意思決定速度は下がっていく。
これは技術的負債というより、事業の機動力に対する負債です。
ソロ開発にとって、コードベースを理解する能力は、単なるエンジニアリングスキルではなく、自分の事業を方向転換し、改善し、生き残らせるための能力です。
これらの問題を解決するためにも、ハーネスエンジニアリング・コンテキストエンジニアリングの考え方を実践していくことで負債にしないAI活用を実践したいところです。
AIを使わない状態で、5つの質問へ答えられるか
自分がコードを理解しているかどうかは、コードを見て「分かる気がする」と感じても判断できません。
そこで、AIを閉じた状態で、次の質問へ答えられるかを確認します。
1. 処理の流れを説明できるか
入力はどこから入るのか。
どこで検証されるのか。
どのデータが変更されるのか。
どんな外部サービスが呼ばれるのか。
最後にユーザーへ何が返るのか。
2. 守るべき不変条件を説明できるか
どんな状況でも破ってはいけないルールは何か。
たとえば、次のようなものです。
- 同じ決済を二度実行しない
- 他人のデータを参照できない
- 残高が負数にならない
- 削除済みデータを再利用しない
- 同じイベントを複数回処理しても結果が変わらない
3. 主な失敗パターンを説明できるか
APIがタイムアウトしたらどうなるのか。
DBの更新後に通知が失敗したらどうなるのか。
途中でプロセスが停止したらどうなるのか。
同じ処理が同時に二つ実行されたらどうなるのか。
再実行しても安全なのか。
4. なぜこの設計なのか説明できるか
ほかにどんな設計案があったのか。
何を優先し、何を諦めたのか。
既存コードの都合なのか。
性能、保守性、安全性のどれを重視したのか。
5. 仕様変更の影響範囲を予測できるか
料金体系を変える。
認証方式を変える。
外部APIを変更する。
DBのカラムを削除する。
このような変更を行う場合、どのファイル、データ、テスト、外部連携が影響を受けるのか。
重要な質問へ答えられないなら、そのコードはレビュー済みではあっても、まだ自分のものにはなっていません。
AIに説明させれば答えられる、では足りません。
AIの説明が正しいかを判断するために、こちら側の理解が必要だからです。
コードを書く仕事が減るほど、理解する仕事は増える
AIによって、コードを書くコストは急速に下がりました。しかし、コードを理解するコストまで下がったわけではありません。
むしろ、大量のコードを短時間で生成できるようになったことで、何が重要で、なぜこの設計になり、どこが壊れやすいのかを把握する能力は、以前より希少になっています。
AI時代に価値を失うのは、構文を思い出しながらコードを入力する能力です。
一方で、価値が上がるのは、システムの因果関係を理解し、設計を選び、その結果へ責任を持つ能力です。
AIにコードを書かせることはできます。
AIにテストさせることもできます。
コードベースを調査させ、障害の原因候補を探させることもできます。
でも、そのコードを顧客へ提供し、料金を受け取り、問題が起きたときに結果を引き受けるのは自分です。
コード生成が安くなるほど、理解は開発で最も高価な工程になります。
AIに実装を任せてもいい。
ただし、理解、判断、復旧、説明責任まで一緒に渡さない。
AIを閉じても自分のプロダクトを説明できる状態だけは、失わないようにしたいところです。