執筆者：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」は人間が残す。これまでのドキュメント運用が苦しかったのは、人間がこの両方を背負わされていたからではないでしょうか。AIが網羅と鮮度を引き受ければ、人間に残る宿題は「why」だけになります。全部を書く義務から解放されて、本当に人間にしか書けない一行に集中できる。書く総量が減るからこそ、続けられる。文化や気合に頼って失敗してきた運用が、初めて構造として回り始める可能性が、ここにあります。
もう一つの道は、「書かなくても残す」ことです。「why」は、判断した瞬間に最も濃く、時間とともに揮発します。だとすれば後から書かせるのではなく、コミット履歴やPRの議論といった、開発の過程で自然に発生する痕跡から「なぜ」を拾い上げて束ねる。散らばった情報の収集と整理は、まさにAIが得意とするところです。人間に「書け」と命じるのではなく、人間が普段の仕事で残した足跡を、AIが意味のある形に編み直す——ここにこそ、AIならではの勝機があると私は見ています。
AIがドキュメント問題を解けるかという問いへの答えは、「全部は解けないが、人間が一番苦しんでいた部分は解ける」です。完全な自動化という意味での「解決」は来ません。けれど、現場が破綻しない運用に到達するという意味でなら、それはもう射程に入りつつあります。Phase 1で重ねてきた議論の全体像も、近いうちに一枚の地図として束ね直すつもりです。

　

まとめ

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

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

• « 技術ドキュメント問題の全体地図——AIコーディング時代に何が起きているか【まとめ】
• AIが書く時代に、人間が手放してはいけないもの »