CLAUDE.md とは何か
まずファイルの説明から。Claude Code で作業するとき、毎回ゼロから説明しなくて済むように「知っておいてほしいこと」を書いておくマークダウンファイルが CLAUDE.md です。新しい会話を開くたびに自動で一緒に読み込まれます。
ふつう書くのはこういうものです。このプロジェクトが何をするものか、どのコマンドで実行しテストするか、使ってはいけないライブラリは何か、回答は何語にするか。
ここで誤解が一つ生まれます。このファイルが設定ファイルのように強制されると考えることです。そうではありません。CLAUDE.md はプロンプトと一緒に読み込まれる指示の集まりで、読まれることと守られることは違います。だからファイルが長くなるほどルール同士が場所を取り合い、肝心の指示が些細な指示に埋もれます。
当サイトで一度扱った「Claude が実際に従う CLAUDE.md はどう書くか」がその話でした。あちらが一つのファイルをどう書くかだったとすれば、この記事はファイルをどこに置くかです。
三か所 — どこに置くかで、どこまで効くかが決まる
推奨される配置は三層です。同じ名前のファイルなのに、どこに置くかで適用範囲が変わります。
| 場所 | 適用範囲 | 書くのに向くもの |
|---|---|---|
| ホームディレクトリ（~/.claude/CLAUDE.md） | 自分のマシンの全プロジェクト | 回答言語、コミットメッセージの習慣、常に守ってほしい姿勢 |
| プロジェクトルート（./CLAUDE.md） | そのリポジトリ全体 | このプロジェクトが何か、実行・テストのコマンド、リポジトリ全体の禁止事項 |
| 個別のフォルダ（./src/api/CLAUDE.md） | そのフォルダで作業するときだけ | その領域にしかないルール — API のレスポンス形式、局所的なコード慣習 |
三つとも読み込まれる — そして衝突すると具体的なほうが勝つ
三つのファイルはどれか一つが選ばれるのではありません。該当するものが全部ロードされてマージされます。
だからルールが食い違うことが起きますが、そのときは最も具体的なファイルが勝ちます。フォルダの CLAUDE.md がプロジェクトルートに勝ち、プロジェクトルートがホームディレクトリに勝ちます。
この順序がなぜ自然かは、会社の規程にたとえると分かりやすい。全社規程があり部門規程がありチームのルールがあるとき、三つが食い違えば最も近いチームのルールに従うのと同じです。
大事なのは優先順位が「ある」ことではなく、それを使えるように場所を分けて初めて機能するという点です。全部が一つのファイルにあれば、順位をつける軸そのものがありません。
一つのファイルに寄せると何が壊れるか — 静かな衝突
ここがこのアンチパターンの核心です。ルールが多いことが問題なのではなく、ルールが自分の持ち場を離れることが問題です。
たとえばフロントエンドのフォルダでしか必要ない「スタイルはインラインで書かずユーティリティクラスで」という指示が、プロジェクトルートにあるとします。データ整理のスクリプトを書く作業にもこの一文がついてきます。データスクリプトにスタイルはないから何も起きないように思えますが、そうではありません。無関係な指示も読まれた分だけ、他の指示の相対的な重みを削ります。
もっと悪いのは実際に食い違うときです。ルートに「すべての関数に型を明示すること」があるのに、あるフォルダは自動推論に任せる慣習を使っているなら、二つのルールは毎回ぶつかります。
しかもこの衝突は失敗として現れません。ビルドが壊れることも警告が出ることもない。結果が微妙にずれる形で出てきて、どの行がどの行と争ったのかはどこにも記録されません。だから長く続きます。
どの行をどこへ移すか — 判定の問いは一つ
実際に整理するときは、ルールごとに問いを一つ投げるだけで足ります。「このルールはこのリポジトリのすべてのフォルダに当てはまるか」
当てはまればそのまま。当てはまらなければ、そのルールが実際に効くフォルダの CLAUDE.md へ移します。なければそのフォルダに新しく作ります。ファイル名はどこでも CLAUDE.md で同じです。
もう一段上げてみることもできます。「このルールはこのプロジェクトではなく、自分のすべての作業に当てはまるか」当てはまればホームディレクトリへ上げます。回答言語やコミットメッセージの習慣がここに当たります。
肝心なのは消すのではなく移すことです。ルールを減らそうという話ではなく、必要のない場所で読まれないようにしようという話です。
~/.claude/CLAUDE.md # すべてのプロジェクトに適用
my-project/
├── CLAUDE.md # このリポジトリ全体に適用
├── src/
│ ├── api/
│ │ └── CLAUDE.md # api/ で作業するときだけ
│ └── web/
│ └── CLAUDE.md # web/ で作業するときだけ
└── scripts/
今日やってみること一つ
CLAUDE.md を開いて上から一行ずつ読みながら「このルールはこのリポジトリ全体に当てはまるか」を問うてみてください。二十行を超えるファイルなら、三、四行は必ず「いいえ」になります。
その行を切り取って、該当するフォルダの CLAUDE.md に貼ります。ファイルがなければ作ります。今日やることはそれだけです。
効果は次の会話から出ます。無関係な作業をさせたときに見当違いの指示が引っぱられてこなくなり、本当に守ってほしいルールが相対的に大きく読まれます。
次回は三つ目のアンチパターンです。エージェント一つにツールを何個までつけてよいかという話です。