AIエージェント向けドキュメントは「コードから推論できない情報」だけに絞る

モノレポのサブパッケージにCLAUDE.md / AGENTS.mdを追加したとき、最初はディレクトリ構成、開発フロー、実装パターン、コンテキスト型の説明まで盛り込んだ。レビューしたら大半が「コードを読めばわかる」内容だった。

削ぎ落として残したのは3カテゴリだけ:

1. 開発コマンド一覧 — パッケージ固有のスクリプト名とその用途
2. AIエージェント向けのコマンド使い分け — ワンショット版（CI/AI向け）とwatch版（人間の開発時向け）の違い
3. 注意事項 — 生成物の依存関係や実行順序の制約など、コードからは読み取りにくいルール

削った項目:

• ディレクトリ構成 → ls で見える
• 開発フロー（スキーマ定義 → 実装の流れ） → コード読めばわかる
• 主要パターン（実装パターン、ヘルパー、データローダー） → コード読めばわかる
• 型定義の説明 → 型定義ファイルを読めばわかる

判断基準: 「AIがファイルを数個読めば自力で把握できるか？」。Yesなら書かない。ドキュメントに書くべきは、コードに現れない暗黙知（コマンドの使い分けルール、実行順序の制約、生成物の依存関係）だけ。

サブディレクトリのCLAUDE.mdはそのディレクトリ内のファイルに触れたときにオンデマンドで読み込まれるので、コンテキスト圧迫の心配は少ない。ただし冗長なドキュメントはノイズになるので、短い方がよい。