AIでコードドキュメントを作成するときは、先に必要な文書を棚卸しし、コード上の根拠（ファイルパス・安全に確認した実行結果）を集めてから生成させ、公開前に固有名と手順を実物へ突き合わせます。「リポジトリを読んでREADMEを書いて」と一度に頼む方法が失敗しやすいのは、AIが根拠を示さないまま書いた行と、実際に確認できる行が混ざってしまい、読む側が区別できなくなるためです。
ドキュメントの価値は、量よりも、内容が実装と一致し、読者が根拠を確認できることにあります。一致しない文書は、読んだ人を誤った方向へ進ませます。この記事では、文書の種類と読者と更新責任を対応させる棚卸しマトリクス、根拠の番号を付けて書かせる生成指示テンプレート、そして公開前の不一致検証チェックリストを示します。あわせて、更新日だけに頼らず、根拠差分を再確認の合図にする運用まで扱います。
情報確認日：2026年7月28日（日本時間）
結論：根拠を番号で紐付け、検証できない行は本文に書かせない
この記事の結論
- 文書の読者と答える問いを決め、複数の目的を扱う場合も節と導線を分ける
- 生成の前に、根拠になるファイル・履歴・安全に確認した実行結果を集める
- AIには根拠の番号を行末に付けさせ、確認できない内容は本文の外へ出させる
- 手順の文書は「前提・入力・期待結果」の3点を必ず揃える
- 関数説明は要約ではなく、契約（引数・戻り値・例外）と副作用を書く
- 公開前に、安全な環境でコマンドを検証し、固有名を検索して確認する
- 根拠にしたcommitからの差分を、陳腐化を再確認する合図にする
先に必要なドキュメントを棚卸しする
文書不足を感じたら、書き始める前に何が足りないのかを分けます。「ドキュメントがない」という言葉には、セットアップ手順がない、設定の意味が分からない、復旧手順が特定の人の知識にしかない、といった別々の不足が含まれます。1つのファイルに複数の目的を置く場合も、読者が目的の情報へ移動できるよう、節や別文書へのリンクを明確にします。
README・セットアップ・運用・関数説明を分ける
文書の分類には、Diátaxisという枠組みが参考になります。この枠組みは「4つの異なるニーズと、それに対応する4つの文書の形式 — チュートリアル、ハウツーガイド、技術リファレンス、説明 — を特定する」もので、文書はそのニーズの構造に沿って組み立てるべきだとしています。実務では、これをもう少し具体的な単位に落として管理します。
次の棚卸しマトリクスは、その具体化です。自分のリポジトリの状況を、この6行に当てはめてみてください。
| 文書の種類 | 主な読者 | 答える問い | 根拠になるコード | 更新の引き金 | 更新責任 |
|---|---|---|---|---|---|
| README | 初見の人・導入を検討する人 | 何をするものか／なぜ役に立つのか／どう始めるか | 依存定義、entry point（実行の入口）、公開API | 対外的な機能追加、対応環境の変更 | リポジトリ管理者 |
| セットアップ手順 | 新しく参加する開発者 | 手元で動かすまでに何をするか | 依存定義、環境変数の読み込み箇所、初期化script | 依存・必須環境変数・起動方法の変更 | 直近に環境を触った人 |
| 運用手順 | 当番・保守担当 | デプロイ・復旧・定期作業をどうやるか | CI設定、デプロイscript、定期実行の定義、監視設定 | デプロイ経路・手順・閾値の変更 | 運用担当 |
| 関数・モジュール説明 | その関数を呼び出す開発者 | 何を渡すと何が返るか／副作用は何か | 対象の関数本体、型定義、そのテスト | シグネチャ・例外・副作用の変更 | 変更したPR（pull request、変更提案）の作成者 |
| 設定リファレンス | 導入者・運用担当 | どの設定が何に効くか／既定値は何か | 設定の読み込み箇所、既定値の定義 | 設定の追加・改名・既定値の変更 | 変更したPRの作成者 |
| 変更履歴 | 利用者・連携する他チーム | このversionで何が変わったか | タグ、マージされた変更 | リリース | リリース担当 |
READMEに何を書くかは、GitHubのドキュメントが具体的です。READMEには「プロジェクトが何をするか」「なぜそのプロジェクトが有用か」「利用者がどうやって使い始めるか」「どこで助けを得られるか」「誰が保守し貢献しているか」といった情報を含めるのが一般的だとされています。置き場所にも規則があり、「リポジトリに複数のREADMEファイルが含まれる場合、表示されるファイルは .github ディレクトリ、リポジトリのルートディレクトリ、docs ディレクトリの順で選ばれる」と説明されています。複数置いてあるのに片方が表示されない、という混乱はここが原因です。
変更履歴については、Keep a Changelogが「変更履歴とは、プロジェクトの各バージョンについて、注目すべき変更を厳選し、時系列に並べたファイルである」と定義し、変更の種類を Added（追加）・Changed（変更）・Deprecated（非推奨化）・Removed（削除）・Fixed（修正）・Security（脆弱性対応）の6つに分けています。この分類をそのまま使うと、AIに書かせるときの出力形式が固定でき、粒度がぶれません。
読者と更新責任者を決める
マトリクスで重要なのが、右2列の「更新の引き金」と「更新責任」です。この2列が空欄だと、変更時に見直されない可能性が高まります。誰が、どの変更をきっかけに確認するかを決めます。
更新責任は、変更の行動とレビュー工程に紐付けると運用しやすくなります。「設定を変更するPRの作成者が文書差分を確認し、CODEOWNERSの担当者がレビューする」のように、実行者と確認者を決めます。「開発チーム」のような集合名だけでは、実際の担当が曖昧になりがちです。
読者を決めると、本文に含める情報と、別文書へ送る情報を判断できます。セットアップ手順では起動までに必要な情報を中心にし、設計思想はアーキテクチャ文書へリンクする。運用手順では実行コマンド・前提・確認方法を中心にし、内部実装の詳細は必要な箇所だけ参照する、といった分け方です。
コードから根拠を集める
棚卸しで「何を書くか」が決まったら、次は「何を根拠に書くか」を集めます。根拠が不足した状態では、生成された文章が整っていても、実装との一致を検証できません。
entry point・設定・script・型を確認する
集める対象は、文書の種類によって変わります。棚卸しマトリクスの「根拠になるコード」列が、そのまま収集リストです。実際に開くファイルは次のようなものになります。
- 依存定義：パッケージ定義ファイル（
package.json、pyproject.toml、composer.jsonなど）。言語のversion指定、依存、定義済みのコマンドが分かります - entry point：実行が始まるファイル。CLIならコマンド定義、Webアプリならルーティングの起点
- 設定の読み込み箇所：環境変数を読んでいる場所、スキーマ、検証処理、既定値。設定リファレンスの主要な根拠です
- script・タスク定義：ビルド・テスト・デプロイのコマンド。CIの設定ファイルには、実際に動いている手順が書かれています
- 型定義・シグネチャ：引数と戻り値の型を確認する根拠。例外と副作用は実装・テスト・呼び出し先も確認します
- テスト：その関数の想定される使い方と境界条件が、実行可能な形で書かれています
加えて、安全に実行して確認した結果を根拠にします。セットアップ手順なら、使い捨て可能な環境やコンテナでコマンドを順に実行した出力です。デプロイ、削除、マイグレーション、復元など状態を変えるコマンドは、本番で試さず、dry-runや検証環境、レビュー済みの記録で確認します。出力例を載せる場合は、資格情報や個人情報を除去してください。
なお、リポジトリ全体を読ませられる範囲や、差分の扱い方はツールごとに違います。手元のツールでどこまで根拠を渡せるかは「AIコーディングツール比較」を確認してください。仕様が失われた既存コードを、まず読み解くところから始める場合の手順は「AIでレガシーコードを解析する方法」で扱っています。この記事は、コードの意味が分かっている状態から文書を起こす作業を対象にしています。
根拠の確認方法を分ける
集めた内容は、確認方法によって分けておくと、生成後の検証がしやすくなります。
- コードや実行で確認する内容：ファイルの存在、関数のシグネチャ、設定の既定値、安全な環境でのコマンド結果
- 履歴や人に確認する内容：設計の意図、その方式を選んだ理由、過去の経緯、今後の方針。ADR、Issue、PR、議事録、担当者の確認などを根拠にします
コードだけを渡して設計理由を書かせると、もっともらしい理由が生成されることがあります。「パフォーマンスのためにキャッシュを導入しています」という一文も、ADRや当時の議論を確認しなければ根拠がありません。誤った理由が文書に残ると、後の人がその前提で判断します。
根拠資料から確認できない内容は、いったん本文の外にある「確認が必要な項目」へ回します。ADRやIssueを探す、当時を知る人に確認するなどして根拠が得られたら、出典を紐付けて本文へ移します。確認できない場合は、事実として断定せず「理由は記録されていない」と明記するか、省略します。
文書の種類ごとにAIへ生成させる
根拠が揃ったら生成に進みます。まずは1回の生成につき1つの文書へ絞ると、読者と答える問いを固定できます。複数文書をまとめて扱う場合も、文書ごとに入力・出力・根拠を分離してください。
あなたは技術ドキュメントの作成担当です。以下の資料だけを根拠に、
指定した文書を作成してください。
【作る文書】README / セットアップ手順 / 運用手順 / 関数説明 / 設定リファレンス
（1つだけ選ぶ）
【読者】（誰が読むか・どこまで知っている前提か）
【この文書が答える問い】
【根拠資料】各ブロックの先頭にファイルパスを付けて貼る
- [1] path/to/package.json
- [2] path/to/src/index.ts（entry point）
- [3] path/to/src/config/env.ts（設定の読み込みと既定値）
- [4] path/to/.github/workflows/ci.yml
- [5] 安全な環境で実行して得た出力
（実行したコマンドと、秘密情報・個人情報を除去した結果）
【出力ルール】
- 事実を書いた行には、根拠の番号を [1] のように行末へ付ける
- 根拠資料から確認できない内容は本文に書かない。
末尾の「確認が必要な項目」に、何を誰に確認すべきかを書く
- コマンド・ファイルパス・環境変数名・設定キー・既定値は、
根拠資料の表記をそのまま使う（大文字小文字・区切り文字を変えない）
- 手順は「前提 → 入力（コマンド） → 期待結果」の3点を必ず揃える
- 存在しないオプションやサブコマンドを補完しない
- 出力例は [5] にあるものだけを使う。作文しない
- 宣伝的な表現（高速・簡単・強力・最先端）は書かない行末の根拠番号は検証用です。公開版で残すか外すかは文書の方針に合わせますが、外す場合も、文書メタデータやレビュー記録には根拠対応を残してください。番号がない事実記述は、根拠漏れの候補として確認します。
手順は前提・入力・期待結果を揃える
手順の文書で最も多い欠落は「期待結果」です。コマンドだけが並んでいる手順書は、うまくいかなかったときに、どこで止まったのかを判断できません。各手順に、次の3点を揃えます。
- 前提：その手順を始められる状態。「Node.js 22以上が入っている」「
.envの作成が済んでいる」 - 入力：実行するコマンド、または操作。コピーできる形で1行ずつ
- 期待結果：成功したときに何が起きるか。出力の特徴的な行、作られるファイル、アクセスできるURL
期待結果があると、読者は自分で失敗を検知できます。「http://localhost:3000 を開くとログイン画面が表示される」と書いてあれば、真っ白な画面が出た時点で、次に進まずに立ち止まれます。書いていなければ、3手順先まで進んでから戻ることになります。
もう1つ、手順の順序には「前提の依存」を反映させます。環境変数の設定より先にビルドコマンドを書くと、そのとおりに実行した人は失敗します。生成された手順は、コマンドの危険度を確認したうえで、安全な検証環境で上から順に確かめてください。
関数説明は契約と副作用を中心にする
関数説明でありがちな失敗は、コードを読めば分かることを日本語に直しただけの文章です。getUserById に「IDからユーザーを取得します」と書いても、情報は増えていません。書くべきなのは、シグネチャ（引数と戻り値の型の並び）からは読み取れない契約と副作用です。
この点は、Pythonのdocstring（関数やクラスの定義の先頭に置く説明文字列）の規約を定めたPEP 257が明確にしています。「関数やメソッドのdocstringは、その振る舞いを要約し、引数、戻り値、副作用、送出される例外、呼び出せる条件の制約を（該当するものすべて）文書化すべきである」とされています。JavaScriptのJSDocでも、@param（引数）、@returns（戻り値）、@throws（送出される例外）、@example（使用例）、@deprecated（非推奨）といったブロックタグが同じ役割を担います。言語は違っても、記述すべき項目は共通しています。
実務では、次の観点をAIに書かせると差が出ます。
- 引数の制約：型だけでなく、許容される範囲、空文字やNULLを渡したときの扱い、単位（秒かミリ秒か）
- 戻り値の意味：見つからなかったときにNULLを返すのか例外を投げるのか、空配列と未取得を区別するのか
- 送出される例外：どの条件でどの例外が出るか。呼び出し側が捕捉すべきものか
- 副作用：データベースへの書き込み、ファイル出力、外部API呼び出し、キャッシュの更新、ログ出力
- 呼び出せる条件：初期化が済んでいる必要があるか、トランザクションの中で呼ぶ前提か、並行して呼んで安全か
副作用は、AIが最も見落としやすい項目です。関数本体だけを渡すと、その中で呼んでいる別の関数の副作用が見えません。呼び出している関数の定義も根拠資料に含めるか、生成後に自分で確認してください。
実装との不一致を検証する
AIで文書を作る場合、実装との照合は省けない工程です。文章が読みやすくても、正確であることは保証されません。
コマンドと例を実際に実行する
文書に書いたコマンドは、危険度を分類して検証します。セットアップやビルドは使い捨て可能な環境で上から順に実行します。デプロイ、削除、データ更新、復元などは本番で試さず、dry-run、テスト用データ、ステージング、承認済みの実行記録で確認してください。普段の開発環境には、文書に書き忘れた設定がすでに入っていることがあるため、クリーンな環境での確認が役立ちます。
実行しながら確認する点は次のとおりです。
- コマンドがそのままコピーして動くか（改行位置、引用符、パスの区切り）
- 各手順の期待結果が、実際の出力と一致するか
- 手順の順序が、前提の依存関係と矛盾していないか
- 書かれていない前提操作を、自分が無意識に行っていないか
- 出力例が、実行して得た本物の出力か（AIが作文した例ではないか）
ファイル・関数・設定名を検索して確認する
実行だけでは、すべての名前の誤りを見つけられません。文書に登場するファイルパス、関数名、環境変数名、設定キーなどをリポジトリ内で検索し、実在と綴りを確認します。AIは似た名前を自然に生成するため、API_BASE_URL が実際は API_BASE_ENDPOINT だった、といった食い違いが起きます。
公開前のチェックリストとして、次を使ってください。
## 実行して確かめる
- [ ] コマンドを読み取り・可逆・破壊的に分類した
- [ ] 安全に実行できるコマンドを、使い捨て可能な環境で上から順に実行した
- [ ] デプロイ・削除・データ更新・復元は、本番で試さず別の検証方法を記録した
- [ ] 各手順の期待結果が、実際の出力と一致した
- [ ] 出力例は実行して得た本物の出力である（作文された例ではない）
- [ ] 手順の順序が前提の依存関係と矛盾していない
## 検索して確かめる
- [ ] ファイルパスをすべてリポジトリ内で検索し、実在を確認した
- [ ] 関数名・クラス名を検索し、シグネチャが本文と一致する
- [ ] 環境変数名・設定キーを検索し、読み込み箇所と綴りが一致する
- [ ] 既定値が、コード上の既定値と一致する
- [ ] version（言語・依存・ツール）が、依存定義と一致する
- [ ] 外部リンクが実在し、意図した先へ向かう
## 残りを片付ける
- [ ] 「確認が必要な項目」を解消したか、未確認事項として明示した
- [ ] 根拠番号の公開方針を決め、外す場合も対応記録を残した
- [ ] 秘密情報（token・接続文字列・実在の個人情報）が例に混ざっていない
- [ ] 根拠にした commit（または tag）を文書に記録した最後の項目が、次の節につながります。
文書を古くしない運用を作る
公開時に正確だった文書も、コードや運用が変われば古くなります。更新漏れは、コードを変えた人が「この変更でどの文書が影響を受けるか」を判断できないときにも起こります。
コード変更時の確認項目へ追加する
更新の引き金は、棚卸しマトリクスの「更新の引き金」列にすでに書いてあります。これをレビューの確認項目へ移します。
- 公開APIのシグネチャを変えた → 関数説明を更新する
- 環境変数を追加・改名した、既定値を変えた → 設定リファレンスとセットアップ手順を更新する
- 起動方法・ビルド手順を変えた → セットアップ手順を更新する
- デプロイ経路・監視の閾値を変えた → 運用手順を更新する
- 対応環境（言語version・OS）を変えた → READMEを更新する
差分レビューの観点そのものを整理する方法は「AIコードレビューの差分チェックリスト」で扱っています。文書の更新確認は、その観点の1つとして組み込むのが現実的です。独立した作業にすると、忙しい週から抜け落ちます。
更新日ではなく根拠差分を記録する
「最終更新日」だけでは、内容が現在の実装と一致しているか判定できません。日付が示すのはファイルを触った時点であり、根拠となる実装がその後変わっていないことまでは示さないためです。確認日を残しつつ、根拠ファイルとcommitも記録します。
代わりに記録するのは、その文書が何を根拠に書かれたかです。根拠にしたcommitと、根拠ファイルの一覧を残します。
<!-- doc-sources
base: 9f3c1ab
files:
- package.json
- src/index.ts
- src/config/env.ts
- .github/workflows/deploy.yml
-->この情報があると、陳腐化の判定をコマンド1つで行えます。
# 文書が根拠にしたcommitから現在までに、根拠ファイルが変わったかを見る
git diff --name-only 9f3c1ab..HEAD -- \
package.json src/index.ts src/config/env.ts .github/workflows/deploy.yml出力が空なら、列挙した根拠ファイルにはそのcommit以降の差分がありません。1行でも出れば、文書を再確認する合図です。ただし、一覧に含め忘れた依存ファイル、外部サービス、生成物の変化は検出できません。また、差分がないことは、基準commit時点の文書が正しかったことまで保証しません。
この仕組みには副次的な効果もあります。根拠ファイルを書き出す作業を通じて、文書と実装の対応関係が明示されるため、次に更新するときに何を読み直せばよいかが分かります。AIに更新を手伝わせる場合も、この一覧をそのまま根拠資料として渡せます。再確認が必要になった文書については、変更されたファイルの差分と現在の文書を渡し、「この差分によって文書のどの行が事実と合わなくなったか」を指摘させる使い方が有効です。全文を書き直させるより、変わった箇所だけを直すほうが、既存の正確な記述を壊しません。
よくある失敗
リポジトリを渡して一度に全部書かせる
「このリポジトリを読んでドキュメントを整備して」だけでは、READMEとセットアップと設計説明が混ざった出力になりがちです。文書の種類、読者、答える問い、根拠を指定し、文書ごとに検証してください。
出力例を作文させたまま公開する
コマンドの実行結果やログの例は、AIが自然に作文します。実物と少し違う出力例は、読者に「自分の環境がおかしいのでは」と疑わせ、調査の時間を奪います。出力例は、実行して得たものだけを貼ってください。
設計の意図をAIに推測させる
「なぜこの構成なのか」はコードに書かれていないため、AIは一般的にありそうな理由を生成します。誤った理由が文書に残ると、後の人がその前提で判断します。確認できない内容は本文に書かず、確認が必要な項目として残すか、書かないという判断をしてください。
よくある質問
コードコメントとドキュメントは、どちらをAIに書かせるべきですか？
目的が違うので、両方に役割があります。関数のdocstringは呼び出す人向けの契約（引数・戻り値・例外・副作用）を書く場所で、READMEや手順書は、コードを読む前の人が判断するための場所です。ただし、処理をそのまま言い換えただけの行内コメントを大量生成すると、実装変更時に古い説明が残りやすくなります。
根拠番号を付けさせると読みにくくなりませんか？
番号は検証用です。公開版で残すか外すかは文書の方針で決めます。外す場合も、レビュー記録や文書メタデータに対応を残せば、次回更新時に根拠へ戻れます。
ドキュメントを日本語と英語の両方で保守すべきですか？
読者が誰かで決まります。複数言語を別々に保守すると更新負担が増え、片方だけ古くなる可能性があります。両方が必要なら正本と翻訳の更新フローを決め、自動チェックや同一PRでの更新を組み込みます。片方だけで足りるなら、正本を明示します。
古い文書が大量にある場合、どこから手を付けますか？
棚卸しマトリクスで種類を分け、「間違っていると実害が出るもの」から着手します。多くの場合、セットアップ手順と運用手順です。この2つは、間違っていると人の作業が止まるか、復旧が遅れます。設計の説明などは、実害が出るまでの距離が遠いので後回しで構いません。
まとめ
AIでコードドキュメントを作成する作業の中心は、文章を生成することではなく、根拠を集めて突き合わせることです。まず棚卸しマトリクスで文書の種類・読者・答える問い・根拠になるコード・更新の引き金・更新責任を対応させ、書くべきものと書かなくてよいものを分けます。
生成では、根拠資料に番号を付けて渡し、事実を書いた行の行末に番号を付けさせます。確認できない内容は本文へ入れさせず、「確認が必要な項目」へ回します。手順は前提・入力・期待結果の3点を揃え、関数説明は要約ではなく契約と副作用を書かせます。
公開前にはコマンドの危険度を分類し、安全なものは使い捨て可能な環境で実行します。ファイルパス・関数名・環境変数名・既定値・versionも検索して突き合わせます。確認日だけでなく、根拠にしたcommitと根拠ファイルの一覧を残しておけば、git diff --name-only で再確認が必要になった候補を検出できます。差分がない場合も、根拠一覧の漏れや外部仕様の変化は別に確認してください。