AIコーディングツールにREADMEやAPIドキュメントの下書きを任せているチームに向けて、見落とされがちな落とし穴を整理します。Claude CodeやGitHub Copilotなどにドキュメント生成を任せる運用は珍しくありませんが、レビューをすり抜ける種類の誤りがあることは意外と知られていません。
何が起きるか
AIが生成したドキュメントの誤りには、実は性質の異なる2種類があります。
1つ目は「事実の捏造」です。存在しないパラメータ名や、間違ったデフォルト値を書いてしまうケースで、ソースコードと突き合わせればすぐに見つかります。
問題は2つ目です。「静かな約束の誇張」と呼べる現象で、たとえば「このAPIのレート制限は今後も変わりません」のような、チームが守れるかどうか分からない約束を、もっともらしい文体でさらっと書いてしまいます。
この手の文章は、優秀なテクニカルライターが書く文章と文体がそっくりです。レビュワーが違和感を持たず、そのままマージされて何か月も残り続けるリスクがあります。
影響範囲は意外と広く、セキュリティ方針の説明、非推奨化（deprecation）のスケジュール、料金や利用上限の記載、バージョン間の互換性保証など、「誰かがそれを信じて計画を立てる」種類のセクションほど危険です。
なぜ起きるか
原因を段階的に分解すると、構造的な問題が見えてきます。
まず、AIモデルは与えられたコンテキスト（周辺情報）から「自然に続きそうな文章」を生成する仕組みです。事実かどうかより、文として滑らかかどうかが優先されやすい性質があります。
次に、ドキュメントの種類ごとに「どこまで言い切ってよいか」という線引きが、人間のライターの頭の中にしかないケースが多いです。この暗黙知がプロンプトやツール設定に反映されていなければ、モデルは変更履歴の1行も互換性保証の1文も同じトーンで書いてしまいます。
さらに、レビューの仕組み自体が「文章として自然かどうか」を見る設計になっていることが多く、「この主張の裏付けはどのファイルか」という出典チェックが入っていない場合、誇張に気づく仕組みがそもそも存在しません。
つまり根本原因は、モデルの性能不足ではなく、ドキュメントのセクションごとに「AIが書いてよい範囲」を事前に定義していないプロセス側の欠落です。
自分のプロジェクトが該当するか確認する
以下の観点で、自分のリポジトリが該当するかをチェックできます。
- READMEやdocsディレクトリの変更が、AIツール（Claude Code、Cursor、Copilot Workspaceなど）によるコミットかどうかをコミットログで区別できるか
git log --authorや commit message に「生成AIによる下書き」を示すトレーラー（コミットメッセージ末尾のDraft-Mode: modelのような付加情報）が付いているか- プルリクエストのレビュー時に、セキュリティ方針・料金・互換性保証などの記述に対して「出典ファイルはどれか」を問うレビュー観点が存在するか
確認コマンドの例として、直近のドキュメント変更がAI由来かを粗く洗い出すなら次のように調べられます。
git log --oneline -- docs/ README.md | head -n 30
git log --grep="Draft-Mode" --onelineもしトレーラーの仕組み自体が存在しないなら、それは「AIが書いた範囲」と「人間が書いた範囲」が記録上区別できていない状態を意味します。まずはここが出発点です。
対策の手順
対策の骨格はシンプルで、ドキュメントのセクションを3段階の「所有権」に分けて、それをファイル内のマーカーとCIチェックで強制する方法です。
1. セクションを3段階に分類する
影響範囲（ブラスト半径）を基準に分類します。プローズ（文章）としての難易度ではなく、間違っていたときの被害の大きさで判断します。
| 区分 | 該当する内容 | AIに許可すること |
|---|---|---|
| Draftable | 変更履歴、CLIフラグ一覧、スキーマ由来の設定表 | 文脈から自由に下書きしてよい |
| Draftable with evidence | トラブルシューティング手順、エラーメッセージの説明 | 指定したソースファイルに根拠がある主張のみ記述可 |
| Human-owned | セキュリティ方針、非推奨化の約束、料金・上限、互換性保証 | コメントで提案のみ、コミットは不可 |
多くのドキュメントが実際に住んでいるのは2段目です。ここでAIに「出典のファイルパスを示させる」ようにするだけで、根拠のない主張が可視化されます。
3段目は意図的に狭く設定します。担当者の名前を言えないHuman-ownedセクションは、実質的に誰にも所有されていないのと同じです。
2. マーカーをファイル本体に埋め込む
所有権の情報を別のスプレッドシートやWikiで管理すると、2スプリントもすれば本文とずれていきます。HTMLコメントとしてMarkdownファイル内に直接書き込み、レンダリングはされないが差分には残る形にします。
<!-- section: rl-current owner=model evidence=src/limiter/limits.ts -->
## Current limits
The default is 60 requests per minute per API key.
<!-- section: rl-guarantees owner=human -->
## What we guarantee across versions
We do not raise the documented default within a major version.マーカーが開いたセクションは次のマーカーまで、または末尾まで続くという単純な規則にしておくと、パーサーの実装も軽量に保てます。セクションをまたいで段落を移動させた場合も、1行の差分として普通にレビューできます。
3. CIでチェックを自動化する
マーカーとコミットのトレーラーを突き合わせ、矛盾があればプルリクエストを失敗させるチェッカーを用意します。確認すべき最低限の規則は次の3つです。
- AIモード（
Draft-Mode: modelトレーラー付き）のコミットが、Human-ownedセクション内に行を追加していないか - 同じコミットがHuman-ownedのマーカー自体を削除していないか
- 変更後もMarkdownとして正しくパースできるか
実装はおよそ80行程度のPythonスクリプトと、1つのCIジョブで構成できる規模感です。まずは自分たちのリポジトリのサンプルファイルに対して試し、誤検知がないか確認してから必須チェックに昇格させるのが安全です。
まとめ
AIにドキュメント生成を任せる運用では、事実誤認より「もっともらしい誇張」の方が見つけにくい問題です。
対策の軸は次の3点に整理できます。
- セクションを影響範囲で3段階（Draftable / Draftable with evidence / Human-owned）に分ける
- 所有権の情報はWikiではなくファイル内のマーカーとして埋め込み、差分で追跡できるようにする
- AIモードのコミットがHuman-ownedセクションを侵していないかをCIで機械的にチェックする
まずは自分のリポジトリで git log --grep によるトレーラー確認から始めて、該当があればマーカー方式の導入を検討してみてください。