ドキュメント生成 ── コードから文書を作る限界── 自動生成の正確性と陳腐化、ADR という工夫

01そもそも「ドキュメント」とは、何種類あるのか

ドキュメント生成を語る前に、ひとくちに「文書」と言っても中身が違うことを押さえます。ソフトウェアの文書は、少なくとも次の三層に分かれます。読む人も、求められる正確さも、更新の頻度も、層ごとに違います。

• コードに密着した文書 ── 関数やクラスの説明、API の入出力仕様。コードのすぐ隣にあり、コードが変われば一緒に変わるべきもの。
• 使い方の文書 ── 導入手順、チュートリアル（＝手を動かして学ぶ入門）、よくある質問。読むのは、その道具を初めて使う人。
• 判断の文書 ── なぜこの設計にしたのか、どの選択肢を捨てたのか。数か月後の自分や、引き継いだ人が「なぜ？」と問うたときに答えるもの。

生成 AI が得意なのは、このうち上の二層です。コードを読めば、関数の説明も、手順の下書きも作れます。けれど三層目 ── 「なぜそうしたか」という判断の記録は、コードのなかに書かれていません。捨てた選択肢や、その場の制約は、コードには残らないからです。ここに、自動生成の最初の限界があります。

02AI による生成 ── 何がどこまでできるのか

実際に、生成 AI はコードからどんな文書を作れるのか。正確に見ます。過大にも過小にも評価しないことが、道具を使いこなす前提です。

四つを並べると、境界が見えてきます。コードに書かれている事実の転記や言い換えは得意、コードにない情報の復元は苦手。設計の理由を AI に書かせると、それらしい文章は出ますが、実際の判断とは無関係な「作話」になりがちです。ここを取り違えると、間違った理由が公式文書として残ってしまいます。

03正確性の検証 ── 「もっともらしい」を見抜く

自動生成の文書で最も怖いのは、間違いが自然な文章に紛れることです。AI は「正しさ」ではなく「もっともらしさ」を最適化します。だから誤りも、読みやすく、それらしく書かれる。人が書いた粗い文よりも、AI の滑らかな誤りのほうが見逃されやすい。この逆説を、まず知る必要があります。

検証の基本は、文書とコードを突き合わせることに尽きます。生成された説明が、実際のコードの挙動と合っているか。引数の型は正しいか、書かれた手順のとおりに動くか。理想は、この突き合わせを機械で自動化することです。たとえば、文書中のコード例を実際に実行し、書いたとおりの結果になるかを試す仕組み（＝ドキュメントテスト）を置けば、説明とコードのズレを機械的に見つけられます。

04陳腐化の問題 ── 文書は放っておくと嘘になる

正確に作れたとしても、次の壁が待っています。コードは変わり続けるのに、文書は自動では追いつかないという問題です。今日は正しい説明も、来月コードが変われば、古い説明が残ります。そして読む人は、その文書が古いことに気づけません。誤った文書は、文書がないことよりも危険です。「書いてあるから正しい」と信じてしまうからです。

陳腐化への一番の対処は、文書をコードと同じ場所に置き、コードが変わったら文書も作り直す仕組みにすることです。この考え方は docs-as-code（＝文書もコードと同じ道具・手順で管理する）と呼ばれます。生成 AI は、この「作り直し」を速める助けになります。人がすべてを書き直すのではなく、変わった部分の下書きを AI が作り、人が確かめる。ただし、どの文書を機械で作り直してよく、どの文書は人が管理すべきかは、次章からの型の話につながります。

05ADR ── 「なぜそうしたか」を残す工夫

01 章で見たとおり、生成 AI が最も苦手なのは「設計の理由」です。ではその判断を、どう残せばよいのか。ここで役立つのが ADR（＝Architecture Decision Record、設計判断記録）です。Michael Nygard が 2011 年に提唱した、ごく軽い形式の記録です。一つの設計判断を、一枚の短い文書にまとめます。

ADR の中身は、驚くほど簡素です。おおむね次の四つだけを書きます。

• 背景（Context） ── どんな状況で、何を決めなければならなかったか。
• 決定（Decision） ── 何を選んだか。
• 理由と捨てた選択肢 ── なぜそれを選び、他の案をなぜ捨てたか。
• 結果（Consequences） ── その決定が、後々どんな制約や利点を生むか。

ADR の肝は、コードに残らない情報を、判断した本人が、その場で残す点にあります。捨てた選択肢や、当時の制約は、後から復元できません。だからこそ AI に作文させるのではなく、人が書く。逆に言えば、ADR さえ残っていれば、生成 AI はそれを読んで、要約や関連文書の下書きを作れます。人が「事実としての判断」を残し、AI が「その周りの説明」を膨らませる ── 判断の文書では、この分担が効きます。番号を振って時系列に並べ、決定を変えたときは古い ADR を「置き換えられた」と印を付けて残す。消さずに履歴として積む点も、製薬の変更管理の記録と同じ発想です。

06Diátaxis ── 文書を四つの型に分ける

もう一つ、実務で効く工夫が Diátaxis（＝ディアタクシス、文書を四つの型に分ける枠組み）です。Daniele Procida が整理したもので、あらゆる技術文書を、読む人の目的で四象限に分けます。「学ぶため」か「作業のため」か、「手を動かす」か「理解する」かの二軸です。

Diátaxis が教えるのは、四つを混ぜてはいけないということです。チュートリアルに仕様の細部を詰め込むと初心者が迷い、リファレンスに解説を混ぜると引きにくくなる。そして自動生成の観点でも、この分類は道しるべになります。リファレンスは機械に任せてよい、解説は人が管理すべき。四つの型に分けておけば、どこを AI で作り直し、どこを人が守るかの線引きが、そのまま見えてきます。04 章で言う「機械で作り直してよい文書」とは、主にリファレンスとハウツーを指します。

07運用 ── 生成と検証を回し続ける

ここまでの工夫を、日々の開発にどう組み込むか。単発で文書を生成しても、コードが変われば陳腐化します。大事なのは、生成・検証・更新を回し続ける仕組みにすることです。次の四つが、実務で効く運用原則です。

四つに共通するのは、「機械に任せる部分」と「人が守る部分」を先に切り分けるという発想です。事実の転記と検証は機械へ、判断とつまずき所の補いは人へ。この分担ができていれば、生成 AI は文書づくりの重荷を大きく減らします。分担せずにすべてを AI に任せると、滑らかな誤りと作話が積もり、かえって文書への信頼が崩れます。

08本サイトの他の章との接続

本回は、次の章と読み合わせると理解が厚くなります。

• AI Programming 第 5 回 ── テストの自動化。文書のコード例を検証する仕組みは、テストの発想と地続きです。
• AI Programming 第 7 回 ── AI セキュリティと脆弱性 ── 生成物のリスクを扱う次回。文書の陳腐化も、放置すれば別種のリスクになります。
• 資材審査シリーズ ── 記録の正確性・変更履歴の残し方は、ADR や docs-as-code と同じ問いを共有します。

生成 AI は、コードから文書を作る作業を大きく軽くしました。API リファレンスの転記、手順の下書き、要約と翻訳 ── これらは任せてよい領域です。けれど二つの壁が残ります。一つは正確性 ── AI は「もっともらしい誤り」を自然な文章で書くため、コードと突き合わせる検証が要る。もう一つは、コードに書かれていない「なぜそうしたか」は AI には作れないということ。ここは人が ADR として残すしかありません。

限界を正しく引けば、道具は強く働きます。Diátaxis で文書を四つの型に分け、リファレンスは機械に、解説は人に。docs-as-code で文書をコードの隣に置き、生成と検証を回し続ける。判断だけは人が残す。この線引きが、陳腐化しない文書を、速く保つ土台になります。それは製薬の記録管理 ── 誰が・いつ・何を根拠に決めたかを正確に残す営み ── と、同じ規律の話でもあります。次回は、生成コードそのものが抱えるリスク、AI セキュリティと脆弱性に進みます。