こんにちは、ENECHANGEエンジニアの柿です。
Claude Codeを使っていると、/initでCLAUDE.mdを作成し、プロジェクトの情報を記述していくと思います。
しかし、CLAUDE.mdの/initによる記述量は比較的多く、そこにさらに追記・編集を加えると、CLAUDE.mdが大きくなってしまいます。
CLAUDE.mdはどのセッションでも最初に読み込まれるファイルなので、大きければ大きいほど、コンテキストウィンドウを圧迫してしまい、長いやり取りが困難になり、開発体験を損なう可能性があります。
また、公式ドキュメントには以下の記述があり、肥大化は非推奨とされています。
ミスを起こさないのであれば、削除してください。肥大化したCLAUDE.mdファイルは、Claudeが実際の指示を無視する原因となります。
そこで本記事では、CLAUDE.mdに何を書くべきかという判断基準と、肥大化した内容を整理するためのrules分割・@importsの活用方法を紹介します。
CLAUDE.mdとは
CLAUDE.mdは、プロジェクトのルートに置くマークダウンファイルで、Claudeに永続的な指示を与えるためのファイルです。ビルドコマンド、コーディング規約、アーキテクチャの決定事項、リポジトリの規約などを記述しておくことで、すべてのセッションの開始時に自動で読み込まれます。
CLAUDE.mdがあることによって、毎回コーディング規約、アーキテクチャの決定事項などを毎回伝える必要がなくなり、前提条件を共有したうえでタスクを実施することができます。
静的なファイルとして情報を持たせる効果は大きく、Vercelの事例でもAGENTS.md（Claude CodeではCLAUDE.mdに相当）にドキュメントインデックスを埋め込んだ静的アプローチが、skillsといった動的アプローチよりも精度が高いという結果が示されています。具体的には、skillsが明示的な呼び出し指示ありでも79%のテスト通過率にとどまったのに対し、AGENTS.mdを使った静的アプローチでは100%を達成しています。
つまり、CLAUDE.mdはコンテキストという文脈において、最も確実な情報伝達手段といえます。
では、CLAUDE.mdには一体何を書くべきなのでしょうか。
CLAUDE.mdに何を書くべきか
結論からいうと、書くべきことより、書かなくていいことを削ることの方が重要です。
/initで生成されるCLAUDE.mdはプロジェクト構造を元に自動生成されますが、出力は肥大化しやすい傾向があります。
そのため、既存のもので不要なものを削除していく必要があります。
ドキュメントによると目安は、200行以下目標となっています。
サイズ: CLAUDE.md ファイルあたり 200 行以下を目標にします。より長いファイルはより多くのコンテキストを消費し、遵守を減らします。
「どうせ削るなら0から書いた方が早い」と思う方もいるかもしれません。ただ、/initの生成物にはビルドコマンドやディレクトリ構造など、手動で書くと漏れやすい情報が含まれています。0から書くよりも、生成したものをベースに削る方が現実的だと私は考えています。
具体的に削除すべき内容は以下のようなものです。
- 特定の分野に関する知識やワークフロー
- 場面によってしか適用されないルールなど
削除の判断に迷ったときは、「これを削除したらClaudeがミスをするだろうか？」と質問してみてください。 この質問の意図としては、Claudeが実際にミスをした内容こそ記述すべき内容といえるためです。
さらに、開発を進める中でClaudeがミスをした際にも、都度CLAUDE.mdに追記していくとよいでしょう。
「二度とこのようなことが起こらないようにCLAUDE.mdに追記して」と伝えるだけで、Claudeが自らルールを作成し、次のセッションから自動的にそのルールに従ってくれます。
つまり、CLAUDE.mdをミスによって生きた文書にしていくことが重要ということです。
ただし、そのまま追記し続けると肥大化してしまうため、詳細な内容は後述するrules分割・@importsを活用することで対策します。
.claude/rules/ による分散管理
Claude Codeには.claude/rulesにマークダウンファイルを配置することで、ルールをファイルとして分割する仕組みがあります。
この仕組みは、特定の場面でのみルールを適用したい場合に非常に有効です。
デフォルトでは、すべてのrulesファイルはセッション開始時に読み込まれます。
特定のファイルを操作しているときのみルールを読み込むにはルールファイルのYAML フロントマターにpathsを指定します。
例えば、以下のように記述することができます。
--- paths: - "**/*.ts" --- # TypeScript conventions Prefer interfaces over types.
こうすることで、.tsファイルを操作するときだけTypeScriptの規約が読み込まれ、関係のないルールをコンテキストに乗せずに済むため、CLAUDE.md本体をシンプルに保てます。
また、一度読み込まれたルールは同一セッション内で重複して読み込まれない仕様のため、コンテキスト効率の面でも優れています。
@importsによる参照管理
CLAUDE.md内で以下のように記述することで、外部ファイルを参照できます。
@docs/git-instructions.md @README.md @~/.claude/my-project-instructions.md
@importsは「必要であればさらに詳しい情報はこちら」という形で機能します。CLAUDE.md本体には参照先だけを書いておき、詳細は外部ファイルに逃がすことで、セッションごとに不要な内容をコンテキストに乗せずに済みます。
例えば、コーディング規約やアーキテクチャの決定事項などは@docs/coding-style.mdや@docs/aarchitecture.mdのような外部ファイルに書いておき、@importsで参照することで、CLAUDE.mdの記述量をおさえることができます。
おわりに
本記事では、CLAUDE.mdの肥大化を防ぐための判断基準と、rules分割・@importsを使った管理方法を紹介しました。
改めて整理すると、重要なのは以下の3点です。
- 書かなくていいことを削る ── 指示しなくてもClaudeが正しく動く内容はノイズになる
- ミスを記録する ── 実際のミスから学んだルールこそ
CLAUDE.mdに書くべき内容 - 分散管理する ── 詳細はrules分割・@importsに逃がし、本体はスリムに保つ
CLAUDE.mdは一度書いたら終わりではなく、開発を通じて育てていくものです。肥大化に気づいたタイミングで見直し、常にスリムな状態を保つことが、長期的な開発体験の向上につながると思います。
参考文献
— Vishwas (@CodevolutionWeb) 2026年3月19日
