執筆者：DigKnow株式会社 CTO 桑原 脩

AIコーディングがコードを書く速度を何倍にも引き上げた一方で、その理解を支えるドキュメントは相対的に痩せ細っていく——ここまでほぼ毎日ブログ記事を書きながら、私はこの構造を繰り返し見つめ直してきました。ここで自然に湧いてくる問いがあります。書くのを速くしたのがAIなら、整えるのもAIに任せれば済むのではないか。半分はそのとおりで、もう半分は、そう簡単でもありません。今日は、可能性と現実の境界線がどこにあるのかを、開発の当事者として、できるだけ正直に書いてみます。

　

「AIが作った問題は、AIが解けるのか」という問い

問いの立て方そのものに、ある皮肉が含まれています。コードを10倍速く書けるようにしたのはAIで、その結果として「説明されないコード」が急増した。ブログ記事の軸として書いた[コードは残るが、仕様は誰も知らない]で名付けた構造問題は、まさにこれです。だとすれば、説明する側もAIに肩代わりさせればいい——理屈としては、まっすぐ筋が通っています。
そして、この発想は的外れではありません。コードを読み、構造を解析し、人間が読める形に書き起こす作業は、AIがかなり得意とする領域です。私自身、技術ドキュメント自動生成サービスを開発している立場ですから、ここに勝機があると本気で考えています。けれど当事者だからこそ、過大な期待を煽る書き方はしたくありません。可能性だけを語れば宣伝になり、限界だけを語れば諦めになる。その間に引くべき一本の線を、これから探していきます。

　

可能性：AIが本当に向いている領域

まず、明るいほうから書きます。AIがドキュメント問題に効く理由は、感覚ではなく構造で説明できます。共通するのは、いずれも「コードという事実情報からの距離が近い」ことです。

①書くコストを限りなくゼロに近づけられる。以前の記事で、解決の方向性は「書くコストをゼロに近づける」か「書かなくても残る仕組みを作る」かのどちらかだと書きました。AIは前者を正面から担えます。リポジトリを解析し、プロジェクト概要書やシーケンス図、フローチャートといった「what」「how」を、秒単位で書き起こす。人間が分〜時間単位で払っていたコストが、桁違いに下がります。

②鮮度を機械的に保てる。ドキュメントが信頼を失う最大の原因は、コードが変わっても追従しないことでした。人間はリファクタのたびに図を描き直しません。けれどAIは疲れない。コードが更新されたら再解析して書き直す運用なら、「古くて嘘をついているドキュメント」という最悪の状態を、構造的に避けられます。

③網羅性で人間を上回る。人間は「重要そうな2割」しか文脈を残せませんでした。AIは全ファイルを淡々と処理し、関数の依存やテーブル定義といった事実を取りこぼしません。ある変更がどこに波及するかという差分の把握も、毎リリース人間が書ききるのは難しい一方、AIなら「目の付けどころ」を示せます。

具体的な場面で考えてみます。エンタープライズの新規顧客から、契約前のセキュリティ監査でシステム概要書の提出を求められた、という状況です。多くの現場で、ここから数日が消えます。最新の構成を知る人を捕まえ、記憶を頼りに資料を起こし、レビューする。AIが常に最新の概要書を生成し続けている状態なら、この数日が数分になる。これは「あったら便利」ではなく、商談のスピードに直結する実利です。

　

現実：AIが越えられない二つの壁

ここからが、当事者として正直に書いておきたい部分です。AIには、構造的に越えられない壁が二つあります。
一つ目の壁は「why」です。前回の記事でも触れたとおり、コードに残るのは「何をするか」「どう動くか」までで、「なぜこの設計を選んだのか」「なぜこの分岐を残すのか」は、コードのどこにも書かれていません。採用された案は残りますが、検討の末に捨てられた案も、三年前の障害という背景も、痕跡しか残らない。AIはコードを読んで解析しますから、コードに無いものは、どれだけ賢くても復元できません。頼めばそれらしい文章は出てきますが、それは「実際の経緯」ではなく「ありそうな経緯」です。もっともらしい架空の理由を、AIは平気で生成してしまう。これが、ドキュメント生成における最も厄介な失敗の形です。

二つ目の壁は、検証です。見落とされがちですが、私はこちらのほうが根が深いと思っています。コード生成にはまだ救いがあります。生成されたコードは実行でき、テストや型チェッカーが機械的に正しさを確かめてくれる。ところが、ドキュメントにはそれがありません。「このAPIは認証のあとに呼ばれる」と書かれていたとき、確かめるには実装を追い、呼び出し関係を辿り、過去の議論を掘り返すしかない。正しさを検証するコストが、手で書くコストとほとんど変わらないのです。

だから、AIが生成したものを「だいたい合っていそう」で受け入れた瞬間、技術的負債は減ったように見えて、実は「検証されていない仕様書」という別の負債に置き換わっています。たとえば、深夜の障害対応で、当事者でないエンジニアが自動生成されたシーケンス図を頼りに原因を切り分けている場面を想像してみてください。図の大筋は正しい。けれど運用で例外的に挟まるリトライ処理が、図には現れていなかった。そのズレに気づかず「ここは問題ない」と判断を進めれば、復旧はかえって遠回りになります。何も無ければ人は慎重にコードを読む。中途半端に正しい一枚があると、人はそれを信じてしまう。精度問題が怖いのは、間違いそのものより、間違いを信じさせる説得力のほうなのです。
なお、人間にしか残せない「why」も一枚岩ではありません。①設計判断の理由（何を諦め、どの制約と引き換えに何を取ったか）、②ドメインの暗黙知（業界の慣習や規制、顧客との約束）、③判断の優先順位（当時の人員・納期・競合のなかで、なぜこちらを選んだか）。どれも人間の頭のなかにしかなく、コードを掘っても出てきません。

　

では、勝機はどこにあるのか

可能性と限界を並べると、現実的な解の形が見えてきます。「AIが完璧なドキュメントを全部書く」ではありません。そんな未来を売り込むのは、当事者としてもむしろ不誠実だと思っています。
筋がいいのは、層を分けることです。量が多く、人間がやると消耗し、コードから機械的に導ける「what」「how」はAIに任せる。量は少ないが決定的で、人間の頭のなかにしか無い「why」は人間が残す。これまでのドキュメント運用が苦しかったのは、人間がこの両方を背負わされていたからではないでしょうか。
ただ、「what」「how」をAIに任せる、と一言で言っても、そこには先ほどの検証の壁がそのまま残ります。生成して放置すれば、いずれ「中途半端に正しい一枚」へと劣化していく。だからこそ、現実的な主戦場は実はここにあります——what/howを、常に最新で、かつ検証できる状態のまま生成し続けられるか。これは「コードから読めるのだから簡単」という話では全くなく、鮮度と信頼を仕組みとして担保できて初めて成立する、それ自体が難しい勝負どころです。AIがこの層を人間の手から確実に外せたとき、はじめて人間は残った「why」だけに集中できる。書く総量が減るからこそ続けられ、文化や気合に頼って失敗してきた運用が、ようやく構造として回り始めます。
では、残った「why」のほうはどうでしょうか。判断した瞬間に最も濃く、時間とともに揮発するこの情報を、後から書かせるのではなく、コミット履歴やPRの議論といった開発の痕跡から拾い上げて束ねられないか——という方向には、確かに可能性があります。散らばった情報の収集と整理は、AIが得意とするところだからです。ただ、ここは正直に言えば、越えるべき壁のほうがまだ多い未開拓地です。痕跡から復元できる「why」には限界があり、判断したその場で人間が一言残すことの、完全な代わりにはなりません。だからこの方向を「勝機」と言い切るには、私はまだ慎重でいたいのです。
AIがドキュメント問題を解けるかという問いへの、現時点での私の答えはこうです。「全部は解けない。けれど、人間が一番消耗していた層は、確実に手から外せる」。完全な自動化という意味での「解決」は来ません。それでも、現場が破綻しない運用は射程に入りつつあります。そして、外しきれずに残る「why」を、どこで、どう捕まえるのか——特効薬ではなく、解決が満たすべき条件という形で、ここまでの議論を一枚の地図に束ね直す次回に、その方向を差し出すつもりです。

　

まとめ

AIは技術ドキュメント問題を魔法のようには解決しません。コードに書かれていない「why」は原理的に復元できず、しかもドキュメントは生成物の正しさをその場で検証できない——この二つの壁は、AIが進化しても残ります。一方で、事実情報の生成、鮮度の維持、散らばった文脈の収集は、AIが人間を大きく上回れる領域です。だとすれば現実解は、層を分けて分担すること。書ける領域はAIに、書くべき「なぜ」は人間に。万能の夢でも諦めでもない、その境界線の上に、確かな勝機があると私は考えています。

あなたのチームでは今、ドキュメントの「どの領域」を人間が手で書いているでしょうか。そのうち、コードから機械的に再生成できるものと、本当に人間が判断の文脈として残すべきものを、はっきり分けられているでしょうか。その線引きをしておくことが、AIと一緒に働く最初の一歩になるはずです。

• « コードが自分を説明できる世界——「セルフドキュメンティングコード」の限界と未来
• 技術ドキュメント問題の全体地図——AIコーディング時代に何が起きているか【まとめ】 »