概要
語り尽くされてそうなAI用ドキュメント構成の話。
個人的には小規模向けの構成があっても良いのではと考えて書いてみました。
Github Copilot と Claude Code の環境で使っていて、色々と試して落ち着いたディレクトリ構成です。
構成
CLAUDE.md / AGENTS.md は最小になるよう、ほとんど索引のみ。
LLMの思考が発散しないようコンパクトな構成にしています。
CLAUDE.md/AGENTS.md # AI への指示書（エントリーポイント）
# ├─ スタック概要
# ├─ ディレクトリ構成
# ├─ コーディング規約
# ├─ 作業ルール
# └─ 各ドキュメントへのポインタ一覧
docs/
├── PROJECT.md # プロジェクト全体像・アーキテクチャ詳細
├── COMMAND.md # よく使うコマンド集（都度更新）
├── TESTING.md # テスト方針・構成
│
├── design/ # 機能設計ドキュメント（実装前に作成）
│ ├── README.md # ├─ 一覧表 & テンプレート
│ └── YYYYMMDD-<機能名>.md # └─ 個別 design doc
│
└── knowledges/ # 調査・トラブルシュートで得た知見
├── README.md # └─ 一覧表
└── <トピック>.md
COMMAND.md は Makefile にした方がいいかもと思っています。
コメントを充実させればAI用のドキュメントとしても機能すると思いますし、メンテ漏れも起きにくくなります。
ポイント
- 先に述べた通り、コンパクトにまとめるポリシーです
- 設計駆動でエージェントコーディングする際、人間がレビューすることを前提に成果物のドキュメントを作りすぎないための構成です
- design-docのテンプレートもなるべくコンパクトにして、計画を発散させないように気をつけます
- docs/ 直下はリポジトリ全体の方針で、基本方針を決める情報です
- design-docs/ はプランモードを併用して作成します
- requirements.md を細かく書いて design-docs を生成させるやり方もありますが面倒なので、プランモードで雑な要件から仕様を固めて、それをそのまま保存するイメージです
- 学習用のメモリは knowledges/ に集約します
- 個別のトピックを散発的に残していく想定なので、大規模になるともう一階層カテゴライズしてあげたほうがAIには優しくなるかも
まとめ
- あまりドキュメントの種類を増やさないで良い構成にしました
- これを原型にして、プロジェクトによって手順をスキル化したりしてカスタムしていきます
- ガードレールとしてのドキュメントは信頼性がまだ低いと思っているので、別途linterなどを整備してhooksで定性的なチェックをかける想定です