tomevault-io エージェント向けコンテキストドキュメントの作成ガイド
原則1: 書くべきものと書くべきでないものを区別する
ドキュメントの目的は「コードを読まなくても全体像と探索の起点を把握できる」こと。
書くべき内容
- アーキテクチャの全体像（レイヤー構成、責務、依存方向）
- 処理フロー（リクエストライフサイクル、主要な非同期境界）
- アーキテクチャレベルの構成要素と各要素の役割（1行説明）
- 設計判断の意図（Why、トレードオフ）
書くべきでない内容
- 型シグネチャ、フィールド一覧、定数値の列挙
- コードレベルの構成要素の網羅的列挙（エラー型・DTO一覧等）
- 関数の振る舞いや引数の説明（→ コードコメント / テストへ）
判断基準
「コードを変更したとき、このドキュメントも更新しなければ嘘になるか？」
- Yes → コードコメント・テストに書く
- No / 嘘になっても探索に有用な"上位の真実" → ドキュメントに書く
例外: 探索の起点になる最小の具体値
以下は最小限に限り記載してよい（目安: 各カテゴリ3個以内）。
- 最初に実行すべき開発・検証コマンド
- エントリーポイントとなるファイル
- ログやトレースを確認する最短経路
原則2: 常時ロードされるコンテキストを最小に保つ
CLAUDE.md は会話の度に常時ロードされる。トークンコストに直結するため、本当に毎回必要な情報のみを記載する。
- 上位階層に詳細を書かない — 下位ドキュメントまたはコード自体に委譲する
- 情報は一箇所に記述し、重複させない
原則3: 配置先を内容の性質とロードタイミングで決める
コンテキストの配置先は3層に分けて管理する。
CLAUDE.md — 常時ロード
性質: オリエンテーション（概要・探索の起点）
例: プロジェクト概要、技術スタック、開発コマンド、ディレクトリ構成、下位ドキュメントへのリンク
.claude/rules/<topic>.md — 条件付き自動ロード or 常時ロード
性質: 規範（「〜せよ / 〜するな」）
例: テスト規約 (paths: *.test.ts)、命名規約 (paths: *.ts)、コミットメッセージ規約 (paths なし = 常時)
docs/<topic>.md — オンデマンド参照
性質: 知識（「〜はこうなっている」）
例: アーキテクチャ詳細、処理フロー、設計判断の背景、環境変数一覧
配置の判断基準
- 毎回必要か？ → Yes:
CLAUDE.md/ No: 下位へ - 「〜せよ」か「〜である」か？ → 規範:
.claude/rules// 知識:docs/ - 特定のファイルパターンにスコープできるか？ → Yes:
paths:付き rules / No:paths:なし rules またはCLAUDE.md
注意: アーキテクチャ情報は src/ 全体に適用されるためパスベースの絞り込みの利点が薄い。概要は CLAUDE.md に、詳細は docs/ に置く。
原則4: rules の粒度をロードコストで使い分ける
paths:付き → 必要な分量を書いてよい。命令と理由を明確にpaths: なし（常時ロード）→ 命令 + Why を1行で書く。詳細はdocs/に委譲するpaths: なしの rules を増やすのは最後の手段
原則5: 参照構造を明確にする
CLAUDE.mdは下位ドキュメントへのリンクを持つdocs/は 1ドキュメント = 1テーマ- docs 間の相互参照は可、循環・重複は避ける
Converted and distributed by TomeVault — claim your Tome and manage your conversions.