CLAUDE.mdの@importはコンテキストを減らさない：公式が明言する誤解と本当の削減策3つ

Claude Codeを使い込むと、CLAUDE.md がどんどん肥大化します。プロジェクトのルール、コーディング規約、過去の決定事項。気付けば数千行になっていた、という人は多いと思います。

context（＝AIが一度に読み込める作業記憶。ここを使い切ると精度も速度も落ちる）は有限です。だから、こう考えるのは自然な流れでした。

「CLAUDE.md を @import で複数ファイルに分割すれば、必要なものだけ読み込まれてコンテキストが軽くなるはず」

これは誤解でした。私自身、最初は「最優先で導入すべき」と判断しています。ところが公式ドキュメントを確認したら、明確に否定されていたのです。

この記事では、@import（＝CLAUDE.mdから別ファイルを読み込む記法）の本当の挙動と、コンテキスト消費を実際に減らす3つの方法を整理します。

結論：@importは「整理」のためで、コンテキストは減らない

公式ドキュメントの記述がすべてです。

"Splitting into @path imports helps organization but does not reduce context, since imported files load at launch." （@path インポートへの分割は整理に役立つが、インポートされたファイルは起動時に読み込まれるため、コンテキストは削減しない） （出典：Claude Code公式ドキュメント）

@import でできること、できないことを分けるとこうなります。

10個のファイルに分けようが、起動時に全importが展開されてコンテキストに乗ります。中身の合計は変わりません。分割は人間の見通しのためであって、AIの作業記憶を空けるものではない。ここを混同すると、いくら整理しても軽くならず、原因を見失います。

コンテキストを本当に減らす3つの方法

では何を使えば実際に減るのか。3つあります。コンテキストをどう管理するかという土台の考え方はコンテキストエンジニアリングの基本でも整理しているので、合わせて読むと選び方の軸がはっきりします。

方法1: path-scoped rules（paths: frontmatter）

.claude/rules/*.md に paths: frontmatterを書くと、指定したパスのファイルをClaudeがReadしたときにだけ、そのルールが読み込まれます。常時ロードはされません。

---
paths:
  - "src/components/**/*.tsx"
  - "src/**/*.css"
---

# UIコンポーネントのルール
（このルールはUIファイルを編集するときだけ読まれる）

「UIを触るときだけUIルールを読む」「DBマイグレーションを触るときだけDBルールを読む」。作業中のファイルに応じて必要なルールだけを動的にロードできます。

方法2: スキル化（skills/）

skills/ に置いたスキルは、呼び出された（invokeされた）ときだけ本体が読み込まれます。3つの中で最も軽量です。

• 普段: スキルの名前と説明（数行）だけがコンテキストに乗る
• 使うとき: そのスキルの本体（手順・スクリプト）が読み込まれる

「めったに使わないが、使うときは詳細な手順が必要」なものはスキル化が向いています。

方法3: HTMLブロックコメント（<!-- -->）

ファイルに残したいが、Claudeのコンテキストには入れたくないメンテナンスメモは、HTMLコメントで囲みます。

<!-- 
このセクションは廃止予定。
理由: xxx。担当: yyy。
-->

ファイルには残るので人間は読めますが、Claudeのコンテキストには注入（injection）されません。「将来の自分へのメモ」を残すのに使えます。

使い分け表

path-scoped rulesの落とし穴：「発話キーワード」では発動しない

path-scoped rulesは強力ですが、重大な誤解ポイントが1つあります。

paths: frontmatterは、Claudeが該当ファイルをReadしたときに発動するものです。ユーザーが特定のキーワードを発話したときには発動しません。

たとえば「ユーザーが『東京拠点』と言ったら拠点マスタを参照する」のような、発話キーワードで発動させたいルール。これをpath-scopedにしてはいけません。ユーザーの発話にはファイル読み込みが伴わないので、ルールが永遠に発動しなくなります。

「コンテキストを減らしたい」と全ルールをpath-scoped化すると、発話ベースで発動すべき重要ルールが沈黙してしまう。適性を見極めて使い分けるのが正解です。

なぜこの誤解が生まれたか：一次情報を当たる教訓

私がこの誤解にハマった経緯も、教訓として共有しておきます。

ある調査レポートに「CLAUDE.md の @import 導入でコンテキストをスリム化」というHIGH優先度の提案がありました。私は最初、これを「最優先で採用すべき」と受け取っています。

ところが別のAIにセカンドオピニオンを求めたら、「@import は条件ロードではない、検証が必要」と指摘されました。そこで公式ドキュメントを確認すると、明文で否定されていた。判断が一段で覆った瞬間でした。

教訓は明快です。Claude Codeの機能について「コンテキスト削減策」「自動化策」を提案する前には、必ず公式ドキュメントで一次情報を確認する。リリースノートやコミュニティ記事の二次情報だけで判断すると、こういう誤解に足をすくわれます。

アンチパターン3つ

アンチパターン1: コンテキスト肥大化対策で@import分割する

「ルートのCLAUDE.mdが重いから@importで分割しよう」は軽量化としては無意味です。公式が「does not reduce context」と明言しています。整理目的なら有効、軽量化目的なら効果ゼロ。

アンチパターン2: path-scopedを「発話キーワード検出」と混同する

path-scopedはファイルRead時のみ発動します。「ユーザーが○○と言ったら」のルールをpath-scoped化すると、永遠に発動しません。

アンチパターン3: 二次情報だけで機能仕様を判断する

Claude Codeのような進化が速いツールは、コミュニティ記事の情報が古いことがあります。仕様の話は必ず公式ドキュメントを当たること。

まとめ：整理と軽量化を混同しない

CLAUDE.md の @import について、押さえておきたいのは次の4点です。

1. 整理には役立つが、コンテキストは減らない（起動時に全展開される、公式明言）
2. 本当に減らすなら、path-scoped rules / スキル化 / HTMLコメントを使い分ける
3. path-scopedはファイルRead時のみ発動。発話キーワードでは動かない
4. 機能仕様は公式ドキュメントで一次情報を確認してから判断する

コンテキストはClaude Codeの貴重なリソースです。「分割すれば軽くなる」という直感は外れていることが多い。ロードのタイミングを正しく理解し、適材適所で削減策を選ぶ。これが長期運用のコツになります。

AIエージェントの運用設計でお困りなら

「ルールやメモリをどこに置けばいいか分からない」「設定を増やすほどAIの精度が落ちている気がする」。Claude Codeを業務に定着させようとすると、コンテキスト設計のつまずきはほぼ必ず出てきます。f2t.jpではAIエージェントの運用設計から、コンテキストを圧迫しないルール構造の整理まで一貫してお手伝いしています。お問い合わせフォームからお気軽にどうぞ。