#documentation | dev-memo

長大レポートより「依頼書項目に1対1対応+参照元明記」が強い 2026/4/13

分析レポートで「課題発見→施策提案」を網羅的に書くと情報過多で読まれない。ビジネスサイドから来た依頼書の項目①〜⑦に1対1対応させ、各回答に**参照元（どの資料のどの部分を見たか）**を添える構造が最も読みやすい。

構造

## 参照データ一覧
| 略称 | 実体 | 粒度 |
|---|---|---|
| 資料A | 検索語句レポート | ... |
| 資料B | LPレポート | ... |
| 資料C | ヒートマップCSV | ... |

## ① 対象を決める
### 回答
...
### 参照元
- 資料B → L4粒度で集計 → 費用1位のスライスを選定

## ② カテゴライズ
### 回答
...
### 参照元
- 資料A → ①で絞込 → XXX語句 → カテゴリ辞書で分類

効果

Before（網羅型）	After（1対1対応）
課題1〜6が並列で優先度不明	①〜⑦順に読めば結論が導ける
数値の出典が追えない	資料A〜Eで追跡可能
レビュワーが「この数値の根拠は？」と往復	各主張の横に参照元がある
代理店がサボれる	事業主が「資料Xの何ページ」で検証できる

重要ポイント

依頼書の文言に忠実に答える（「対象の広告グループを決める」と書いてあるなら広告グループ粒度で答える。LP粒度に勝手に格上げしない）
分析の限界を正直に開示する（粒度ズレ・セグメント切れない問題など）
参考PDFなど既存アウトプット形式があれば踏襲する（2列「現状vs改善案」レイアウト等）

「AI出力の品質をビジネス側が評価できる状態」を設計することで、標準化プロセスの再現性が上がる。

ドキュメントの4層構造と"骨子×世界観"モデル — AI自動生成の構造的限界 2026/4/11

documentation tacit-knowledge claude-code ai-agents

コードベース自動ドキュメント生成ツール（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行で答えてくれる。アウトラインを埋める形式にすることで書き出しの心理障壁を下げるのが肝。

ツール評価基準の転換

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

wikigen検証メモ — Claude Codeでコード仕様wiki自動生成 2026/4/11

claude-code documentation headless-mode cli

wikigenはGo製CLIで、Claude Codeを呼び出してコードベースから仕様wikiを自動生成する。embeddings/Docker/Ollama不要。Astro+Svelte+Firebaseの中規模プロダクトで検証した結果、想像を超えるクオリティだった。

本質は「Claude Codeをワーカーとして外部から叩くパターン」

これが一番の学び。wikigenはClaude Codeスキルのようなものではなく、外部プログラムがclaude CLIを子プロセスとして並列に起動する設計。スキルとは別物。

観点	スキル	wikigen方式
実行場所	現在の会話内（同一context）	外部プロセスが独立context起動
並列	不可	`-pp N`で並列worker
Context消費	現在のcontextを食う	各subprocess独立
運用	人が対話	GH Actionsで無人実行可能

いわゆる Claude Code headless mode / Claude Code as SDK のパターン。claude -p <prompt> で対話UIを起動せずプロンプト投入だけできるので、それを外部オーケストレーターから叩くと「バッチ処理」「CI統合」「Slack Bot裏側」等に応用できる。会話UIとしてのClaude Codeと、プログラムから叩くワーカーとしてのClaude Codeは別の顔、という発想転換が大事。

実行のコツ

-localフラグは不要: 位置引数に直接ローカルパスを渡せばclone不要 → ./wikigen /path/to/repo
privateリポでもローカルクローンさえあれば動く
認証はclaude CLIの対話ログイン状態を子プロセス継承で引き継ぐ。CLAUDE_CODE_OAUTH_TOKENを明示設定しなくても動作した（READMEに記載なし）
単一ページだけ生成したい場合は-retryを悪用: 1ページだけ空ファイル（<200B）を置いてretry実行 → そのページだけ生成される

クオリティ検証結果

24ページ構成のwikiを2分24秒で設計。1ページ本生成は約3分で16,301文字。スポットチェックで確認した範囲では:

ソース引用が行番号まで全て正確（ハルシネーションなし）
sequenceDiagramとflowchartのmermaid図を自動生成
コメントと実装の乖離のような人間のレビュアーでも見落としがちな細部まで指摘
「設計上の特徴」セクションを自力で作成する抽象化力

記事が触れていない注意点

「追加課金なし」はClaude Pro/Max契約者のOAuthトークン方式のみ。ANTHROPIC_API_KEY利用時は従量課金
--bareモードではOAuthトークン無効
OAuthトークンは1年有効
便利な未記載フラグ: -dry-run, -model(haiku/sonnet/opus), -json

向き/不向き

向き: コード主体のリポの叩き台仕様wiki、新人オンボーディング初稿、設計ドキュメントの老朽化対策（GH Actionsで定期再生成）

不向き: Markdownコンテンツ主体のドキュメントリポ、ビジネス要件・設計意図の「Why」の記述（wikigenはコード根拠に限定される）

READMEと社内ドキュメントサイトの責務分離パターン 2026/3/21

documentation readme architecture

#documentation (4)

構造

効果