Claude Codeをインストールして真っ先に行うのが「CLAUDE.md」の作成ですが、公式ドキュメントを読み解くと、この「CLAUDE.md」の適切な運用に関して、いくつかの注意点が存在しました。

今回は、それらの注意点を公式ドキュメントからピックアップしてまとめます。

1. 「詰め込みすぎ」は逆効果

最も避けるべきは、CLAUDE.mdにあらゆる情報を詰め込んでしまうことです。

公式ドキュメントの重要な警告

公式ドキュメントより引用：

“Bloated CLAUDE.md files cause Claude to ignore your actual instructions!”
（肥大化したCLAUDE.mdファイルは、Claudeが実際の指示を無視する原因となります！）

（リンク）

なぜ問題となるのか

処理する情報量の増大とそれによる精度低下:
CLAUDE.mdの内容は毎回の発言の冒頭に「必ず」付加されるため、ここが肥大化すると、簡単な質問一つに対しても毎回膨大な情報を再読み込みさせることになり、動作の遅延や処理効率の悪化を招く「無駄の多い構成」になってしまいます。

公式ドキュメントより引用：

“Claude’s context window holds your entire conversation, including every message, every file Claude reads, and every command output. However, this can fill up fast. LLM performance degrades as context fills. When the context window is getting full, Claude may start “forgetting” earlier instructions or making more mistakes.”
（Claudeのコンテキストウィンドウ（記憶容量）には、すべてのメッセージ、読み込んだファイル、実行したコマンドの結果など、会話の全内容が保存されます。ただし、これらはすぐに容量がいっぱいになってしまいます。LLMの性能は、コンテキストが埋まるにつれて低下し、容量が限界に近づくと、Claudeは以前の指示を「忘れ」始めたり、ミスが増えたりします。）

（リンク）

結果として重要なルールを無視し始めるため、情報を絞ることが回答精度の維持に直結します。

CLAUDE.mdの推奨行数

上記に対して、公式ドキュメントでは CLAUDE.md のファイルサイズを500行以内 に収めることが推奨されています。

公式ドキュメントより引用：

“Keep CLAUDE.md under ~500 lines. Move reference material to skills, which load on-demand.”
（CLAUDE.mdを約500行以下に保ってください。参照資料は、必要に応じて読み込まれるスキルに移動してください。）

（リンク）

その一方で、必要な情報はコンテキストとして適切に渡す必要があり、内容によっては500行では足りない、ということあるかと思います。

この課題を解決するために「CLAUDE.mdファイルをスリムにしつつ、必要な時に必要な情報だけを展開する」ための仕組みが用意されています。

その核となるのが以下の2つの戦略です。

2. メモリの階層化：AIの視界を「今やっている作業」に絞る

公式ドキュメントが推奨するもっとも強力な対策は、メモリを1箇所にまとめず階層化することです。

構成例を下記に示します。

フォルダ構成例

~/ (ホームディレクトリ)
├── .claude/
│ └── CLAUDE.md <-- 【PC全体のスタイル】「日本語で回答」など共通の好み
│
└── my-project/ (プロジェクト階層)
│└── CLAUDE.md <-- 【プロジェクトの憲法】ビルドコマンドなど「全員必須」のルール
│
└── src/
│└── components/
││└── CLAUDE.md <-- 【局所的な専門知識】UI設計規約など、ここを触る時だけロード

なぜこれが効くのか？

公式ドキュメントより引用：

“CLAUDE.md files in child directories load on demand when Claude reads files in those directories.”
（子ディレクトリ内のCLAUDE.mdファイルは、Claudeがそれらのディレクトリ内のファイルを読み取る際にオンデマンドで読み込まれます。）

（リンク）

例えば、ルート階層（my-project/）で作業をしている時はその時不要な細かい規約（src/components/CLAUDE.md）は読み込まれない、というように、今実施している作業に不要な情報を読み取る必要がなくなります。
これによりAIが「今関係していることのみ」を集中することが可能になり、無駄な情報の読み取りを抑えられます。

3. 情報の外部化：@参照とSkillsで必要な時に呼び出す

遵守すべきルール全てを CLAUDE.md に直接書くのではなく、切り出し可能な情報は外部に逃がしましょう。
AIが必要になった瞬間だけその情報をロードさせることで、無駄な読み込みを抑えることができます。

ここでは、情報の性質に合わせて「@参照」と「スキル（Skills）」を使い分けます。

① 外部参照 (@filename)：【静的な知識】のライブラリ

「情報を読み取る・参照する」ための仕組みです。膨大なドキュメントをAIの記憶（コンテキスト）に常駐させないために使います。

公式ドキュメントより引用：

“CLAUDE.md files can import additional files using @path/to/import syntax”
（CLAUDE.mdファイルは@path/to/importシンタックスを使用して追加ファイルをインポートできます）

（Claude Code Best Practices）

  • 主な用途例: スタイルガイド、複雑なAPI仕様書、用語集、プロジェクトの背景知識。
  • メリット: 何十ページもあるPDFやMarkdownを直接 CLAUDE.md に書く代わりに、1行のリンクで済みます。
  • 挙動: AIが「このフォルダの命名規則ってどうだっけ？」と疑問を持った時や、ユーザーが明示的に指示した時にだけ、中身を読みに行きます。

② スキル (Skills)：【動的な手順】の専門マニュアル

「特定のタスクを実行する手順」を覚えさせる仕組みです。.claude/skills/ ディレクトリ内に定義します。

公式ドキュメントより引用：

“Skills extend Claude’s knowledge with information specific to your project, team, or domain. Claude applies them automatically when relevant, or you can invoke them directly with /skill-name.”
（スキルは、プロジェクト、チーム、またはドメイン固有の情報でClaudeの知識を拡張します。Claudeは関連性がある場合に自動的にスキルを適用するか、/skill-nameで直接呼び出すことができます。）

（リンク）

  • 主な用途: PR（プルリクエスト）の作成手順、本番環境へのデプロイフロー、複雑なテストデータの生成スクリプト。
  • メリット: 「PRを作って」と頼むだけで、定義された手順（ブランチ確認→テスト実行→PR作成）を一気に自動実行できるようになります。
  • 挙動: AIが「あ、これはスキルに登録されている作業だ」と判断した瞬間に、そのマニュアルがロードされ、ツールとして実行されます。

まとめ

コンテキスト管理は、Claude Codeに限らずAI活用における重要な課題です。

場当たり的な指示を繰り返すのではなく、情報をいかに整理し、必要な時にだけ提供するか。この設計思想がパフォーマンスに大きな影響を与えます。

Claude Codeの運用を成功させるために、適切なCLAUDE.mdファイルの作成を心がけましょう。