Agentic Coding時代のドキュメント配置: /docs ディレクトリはもう限界？
Agentic Coding（AIエージェントによるコーディング）が普及する中、AIに渡すドキュメントをどこに配置すべきかという問題が注目されています。古川陽介氏（@yosuke_furukawa）のポストで紹介されていた記事「Your Docs Directory Is Doomed」（Yagmin）の内容をもとに、この問題を考えます。 /docs ディレクトリの進化と限界 Agentic Coding を始めると、多くのプロジェクトで以下のようなドキュメントが増えていきます: まず CLAUDE.md や AGENTS.md のような設定ファイルを作成 ARCHITECTURE.md でシステム全体の構造を記述 機能仕様やデザインドキュメントを /docs フォルダにまとめ始める この流れ自体は自然ですが、記事では /docs ディレクトリへの集約には根本的な問題があると指摘しています。 /docs ディレクトリの問題点 1. 発見可能性（Discoverability） LLM はどのドキュメントをいつ読むべきかを自律的に判断する必要があります。/docs に大量のファイルがある場合、LLM が適切なドキュメントを見つけられる保証はありません。計画フェーズで必要なドキュメントと、コード生成フェーズで必要なドキュメントは異なりますが、それを正しく参照できるでしょうか。 2. ドキュメントの腐敗（Documentation Rot） コードは頻繁に変更されますが、対応するドキュメントの更新は忘れがちです。小さな不整合が積み重なり、LLM が参照するコンテキストの品質が徐々に劣化していきます。さらに厄介なのは、ドキュメントが間違っていることに気づくための仕組み（observability）がないことです。 3. 構造の欠如 ドキュメント間の階層関係や依存関係が明示されていないため、LLM がドキュメント群をナビゲートする明確な方法がありません。各自が自分のスタイルで書くため、LLM にとって情報の探索がしにくい構造になります。 4. 変更速度の不一致（Velocity Mismatch） ドキュメントの種類によって変更頻度が異なります。アーキテクチャの概要はめったに変わりませんが、API仕様やコンポーネントの詳細は頻繁に更新されます。一つのディレクトリにすべてをまとめると、この違いが管理を困難にします。 コロケーション（Colocation）というアプローチ 古川氏がツイートで触れているように、一つの解決策はコロケーション — ドキュメントをコードの近くに直接配置する方法です。 src/ auth/ README.md # 認証モジュールの説明 auth.ts auth.test.ts api/ README.md # APIモジュールの説明 routes.ts middleware.ts このアプローチの利点: 発見可能性の向上: 関連コードと同じディレクトリにあるため、LLM が自然に参照できる 更新の同期: コードを変更する際にドキュメントも目に入るため、更新忘れが減る スコープの明確化: 各ドキュメントが担当する範囲が明確 Agentic Coding でのドキュメント管理の方向性 「Your Docs Directory Is Doomed」の記事は、従来のドキュメント管理は「1985年からの解決策」に過ぎないと指摘しています。Agentic Coding 時代には、以下の要素が重要になります: ...