従われるCLAUDE.md
ほぼ誰もが陥る罠があります。それはCLAUDE.mdファイルがどんどん大きくなっていくというものです。問題にぶつかるとルールを追加する。また別の問題にぶつかると、さらにルールを追加する。そうこうしているうちに、巨大な1つのファイルができあがり、Claudeはその一部を無視し始めます。これはClaudeのバグではありません。このファイルの仕組みそのものなのです。
理解しておくべき重要な点は、CLAUDE.mdは強制される設定ではないということです。これはガイダンスです。すべての行が、Claudeの注意を引くために他のすべての行と競合しています。ファイルが長くなればなるほど、それ自身との競合が増え、Claudeが個々のルールに確実に従う可能性は下がります。つまり、目標はすべてを書き留めることではありません。目標はファイルを引き締めておくことです。ファイルが無駄を削ぎ落とされているほど、Claudeは実際により多くの部分に従うようになります。
まず、CLAUDE.mdが本当に適切なツールかどうかを問う
ルールを書く前に、そもそもそれがCLAUDE.mdに属するものなのかを問いましょう。ルールの中にはガイダンスに過ぎないものもあれば、決して越えてはならない絶対的な一線であるものもあります。これらはまったく別の役割です。
「mainブランチには絶対にプッシュしない」というルールを例に取りましょう。これをCLAUDE.mdに書いた場合、Claudeがそれを読んで守ってくれることを期待することになります。ほとんどの場合はそうなるでしょう。しかし、それほど危険な事柄に対して「ほとんどの場合」では不十分です。このような絶対的なルールは、代わりにpre-tool-useフックに置くべきです。
この違いは重要です。フックはClaudeが行動を起こす前に実行されるコードであり、実際にその行動をブロックすることができます。つまり、たとえClaudeがmainにプッシュしようとしても、フックがそれを止めます。これは丁寧なお願いではなく、実際の強制力です。絶対的なルールはフックに移し、CLAUDE.mdにはより緩やかな慣習を扱わせましょう。
4つの配置場所
CLAUDE.mdはプロジェクトに1つだけ存在するファイルではありません。配置できる場所は4か所あり、Claudeは起動時にそれらすべてを一緒に読み込みます。何も省略されることはなく、それらは積み重なります。
それぞれの用途は次のとおりです。
- 管理ポリシー — プラットフォームチームが管理する組織レベルのファイルです。これを除外することはできないため、組織のポリシーは常に適用されます。
- ユーザー — あなたの個人的な好みを記したもので、マシン上のすべてのプロジェクトに適用されます。
- プロジェクト — チームと共有され、リポジトリにチェックインされるファイルです。
- ローカル — gitから無視されます。このリポジトリだけに限った、あなた個人のメモです。
最後のローカルは見落とされがちですが、実はとても便利です。たとえば、自分のブランチでリファクタリングを行っていて、作業中にClaudeにいくつかのアーキテクチャ上の決定事項を念頭に置いておいてほしいとします。それはチーム全体に影響を与える共有のプロジェクトファイルに置くべきものではありません。そういうものはローカルに置くことで、このリポジトリにおいてはあなただけのものになります。
インポートで大きなファイルを分割する
プロジェクトファイルが長くなってきたら、パス指定によるファイルインポート構文を使ってファイルを分割できます。1つの巨大な文章の壁の代わりに、他のファイルを参照するようにします。
@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.mdこれは整理整頓には最適です。ただし、これが実際に何をもたらすのかを正確に理解しておいてください。誤解しやすい部分だからです。Claudeが起動すると、参照した場所にそれらのインポート対象ファイルをインラインで展開します。つまり、インポートは整理整頓には役立ちますが、結局すべてが最初に読み込まれることに変わりはありません。Claudeが読み込まなければならないコンテキストの量を減らすわけではないのです。インポートは整理のために使うものであり、読み込み量を減らすためのものではありません。
ルールを定着させるのは言い回し次第
あるルールをCLAUDE.mdに入れると決めたら、実際にClaudeがそれに従うかどうかは、その書き方にかかっています。ほとんどのルールがうまくいかないのは、曖昧だからです。それを直す方法を見ていきましょう。
具体的かつ検証可能にする
「ベストプラクティスに従う」とは書かないでください。そもそも、それが正確に何を意味するのか、あなた自身わかっていますか?守られたかどうかを確認できないなら、Claudeにもできません。次の2つを比較してみましょう。
- 曖昧な例: 「APIルートについてはベストプラクティスに従うこと」
- 具体的な例: 「新しいAPIルートは
src/api/handlersに、1ファイル1ルートで配置すること」
2番目の例は明確です。結果を見れば、正しく行われたかどうかをすぐに判断できます。それがすべてのルールが満たすべき基準です。
何かを禁止するだけでなく、代わりの案を示す
Claudeに何かをしないよう伝えるときは、代わりに何をすべきかも伝えましょう。そうしないと、解釈の余地を残してしまいます。
- 余地を残す: 「デフォルトエクスポートを使わない」 わかった、では代わりに何を?
- 余地をなくす: 「デフォルトエクスポートではなく、名前付きエクスポートを使う」
2番目の言い方は代わりの案を明示しているため、誤解の余地がありません。
大声を張り上げるのではなく、平易に言葉にする
「IMPORTANT」や「YOU MUST」といった言葉は、Claudeが見落とし続けているルールをめったに救ってはくれません。現行のモデルは平易に書かれた一文にきちんと従うものであり、強調を重ねることは、むしろClaudeにそのルールを過剰に適用させる結果になりがちです。曲げられないルールであれば、フックにしましょう。見落とされがちなら、ファイルを短くしましょう。
ファイルを改訂し続ける
あなたのCLAUDE.mdファイルは決して完成しません。常に編集され続ける、生きたコードのように扱いましょう。
Claudeが間違ったことをしたとき、ただため息をついて手作業で直すだけでは不十分です。それをCLAUDE.mdファイルに対するバグ報告として扱いましょう。Claudeに直接「それをCLAUDE.mdファイルに追加して」と伝えることさえでき、Claudeがそのルールを書いてくれます。そうすることで、何か問題が起きるたびにファイルはより良くなっていきます。
まとめ
CLAUDE.mdを本番コードのように扱いましょう。ある行の存在を正当化できないなら、それは削除すべきです。ファイルを引き締まった、従いやすいものに保つには、次のようにします。
- 絶対的なルールはフックに移し、実際に強制されるようにする。
- 長いファイルはインポートで整理する(ただし、それがコンテキストを減らすわけではないことを忘れない)。
- すべてのルールを具体的かつ検証可能にし、代わりの案を示す。
- ルールは強調を加えるのではなく、平易な言葉で書く。
- Claudeが何か問題を起こすたびに、ファイルを改訂し続ける。
考え方はシンプルです。ファイルが引き締まっているほど、Claudeはそれにより多く従います。