なぜ1つの大きな CLAUDE.md ではなく、複数の小さな CLAUDE.md ファイルを使うのか
最初の CLAUDE.md は800行だった。すべてを網羅していた：コードスタイル、コミット形式、テスト要件、エラーハンドリングの慣例、APIレート制限、デプロイの制約、命名規則。エージェントに知ってほしいと思うすべてのこと。
うまく機能しなかった。
1つの大きなファイルの問題点
それは毎回のターンで読み込まれます。800行のコンテキストが、テストカバレッジだけを行っているセッションがデプロイ手順を知る必要があるという稀なケースで消費されてしまう。
さらに重要なのは：長いファイルは優先度の曖昧さを生む。どのルールが最も重要か？2つの規約が衝突した場合、どれが勝つのか？エージェントはこれを合理的に扱うが、完全ではない。より範囲が明確な短いファイルは、階層を見えるようにする。
代わりに私が行うこと
Core CLAUDE.md（100行未満）：すべてのセッションに適用されるルール。コミット形式、スコープ外のファイルには触れない、先にテストを書く、停止条件プロトコル。決して変わらないもの。
ドメイン固有ファイル（各50〜100行）：関連性がある場合に包含されるよう、サブディレクトリに作成するか、個別ファイルとして作成します。
-
CLAUDE-api.md: レート制限ルール、認証パターン、外部呼び出しのエラーハンドリング -
CLAUDE-testing.md: テストファイル規約、何をテストするか、カバレッジの期待値 -
CLAUDE-deploy.md: ビルドプロセス、環境変数、デプロイ前に触ってはいけないこと
タスク固有のコンテキスト: そのタスクのプロンプトに含まれます。「認証モジュールはJWTを15分の有効期限で使用し、リフレッシュトークンのローテーションを行います。リフレッシュのロジックは lib/auth/refresh.js にあります。」このコンテキストはそのタスクに特有で、CLAUDE.md に保存しておく必要はありません。
実践での動作
私はコア CLAUDE.md でセッションを開始し、タスクのプロンプトに関連するドメインファイルを含めます:
一般的なルールはCLAUDE.mdを、API規約はCLAUDE-api.mdを参照してください。
タスク: [特定のタスク]エージェントは必要なものだけを読み込みます。APIに触れないセッションは API ルールの文脈コストを支払いません。触れるセッションには、必要な正確なルールが適用されます。
コアに残る唯一のルール
「If a file you need information from isn't in context, ask before assuming.」
これは、エージェントが規約をでっちあげるのを防ぐルールです。APIのエラーハンドリングのパターンを知る必要があり、CLAUDE-api.md が文脈にない場合は推測せず尋ねます。その1つのルールが、私が含め忘れたあらゆることを補います。
builtbyzac.comで Claude Code を実行した結果です。
