設計書・ドキュメントはAIに書かせる（前編）──コードから「たたき台」を逆生成する

ドキュメントが更新されない原因は「書く気がない」ことではなく、白紙から書き始めるコストが高すぎることにあります。この前編では、既存のコードやリポジトリの構造をAIに読ませて README・構成説明・API仕様のたたき台を逆生成する具体的な手順と、そのまま使えるプロンプトを示します。

同時に、実務でやってみて分かった限界も扱います。結論を先に言うと、コードから生成できるのは「What」と「How」だけで、「Why」は生成できません。設計意図・業務ルール・非機能要件はコードのどこにも書かれていないため、AIはそこを「もっともらしく捏造」します。この境界線を運用ルールに落とし込めるかどうかが、AIドキュメント生成が定着するかどうかの分かれ目です。

ドキュメントは「書くコスト」と「読まれる回数」が釣り合いません。3時間かけて書いた設計書が3回しか読まれないことは普通にあります。一方で、書かなかったことによるコスト（同じ質問への回答、調査のやり直し、誤った前提での実装）は分散して発生するため、誰の工数としても計上されません。この非対称性が「後で書く」を永遠に続けさせます。

コードはPRという明確な変更単位を持ちます。一方でドキュメントには「変更されるべきタイミング」を機械的に検出する仕組みがありません。結果として、ドキュメントは書かれた瞬間から古くなり始めます。

設計を理解している人が書くドキュメントは、当人にとって自明な前提が省略されます。ドキュメントの価値は「知らない人に伝わること」なのに、書き手は最もそれを判定できない立場にいます。

AIはこの3つ目に対して意外に強いです。AIは対象システムに関する前提知識をコンテキスト内の情報しか持たないため、「書かれていないこと」を質問として返してきます。この性質は後編で扱う「AIに設計意図をインタビューさせる」使い方につながります。

「AIに任せられる度」を実務感覚で整理します。◎に近いほど、コードという一次情報から機械的に導出できる範囲が広い(=AI適性が高い)という意味です。

この△と×で示したゾーンについて、理解せずに導入すると、「AIが書いた立派な文書の中に、誰も決めていない仕様が混ざる」という最悪の事故が起きるため、注意が必要です。こちらについては、後半で整理したいと思います。

ここからは、実際にコードからREADME・設計書を作成する方法を、プロンプトを示しながらご紹介していきます。

1. 対象範囲を決める（リポジトリ全体ではなく、1サービス/1モジュール単位）
2. AIに「事実の収集」だけをさせる（推測禁止を明示）
3. 収集結果を人が確認する（ここを飛ばすと後で全部やり直し）
4. 収集済みの事実をもとにドキュメントを生成させる
5. 「コードから判断できなかった項目」をAIに列挙させる ← 最重要
6. 5の項目を人が埋める / 意図的に「未定」と書く

多くの人が 2→4 を1回のプロンプトでやろうとして失敗します。事実収集と文章生成を分けるのがコツです。分けると、事実の誤りを文章のレビューと同時にやらずに済みます。

このリポジトリを読み、以下を「コードから確認できた事実」だけで列挙してください。

1. 言語・ランタイム・バージョン（根拠ファイル名を併記）
2. 依存パッケージのうち主要なもの（用途を1行で）
3. エントリポイント（ファイルパス:行番号）
4. 提供している外部インターフェース（HTTPルート / CLIコマンド / イベントハンドラ）
5. 設定項目（環境変数名・デフォルト値・参照箇所）
6. 外部依存（DB / キュー / 外部API / クラウドサービス）
7. テストの実行方法（設定ファイルの記述に基づいて）
8. ビルド・デプロイに関する記述（CI設定ファイルがあればその内容）

制約:
- 各項目に根拠となるファイルパスを必ず添えること
- 推測が混じる場合は行頭に [推測] を付けること
- コードから判断できない項目は「不明」と書き、埋めないこと
- それらしい一般論で埋めることは禁止

• なぜ根拠ファイルパスを要求するのか
  検証コストが劇的に下がります。パスがあれば「そのファイルを見る」だけで真偽が判定できます。パスがないと、記述の真偽を確かめるためにリポジトリ全体を探すことになり、結局自分で書くより遅くなります。
  　

• なぜ [推測] タグを要求するのか
  これがこの記事の中心的な主張です。AIの出力は「事実」と「推測」が同じ流暢さで混ざります。流暢さは正しさの指標にならないので、AI自身にラベルを付けさせて、レビュー時に推測部分だけを集中的に確認します。

先に収集した事実のみを使い、README.md を作成してください。

構成:
# <プロジェクト名>
## 概要（3行以内。何をするものかだけを書く）
## 動作環境（言語・ランタイム・バージョン）
## セットアップ
## 設定（環境変数の表: 変数名 / 必須 / デフォルト / 説明）
## 使い方（代表的な操作を2〜3個）
## ディレクトリ構成（主要ディレクトリのみ。1行説明付き）
## テスト
## 関連ドキュメントへのリンク（存在するものだけ）

制約:
- 収集済みの事実に無い内容は書かない
- 「高性能」「スケーラブル」などの評価表現を使わない
- コマンドは実際に定義されているものだけを書く（例示のための架空コマンドを書かない）
- 最後に「## このREADMEで埋められなかった項目」として、
  コードから判断できず人間の入力が必要な項目を箇条書きで列挙する

最後の1項目が生成物の価値を決めます。実際に出てくるのは例えばこういう項目です。

• このサービスの利用者は誰か（社内利用か外部提供か）
• 障害時の連絡先・エスカレーション先
• なぜこのライブラリを選んだのか（代替案があるのに）
• SLA・想定負荷・データ保持期間
• 本番環境のデプロイ承認者

いずれもコードには存在しない情報で、かつドキュメントとして最も価値がある情報です。AIは「書けないもののリスト」を作るのが得意で、その一覧は人間へのインタビュー項目としてそのまま使えます。

以下のソースからHTTP APIの仕様書を作成してください。
対象: src/routes/ 配下のすべてのファイル

各エンドポイントについて表形式で:
| メソッド | パス | 認証 | リクエスト | レスポンス | 実装箇所 |

さらに各エンドポイントごとに:
- 認証・認可の判定がどこで行われているか（ファイル:行）
- 入力バリデーションの有無と内容
- エラー時のステータスコードと条件
- 副作用（DB書き込み / 外部API呼び出し / メール送信など）

制約:
- ミドルウェアで共通適用されている処理は、それを明示すること
- コードから読み取れない業務ルールは「要確認」と書くこと
- 「副作用」は必ず列挙すること。見落とした場合の影響が大きいため

「副作用を列挙させる」のは実務的に効きます。読む側が一番知りたいのは「このAPIを叩くと何が起きるのか」であって、リクエストの型ではありません。

生成前（実際によくあるREADME）

# notification-service

## セットアップ
npm install
npm start

生成後（事実収集を経て生成したもの） ※以下は説明用に簡略化した架空の例です。

# notification-service

## 概要
カタログに登録されたグループのメンバーへ、イベント種別に応じた
通知メールを送信するバックエンドサービス。

## 動作環境
- Node.js 24 系（`package.json` engines: `>=24.0.0`）
- PostgreSQL 15 以上（`src/db/migrate.ts` のマイグレーション前提）

## 設定
| 変数名 | 必須 | デフォルト | 説明 |
|---|---|---|---|
| `DATABASE_URL` | ✓ | - | 接続先。`src/db/client.ts:12` で参照 |
| `MAIL_SENDER` | ✓ | - | 送信元アドレス。`src/mail/send.ts:8` |
| `RETRY_MAX` | | `3` | 送信リトライ回数。`src/mail/send.ts:41` |
| `DRY_RUN` | | `false` | true で送信せずログ出力のみ |

## 副作用のあるエンドポイント
| メソッド | パス | 副作用 |
|---|---|---|
| POST | `/notify` | メール送信・`notification_log` へINSERT |
| DELETE | `/subscription/:id` | 論理削除（`deleted_at` 更新） |

## このREADMEで埋められなかった項目
- 通知先グループの定義主体（コード上は外部カタログAPIから取得しており、
  誰がその登録を管理しているかは判断不可）
- `RETRY_MAX` を超えて失敗した通知の扱い（DLQ設定はコード上に無い。要確認）
- 送信失敗時のエスカレーション先

差はプロンプトの精度ではなく、「事実収集 → 生成 → 不足項目の明示」という工程を踏んだかどうかです。

以前、大規模なリポジトリ群のランタイム移行対応を扱いました。ここで学んだのは、AIに「文章を書かせる」前に「機械的なスキャンで台帳を作る」という順序です。

1. gh CLIとスクリプトで全リポジトリの該当箇所を機械スキャンし、「影響あり/なし」の台帳をCSVで作る
2. 台帳をAIに渡して、影響パターンごとの分類と対応手順の文書を生成させる
3. 生成された手順書を、実環境で1件試して検証する
4. 検証で判明した差異を手順書に反映する

この順序が重要でした。先に文書を書かせると、AIは「一般的な移行手順」を書きます。それは正しいけれど自分たちのリポジトリには当てはまりません。台帳という一次データを先に作ると、AIは「自分たちの現実」に基づいた手順を書きます。

スキャンの検出ロジック（正規表現）に不備があり、同じ箇所を二重にカウントしていました。

教訓は2つあります。

• AIが生成した集計結果は、必ず別の方法で検算する。件数の突き合わせ、サンプルの目視、境界値の実機確認。AIは集計の間違いを流暢に報告してきます
• レビュアーの指摘も一次資料で確認する。指摘が来たら反射的に直すのではなく、公式ドキュメントや実挙動で裏を取る。

ここからは、AIドキュメント作成でうまくいかなかった例をご紹介します。

アーキテクチャ決定記録の草案をAIに書かせたとき、一般的な数値が、あたかも決定事項のように書かれていました。実際の要件は別の要件定義書に定義されていて、コードにもインフラ定義にも存在しない数値でした。

これは「AIが嘘をついた」のではなく、存在しない情報を要求した側の設計ミスです。非機能要件はコードから導出不可能なので、要件書という一次資料をコンテキストに入れない限り、出力は必ず推測になります。

対策として運用に入れたルール:

• 非機能要件（保持期間、SLA、監査要件、法規制対応）は、出典となる文書名とセクション番号を併記できない限り書かない
• 出典が見つからない場合は「要確認」と明記して残す。空欄を埋めない

AIは要求した項目をすべて埋めてくれます。結果として、情報は揃っているのに読み手が判断できない文書ができました。これではレビューで「情報が断片的で、結論がどこにあるか分からない」という状態になってしまいます。

これに対しては、以下のように対策をすることで防ぐことができます。

• 判断の理由を1か所に集約するブロックを追加する

• 文書全体に散っている根拠を、本文の早い位置にまとめて置く

• 網羅性はAIに任せ、構成（どこに何を置くか）は人が決めるという分担をする

また、セキュリティについての考慮も重要です。これに関しては、AIにすべて入力しないということが大切です。

「ソースコードを入れてよいか」は組織の判断事項です。判断するために確認すべき点は、以下の通りです。

①入力データが学習に使われるか
②保持期間
③保存先リージョン
④管理者が利用ログを確認できるか
⑤契約上の責任範囲

ドキュメント生成の文脈で見落とされがちですが、AIが生成した設定例に実際の値が混入することがあります。コンテキストに実際の設定ファイルを渡していると、それが「例」として出力に現れます。

これに対しては、次のように対策します。

• 生成物をコミットする前に秘密情報スキャンを通す
• サンプル値は明示的にプレースホルダにする指示をプロンプトに入れる

• AIツールがリポジトリに書き込む場合、その権限を人間の権限と分離する（専用のアカウント/トークン、最小権限）
• 誰がいつどのドキュメントをAIで更新したかが追える状態にする。更新コミットに「AI生成のたたき台を人がレビュー済み」であることを残す運用が現実的です

以上を踏まえると、次のように整理できます。

AIに任せる作業、人間が確認すべき作業

原則として、「間違っていたときに誰かが困る記述」は人が確認する ということを怠らないようにすることが大切であるといえます。

ドキュメントが更新されないのは、書き手の意欲が足りないからではありません。白紙から書き始めるコストが高く、さらに、コードの変更に合わせてドキュメントを更新するきっかけが仕組みとして用意されていないことが、主な原因です。だからこそ、既存のコードやリポジトリの構造から、READMEや設計書のたたき台をAIに生成させる方法には大きな価値があります。

ただし、AIが得意なのは、コードにすでに存在する情報を整理し直すことです。コードから読み取れる「What」と「How」は比較的正確に再構成できますが、設計意図や業務ルール、非機能要件、採用しなかった案の理由といった「Why」までは導き出せません。そこをAIに埋めさせようとすると、もっともらしい推測が、あたかも決定事項であるかのように混ざってしまいます。

実務で安定して使うには、事実の収集と文章の生成を一度に行わないことが重要です。まずAIにコードから確認できる事実を根拠ファイルのパス付きで列挙させ、人が内容を検証したうえで、その事実だけを使って文書を生成させます。さらに、コードから判断できなかった項目を明示させれば、人間が確認すべき論点や、設計者へのインタビュー項目も整理することができます。推測が含まれる場合は [推測] と表示させるなど、事実と推測を区別する仕組みも欠かせません。AIの文章が流暢であることと、内容が正しいことは別だからです。

最終的に、AIに任せるべきなのは、構造の抽出や情報の列挙、文章の整形といった機械的な作業です。一方で、設計意図の確認、非機能要件や業務ルールの確定、公開範囲の判断、承認済み文書の変更といった、誤りがあったときに大きな影響が出る判断は人が担う必要があります。AIに白紙を埋めさせ、人が意味と責任を引き受ける。この役割分担を運用として定着させることが、AIによるドキュメント生成を実務で活用するための最も重要な条件です。