無料記事 2026.10.02 読了約8分

誰も説明できないAIのコードは、どこで防げるのか？

@nifuda ・ 1本

作った人がいなくなったツールを引き継ぐと、動いてはいるのに、なぜその処理なのかを説明できる人がいない。そういう場面は少なくないと思います。AIが書いたコードでは同じことが作った本人のいるうちから起きていて、理由の置き場所を先に決めておくほうが早いと僕は考えています。

引き継いだコードに残っていないもの

半年前に入ったコードについて、なぜこう書いたのかを聞ける人は、あなたの現場にまだいるでしょうか？

コードは残りますし、動くかどうかも確かめられます。残らないのは「なぜそうしたか」のほうで、引き継ぐ側が一番ほしいのはそこなんですね。在庫を夜間にまとめて更新するのか、その都度更新するのか。単価の端数を切り捨てるのか、四捨五入するのか。どちらでも動く選択ほど、理由が残っていないと次の人が良かれと思って直してしまいます。

AIが書いたコードでは、その理由が最初から誰の頭にもないことがあります。コードレビューを担当するITエンジニア322名を対象にしたキッカケクリエイションの調査（2026年4月公表）では、AI生成コードのレビューで問題だと感じた点として最も多かったのが「提出者本人がコードの内容を説明できなかった」で、49.5%でした。本人も理解しないまま取り込まれたコードがたまっていく状態は、最近では「理解負債」と呼ばれることもあります。作った人が辞める前から、説明できる人がいないわけです。

AIのコードより困るのは、誰も知らない状態

スイスのデータエンジニアSimon Spätiさんも、同じ問題を「The problem is not the AI code, but nobody knows anything anymore」という記事に書いています（2026年9月公開）。困るのはAIのコードそのものより、個人やチーム全体が、システムの構造や「なぜその選択をしたのか」という意図を知らなくなっていることだ、というのが主張の中心です。

記事では、仕様もコードもテストもプルリクエストもチケットも全部Claude Codeが作っていて、誰も何も分かっていない、というエンジニアの投稿が引かれています。COBOLを書ける人が現場を去っていく問題を、エージェントによるコーディングがあらゆる言語に広げる、という指摘も紹介されていました。個人的に一番引っかかったのは、手軽に作れるほど保守しなければならないものが増える、という一文です。

一方で、元記事は具体的な手順を示していません。人がAIに方向を与える必要があり、意図やセンス、設計、アーキテクチャがいま強みになる、というところで終わっています。ジュニアの採用に触れる一文はありますが、それ以上は展開されていません。ここから先のCLAUDE.md、ADR、レビュー前の説明は、元記事の主張ではなく、引き継ぐ側から考えた僕の提案です。

AIが書いたコードを引き継ぐとき、理由はどこに残っているか？

説明できる人がいないとき、理由を探しに行く先はだいたい決まっています。コミット履歴とメッセージ、READMEや設定ファイルのコメント、実行ログ、それから実際に使っている部署の人への聞き取りです。

このうち聞き取り以外は、AIが一緒に書けてしまいます。コミットメッセージは丁寧に整っていて、何を変えたかはよく分かるのに、なぜ変えたかは書かれていない。そういう履歴はこれから増えていくと思います。AIは頼まれた範囲のことを書くので、頼んだ人が理由を言葉にしていなければ、どこにも残りません。

裏を返せば、理由を一度でも言葉にして決まった場所に置いておけば、後からでも拾えます。置き場所として現実的なのは、次の3つだと考えています。

CLAUDE.mdに書くのは、やらなかったことの理由

Claude Codeには、セッションの始めに毎回読み込まれる指示用のMarkdownファイルがあります。プロジェクト直下に置くCLAUDE.md（または.claude/CLAUDE.md）で、公式ドキュメントでは、ビルドやテストのコマンド、コーディング規約、設計上の判断などを書く場所として説明されています。

AI向けのファイルですが、リポジトリに入っている以上、次の担当者も読みます。ディレクトリ構成や使っているライブラリはコードを見れば追えるので、書く価値があるのはコードから読み取れないことですね。公式ドキュメントでも、/doctorによる点検はコードから導ける構成や依存関係の一覧を削るよう提案し、落とし穴や判断の理由は残す、と説明されています。

僕が書いておいてほしいのは、やらなかったことの理由です。一見おかしく見える箇所ほど、次に触る人もAIも「改善」したくなるからです。たとえば、こういう書き方です。

## 変えるときは相談してほしい判断
- 在庫の更新は夜間バッチでまとめて行う。即時更新にはしない。
  理由: 基幹システム側の在庫が確定するのが毎日22時のため
- 単価は小数点以下を切り捨てる。四捨五入にはしない。
  理由: 取引先との契約書の計算方法に合わせている
- 帳票のCSVはShift_JISで出力する。UTF-8にはしない。
  理由: 受け取る経理システムがShift_JISしか読めない

中身は説明のために作った例です。公式は1ファイル200行未満を目安にしているので、理由が要る判断だけに絞るくらいでちょうどいいと思います。あなたのリポジトリのCLAUDE.mdは、コマンドの一覧だけになっていないでしょうか？

ADRの下書きはAIに、理由は人が書く

CLAUDE.mdが「いまの決まり」を置く場所だとすると、判断ごとの経緯を1件ずつ残す書式もあります。決めたことごとに短い文書を1枚作り、背景と決定、その結果どうなるかを書いておくもので、ADR（Architecture Decision Record）と呼ばれます。『Release It!』の著者として知られるMichael Nygardさんが2011年のブログ記事で提案した形で、1件を1〜2ページに収めて通し番号を振ります。

引き継ぐ側にとってありがたいのは、決定を覆したときも古い記録を消さず、「置き換えられた」という状態にして残すところです。いまの決まりの前に何を試してやめたのかが、同じ場所で追えます。

下書きはAIに任せてよいと思います。判断を決めた直後の同じセッションなら、検討した案や比べた点が会話に残っているからです。頼み方はたとえばこうです。

いまのやり取りで決めたことを、ADRの下書きにしてください。
項目はタイトル、ステータス、背景、決定、結果の5つです。
検討して採らなかった案と、採らなかった理由も書いてください。
会話から分からない業務上の事情は推測で埋めず、「要確認」と書いて空けてください。

背景の欄は、人が直す前提にしておきます。AIが知っているのは会話で話された範囲だけで、取引先の都合や社内の運用ルールは、言われなければ書けません。それらしい理由で埋めてくることもあるので、「要確認」で空けさせて人が埋める。この分担なら、書く手間はだいぶ減るはずです。

レビュー前にAIへ説明させると、何が見えるのか？

あなたのチームのプルリクエストには、なぜその書き方にしたのかが書かれているでしょうか？

最後の置き場所は、マージする前の会話です。AIが書いたコードをレビューに出す前に、そのコードの説明をAIにさせてみます。聞くのは「何をしているか」より「なぜこう書いたか」のほうがいいと思います。

この差分について、処理ごとに「なぜこの書き方を選んだか」を説明してください。
別の書き方を検討した箇所は、その案と採らなかった理由も添えてください。
コードや会話から理由が分からない箇所は、分からないと書いてください。

具体的な理由が返ってくる箇所は、少なくとも会話の中で理由が言葉になっていた箇所です。「この関数はデータを処理します」のようにコードを言い直しただけの説明や、「分からない」と返ってくる箇所は、誰も理由を持たないまま入ろうとしているコードだと見ています。先ほどの調査で最も多かった「本人が説明できない」状態を、レビューの前に見つけられるわけですね。

ただ、AIの説明をそのままプルリクエストの本文に貼るのは避けたほうがいいと思います。AIは後付けでも筋の通った理由を書けてしまうので、もっともらしい説明が実際の理由だとは限りません。提出者が読んで「その理由で選んだ」と言える部分だけを残し、言えない部分は質問としてレビュアーに渡す。レビューする側も、その質問から読み始められます。