■ 1. ドキュメントの基本的役割
- ソフトウェア開発においてドキュメントは関係者全員が同じ方向を向くためのSingle Source of Truthとして機能する
- 具体的な役割は関係者間のイメージ共有・実装との乖離検出の基準線・正しい挙動の拠り所の3点に集約される
- これらはある時点での正しさを自然言語で記述して共有することに帰結する
■ 2. ドキュメント腐敗の根本原因
- コードには型システムや依存関係グラフといった構造があり変更の影響範囲を機械的に特定できるが自然言語ドキュメントはそれが困難
- 自然言語ドキュメントには機械的なフィードバックループが存在しないことが根本的な問題
- Coding Agent時代では腐敗したドキュメントがAgentの行動を静かに悪化させる危険がある
■ 3. Agentが必要とするドキュメントの分類
- 導出可能なもの（コードやテストから再構成可能なAPI仕様・型定義一覧など）: 書かない
- 検証可能なもの（「レスポンス200ms以内」のように機械的にtrue/false判定可能なもの）: テスト・Linterに移す
- 不変の記録（ADR・ポストモーテムなどある時点の決定と理由）: Append-onlyで保持
- 還元不能な知識（外部制約・Why・組織判断などコードに落とせない知識）: 自然言語ドキュメントとして管理
- ETH ZurichとLogicStar.aiの研究ではディレクトリ構造の概要をCLAUDE.mdに書いてもAgentのファイル発見速度は向上しなかったという結果が出ている
■ 4. 二層構造による提供方式
- Layer 1（CLAUDE.md / AGENTS.md）:
- セッション開始時に自動的にContextに注入される作業記憶として機能する
- 禁止事項・ガードレール・アクティブなアーキテクチャ判断の要約・ビルド/テスト/Lintコマンドを置く
- 約60行を上限としContext効率のためシンプルさを重視する
- Layer 2（docs / docs/adr/）:
- ADRやドキュメント群はAgentが必要に応じて参照する長期記憶として機能する
- Context効率の観点からすべてをCLAUDE.mdに詰め込む必要はない
■ 5. ドキュメント管理・運用の実装
- check-doc-freshness.shスクリプト:
- CLAUDE.md/AGENTS.mdの行数制限（60行以上でエラー）を検査する
- 壊れたパス参照の検出・last-validated日付チェック・古いADRへの参照確認を実施する
- phase: currentのドキュメントは3日でWARNING・5日でERROR
- phase: target（将来目標）は10日でWARNING・15日でERROR
- PreToolUse Hook統合:
- Claude CodeのHook機能を利用しgit commit前にドキュメント検査を自動実行する
- exit 2とstderrを使用してブロック時のフィードバックを実装する
- docs-auditorツール:
- 各ドキュメントが読まれたタイミングを検出する
- Agentの行動変化（beneficial/neutral/harmful/unnecessary）を分類する
- ドキュメントごとのROI（impact_score / (content_tokens / 1000)）を計算する
- 一度も参照されないドキュメントを検出する
- 二段構えの運用:
- check-doc-freshness.sh（軽量・高頻度）: 毎コミット時の時間ベースチェック
- docs-auditor（重量・低頻度）: 定期的な実行と実際の行動改善度評価
■ 6. 人間向けドキュメントの扱い
- 人間向けドキュメント（オンボーディング・運用手順・ユーザーマニュアル）はリポジトリの外に出す選択肢を検討する
- Agent向けドキュメントとの混在を回避し各最適化に専念可能にすることが目的
- コード変更に連動した自動更新の仕組みがないことが課題であり現状では試行錯誤中
■ 7. まとめ
- Coding Agent時代でも基本的なドキュメントの役割は変わらないがフィードバックループの構築が必須
- 検証可能性か不変性のいずれかを持つドキュメントを優先する
- 導出可能なものは書かず検証可能なものはテスト化する方針を採る
- 二層構造と二段構えの運用で腐敗対策を実装する
- コード規模やチーム規模によって正解は異なり試行錯誤の余地がある