AIにドキュメントを書かせたら読みやすさが変わった

ドキュメントを書くのが苦手だった。コードは書けるけど、それを説明する文章がうまく書けない。結果、READMEは最低限、設計書は箇条書きの羅列、手順書は自分しか読めないメモになっていた。

エンジニアのドキュメント問題

エンジニアは「コードを読めばわかる」と言いがち。でも実際には、コードだけでは背景や判断理由がわからない。半年後の自分すら理解できないことがある。

ドキュメントが必要なのはわかっている。でも書くのが面倒。コードを書く時間を削ってドキュメントを書くモチベーションが湧かない。この問題をAIが解決してくれた。

AIに下書きさせる運用

やり方はシンプル。Claude Codeにコードを読ませて「このモジュールのREADMEを書いて」と指示する。構成、説明文、使用例まで含めた下書きが数十秒で出てくる。

自分でゼロから書くと30分かかるREADMEが、AIの下書きを編集するだけなら10分で終わる。しかも構成が整っている。

ただし「READMEを書いて」だけだと、汎用的すぎる内容になることがある。プロジェクトの文脈を伝えるほど、出力の精度が上がる。自分が実際に使っているプロンプトの構成はこうだ。

プロンプトの基本構成：

1. 対象ファイルやディレクトリを指定する
2. 読者が誰かを伝える（チームメンバー、外部開発者、新メンバーなど）
3. ドキュメントの種類と目的を明示する
4. 既存のフォーマットがあればそれに従うよう指示する

たとえばREADMEなら「src/auth/配下を読んで、チームの新メンバー向けにREADMEを書いて。既存のREADME.mdのフォーマットに揃えて」と指示する。API仕様書なら「controllers/配下のエンドポイントを読んで、リクエスト・レスポンスの型定義を含めたAPI仕様をMarkdownで書いて」という形になる。

ポイントは「読者」と「フォーマット」を必ず伝えること。この2つがないと、AIは想定読者がわからないまま書くので、粒度がブレる。

ドキュメントの種類ごとの使い分け

AIにドキュメントを書かせるとき、種類によってアプローチを変えている。全部同じプロンプトで済むわけではない。

README は一番AIが得意な領域。コードの構成を読み取って、概要・セットアップ・使い方・設定項目を網羅的に書いてくれる。人間がやるのは、プロジェクト固有の注意事項や「なぜこのライブラリを選んだか」の補足くらいだ。

API仕様書 はコードから型情報を抽出できるので、AIとの相性がいい。エンドポイント一覧、パラメータ、レスポンス例を正確に書いてくれる。ただしビジネスロジックの説明（「なぜこのバリデーションがあるのか」など）は人間が追記する必要がある。

設計書（ADR・技術選定書） はAIが一番苦手な領域。技術選定の背景や比較検討の過程は、人間の頭の中にしかない。ただし、フォーマットの整形には使える。「背景」「課題」「検討した選択肢」「決定事項」「トレードオフ」といった項目の枠組みを作らせて、中身は自分で書く。空の項目があると「ここ書いてないけど大丈夫？」と気づける効果もある。

手順書（Runbook） はAIが真価を発揮する。コマンドの羅列だけでなく、各ステップの前提条件、期待する出力、失敗時の切り戻し手順まで含めて書いてくれる。自分で書くと「わかっている人が読む前提」で省略しがちだけど、AIはそれをやらない。

トラブルシューティングガイド は、過去の障害対応ログをAIに読ませて「よくあるトラブルと対処法」にまとめさせると有効。Slackの障害対応チャンネルのログを食わせて、パターンを抽出させるといった使い方もできる。

読みやすくなった理由

AIが書いたドキュメントが読みやすい理由は3つ。

構成が一貫している。概要→使い方→設定→トラブルシューティングという流れが毎回同じ。人間が書くと、人によって構成がバラバラになる。

説明の粒度が揃っている。自分が書くと、詳しく書く部分と雑に書く部分の差が激しい。AIは全体を均一な粒度で書いてくれる。

読者視点で書ける。自分はコードの作者だから、前提知識を省略しがち。AIは「このモジュールを初めて見る人」の視点で書くから、省略が少ない。

人間の編集は必須

AIの下書きをそのまま使うことはない。必ず人間が編集する。

理由は、AIが書くドキュメントには「なぜこの設計にしたか」が含まれないから。コードから読み取れる「何をしているか」は書けるけど、「なぜそうしたか」は人間しか知らない。

あと、AIは丁寧すぎることがある。社内ドキュメントなら省略していい前提知識まで書いてくるから、不要な部分を削る作業が必要。

もう1つ注意しているのが、AIが自信ありげに不正確なことを書くケース。特にライブラリのバージョン固有の仕様や、社内独自のルールに関する記述は、必ず裏を取る。コードと突き合わせて事実確認するのは人間の仕事だ。

品質管理のチェックポイント

AIに書かせたドキュメントを公開する前に、毎回確認している項目がある。

事実の正確性。コマンド例は実際に動くか。バージョン番号は最新か。設定ファイルのパスは正しいか。AIはそれっぽいが微妙に違うパスやオプション名を書くことがある。ここは手抜きできない。

対象読者との一致。社内向けなのに外部向けのような丁寧な説明をしていないか。逆に、新メンバー向けなのに社内用語を説明なしで使っていないか。AIの出力は指示した読者レベルとズレることがあるので、通読して違和感がないか確認する。

情報の鮮度。半年前に書いたドキュメントは高確率で古くなっている。AIに既存ドキュメントとコードの差分を検出させる使い方も有効だ。「このREADMEの内容と実際のコードで食い違っている箇所を指摘して」と指示すると、メンテナンスが格段に楽になる。

冗長な表現の除去。AIは同じことを言い換えて繰り返す傾向がある。「つまり」「すなわち」で始まる段落が連続していたら、片方を削る。読者は要点だけ知りたい。

設計書のテンプレート化

設計書でも同じ運用をしている。新しい機能の設計を考えたら、箇条書きでポイントだけ書いて、AIに設計書のフォーマットに整形させる。

背景、目的、技術選定、代替案、リスク。全部の項目を自分で埋めるのは大変だけど、AIに叩き台を作らせれば、追記と修正だけで済む。

具体的には、自分の箇条書きメモとコードの差分（PRのdiff）をAIに渡して「ADRフォーマットで設計書を書いて」と指示している。差分から変更の意図を読み取って、背景や影響範囲まで含めた文書を作ってくれる。自分のメモだけだと書き漏らす「影響を受ける他のコンポーネント」のような項目も、コードを読んでいるAIが拾ってくれることがある。

手順書が一番効果が大きい

一番効果を感じたのは手順書。デプロイ手順、障害対応手順、環境構築手順。

以前の手順書は「自分がわかればいい」レベルだった。新メンバーが読んでも手順通りにできない。AIに書かせたら、前提条件、各ステップの確認方法、ロールバック手順まで含めてくれる。

手順書の品質が上がると、属人化が減る。自分が休んでもチームが困らない。これが一番の効果。

特に障害対応手順書では、「このコマンドを実行したら何が表示されるはずか」を各ステップに書かせるようにしている。深夜の障害対応で焦っているとき、期待する出力が書いてあると「手順通りに進んでいるか」を判断できる。これはAIに指示しないと書いてくれないので、プロンプトに「各ステップに期待する出力例を含めて」と明記している。

ドキュメント更新の自動化

ドキュメントは書いた瞬間から古くなる。この問題に対しては、CIにドキュメントのチェックを組み込んでいる。

PRでコードを変更したとき、関連するドキュメントが更新されていなければ警告を出す仕組みだ。たとえばAPIのエンドポイントを追加したのにAPI仕様書が更新されていなければ、CIが「docs/api.mdの更新が必要かもしれません」と通知する。

完璧な自動化ではないが、「ドキュメントの更新を忘れる」という一番多い失敗を防げる。更新が必要だとわかれば、AIに差分を読ませて「この変更に合わせてドキュメントを更新して」と指示するだけだ。

ドキュメントは「書く」から「編集する」へ

AIのおかげで、ドキュメント作成のハードルが下がった。ゼロから書くのは辛いけど、80点の下書きを100点に仕上げるのは楽しい。

「コードを書いたらAIにドキュメントを書かせる」を習慣にしたら、リポジトリのドキュメント充実度が目に見えて上がった。書かない言い訳がなくなった。

半年この運用を続けて実感しているのは、ドキュメントの量が増えただけでなく、チーム内の質問が減ったこと。「これどうやるの？」の質問に「ドキュメント見て」と返せるようになった。以前は「ドキュメントないから口頭で説明するね」だった。この差は大きい。

関連記事

• AIにコードレビューさせたら精度がすごかった
• AIにテストコードを書かせたら品質が上がった話
• AIに指示を出すのが上手い人の共通点