#ai-agents (1)

コードベース自動ドキュメント生成ツール（wikigen等）を試して辿り着いた気づき。AIはコードの”構造”は完璧に読めるが、“意味”は読めない。そしてその限界は本質的であって、モデルの賢さで埋まらない。

ドキュメントの4層構造

層	内容	生成元	機械で可能か
Layer 1: 構文	コード自身	コード	—
Layer 2: 構造	ファイル関係・関数呼出・API定義	コード	✅ 完璧
Layer 3: 機能	ユーザーから見てこの機能が何をするか	人間の頭	❌
Layer 4: 意図	なぜこう実装されているか、ビジネス要件	人間の頭 + 過去の会話ログ	❌

なぜLayer 3がコードから出ないか

ファイル名が PublicTaskList.svelte でも、それが「顧客向け実績ページ」なのか「社内タスク管理」なのかは読めない。コレクション名 divisions が「業界別」か「社内部門」かも曖昧。多段ワークフローは複数リポをまたぐので、順に読んでもユーザー体験として再構築できない。「なぜこのif文があるか」はコミットメッセージにすら無く、Slack過去ログや誰かの記憶にしか残っていないことも多い。

つまり暗黙知（tacit knowledge）がコードの外にあり、存在しない情報はAIも生成できない。

重要な誤解の訂正

「AI向けドキュメント」は”理解済みの知識の圧縮”であって”理解の代替”ではない。llms.txt や AGENTS.md の議論はほぼ前者で、「すでに誰かが理解しているものを機械可読形式で固定化する」話。理解そのものを生み出す話ではない。

“骨子×世界観”モデル

この限界を逆手に取った役割分担:

役割	担当	作業量
構造（Layer 2）	機械（wikigen等）	秒〜分
機能要約（Layer 3）	人間 + AI対話	各ページ数分
意図（Layer 4）	人間 + 関係者インタビュー	プロジェクト単位
AI向け圧縮	機械（AGENTS.md変換）	秒

機械が骨子を作り、人間が”自分が見ている世界”を書き込む。その合作こそが真のドキュメント。

心理的にも理にかなっている

ゼロから書けと言うと永遠に書かないドキュメントも、骨子を渡されると埋まる。「このページ名、これ何する機能?」と聞けば人間は1行で答えてくれる。アウトラインを埋める形式にすることで書き出しの心理障壁を下げるのが肝。

ツール評価基準の転換

ドキュメント自動生成ツールの真価は「どこまで自動で書けるか」ではなく「人間の暗黙知を引き出しやすい下書きをどこまで作れるか」にある。完璧な自動化を目指すより、人間の追記を誘発する良質な下書きを作る方が、最終的なドキュメントの質は高くなる。