READMEや仕様書をAIに書かせるときのコツ — 「書かせる」より「抽出させる」

READMEや仕様書をAIに書かせるときのコツ — 「書かせる」より「抽出させる」

AIに「このリポジトリのドキュメント書いといて」って丸投げすると、だいたいそれっぽいけど半分ウソの長文が返ってきます。存在しない関数、実態と違うフロー、3ヶ月前に消したはずのモジュール。これ、AIが悪いというより、こっちの頼み方の問題なんですよね。

僕は普段、Firebase Cloud Functions の上で動く米国の消費者向け fintech バックエンドを触っています。決済・カード・不正検知・台帳まわりで、コードは数百ファイル、外部プロセッサも複数。新しく入った人が全体像を掴むのはなかなか大変で、ドキュメントの出来が立ち上がりの速さに直撃します。そんな環境で「AIにドキュメントを書かせる」を何回も試した結果、効くやり方とダメなやり方がかなりハッキリしてきました。結論は1つだけ。「書かせる」んじゃなくて「抽出させる」。これに尽きます。

1. 読者と目的を先に決めちゃう

まずこれが一番効きます。生成する前に、**「誰が・何のために読むのか」**を1文で決めてからAIに渡します。

• ✗「このコードベースのドキュメント書いて」
• ✓「Webhookを初めて追う新人が、署名検証から台帳更新までの流れを15分で辿れる地図を書いて」

読者が変われば、出てくるドキュメントは全くの別物になります。監査の人向け、オンコール対応の人向け、機能追加する開発者向け――同じシステムでも書くべきことは全然ちがう。ここをボヤッとさせたまま投げると、誰の役にも立たない「総花的な何か」が出てくるだけなんです。

2. 粒度 — 百科事典じゃなくて「地図」を書かせる

AIって、放っておくと全部を網羅した超大作を書きたがります。これが罠。長ければ長いほどウソが混ざるし、長ければ長いほど一瞬で腐ります。

うちで一番役に立ってるドキュメント、実は散文じゃなくてただのナビ地図なんですよね。だいたいこんな感じです:

functions/src/
├── index.ts         # まずここ — 全エンドポイント一覧
├── coreTransaction/ # トランザクション処理
├── fraud/           # 不正検知
└── ...
追い方: index.ts で関数を見つける → import を辿って各ディレクトリへ

「index.ts から始めて import を辿れ」――この一文があるだけで、新人が自力でコードを読めるようになります。だからAIには**「全部を説明させる」んじゃなくて「どこを読めばいいか指させる」**。詳しい説明は各モジュールの近くに短く置いて、地図からリンクすればいい。地図は腐りにくいし、詳細はコードのそばに置いておけば同期もラクです。

3. 既存コードから「事実」を抜かせる

ハルシネーション対策って、結局これに尽きます。AIに**「あるべき姿」を想像させない**。「今あるもの」を読ませて要約させる。 それだけです。

• まず index.ts とかディレクトリ構成みたいな、事実が書いてあるファイルを起点に渡す
• 「このファイル群を読んで、実際に存在するエクスポートだけ並べて」とお願いする
• 仕様を創作させない。コメントとコードが食い違ってたら「不明」と書かせる

うちのコードには「お金は整数(セント)で持つ」「Firestoreの既存ドキュメントは必ず {merge:true}」みたいなガチガチの規約があります。こういうの、AIに発明させると地味にズレるんですよね。実在する規約は人が一回ルールファイルに書いて、AIにはそれを参照させるだけ。生成と参照を分けるのがコツです。

4. コードの近くに置いて、腐らせない

ドキュメントがウソになる最大の原因って、「コードから遠い場所に、一回書いて放置」なんですよね。なので:

• ドキュメントはリポジトリの中に置く(別Wikiに逃がさない)
• 「変更したらこのドキュメントも更新」を定型作業に組み込む。差分が出たらAIに更新案を出させる
• 月1でもいいので「コードと突き合わせて、古くなってないかチェック」を回す

「書いて終わり」じゃなくて「ずっと更新し続けられる形」で書く。ここがAIドキュメントを実用にできるかの分かれ目です。

5. 検証 — file:line を引用させてスポットチェック

最後、これは絶対やります。AIってマジで自信満々でウソをつくので、出てきたものを鵜呑みにしちゃダメです。

• 主張には必ずファイル名と行番号をセットで書かせる(「この関数はここ: coreLedger.ts:142」みたいに)
• ランダムに3〜5箇所だけ、自分で実際にコードを開いて照合する
• 1個でもウソがあったら、その章はもう信用しないで作り直す

引用を強制するだけで、AIの「それっぽい捏造」はかなり減ります。検証も全部読まなくていい、サンプル照合で済むのがラクなところです。

まとめ

AIにいいドキュメントを書かせるコツって、結局「いい質問を投げる」に尽きるんですよね:

1. 読者と目的を1文で決めてから渡す
2. 百科事典じゃなくて地図を書かせる
3. 「あるべき」じゃなくて実在するコードを読ませて抜く
4. コードの近くに置いて更新し続ける
5. file:line 引用でスポット検証

「ドキュメント書いて」って丸投げした瞬間に、もう負け確定。AIは作家じゃなくて、爆速の抽出器として使うのが正解です。