Claude Codeのトークン予算は有限で、CLAUDE.mdは全セッションに読み込まれます。多くのガイドは「短く保つ」で終わりますが、本記事はその先を扱います。レイジーロードパターン、条件付きセクション、メモリオフロードアーキテクチャ、そしてカットを始める前に何がコンテキストを食べているかを明らかにする実測手法です。
本記事はCLAUDE.mdトークン最適化ガイドの基礎を前提に、より踏み込んだ内容を扱います。
異なるトークンプロファイルの実際のCLAUDE.mdファイルはギャラリーで確認できます。
なぜ通常の削減では不十分なのか
「使っていないものを削除する」というアドバイスはすぐに上限に達します。問題は、よく管理されたCLAUDE.mdのほとんどは実際に使われているということです。削れない。別の戦略が必要です。
核心にある洞察：CLAUDE.mdは最悪ケースの動作（指示なしでClaudeが間違いを犯す）を防ぐために最適化されていますが、「この関数は何を返すか？」のような単純なリクエストを含む全てのリクエストで読み込まれます。3,000トークンのCLAUDE.mdを単純なタスクに対して読み込むのは、そのリクエストに対して何の恩恵もない高いコストです。
上級最適化とは、命令の密度を実際のタスクの複雑さに合わせることです。
ステップ1：命令の分類
最適化の前に、CLAUDE.mdの全内容を4つのバケツに分類します。
常に必要（コア）。 ほぼすべてのタスクで、これがなければClaudeが間違える命令。例：「TypeScript strictモードを常に使う」「本番コードにconsole.logを書かない」。これらはCLAUDE.mdに残します。
頻繁に必要。 ほとんどの作業に関連しているが全てではない命令。例：「APIのベースURLはX」「デザインシステムのトークンは/src/tokensにある」。MEMORY.mdパターンの候補です。
めったに必要でない。 特定のタスクにのみ関係する命令。例：詳細なマイグレーション手順、レガシーシステムの特性、リリースプロセスの手順。これらはCLAUDE.mdに置くべきではありません。
デッド。 使わなくなったパターン、廃止した依存関係、終わったプロジェクトフェーズのコンテキスト。削除します。
多くのCLAUDE.mdファイルはデッドまたはめったに必要でないコンテンツを30〜50%含んでいます。削除が最速の改善です。
レイジーローディングとMEMORY.md
標準のCLAUDE.mdパターンは全てを事前に読み込みます。MEMORY.mdパターンはナレッジベースを分割します：
~/.claude/CLAUDE.md（または./CLAUDE.md）
→ コア命令のみ（目標：800トークン未満）
./MEMORY.md（または.claude/MEMORY.md）
→ 拡張ナレッジ、必要時にオンデマンドで読み込むCLAUDE.mdには1行の参照のみを追加します：
## 拡張ナレッジ
プロジェクト固有の詳細、規約、参照情報はMEMORY.mdを読むこと。
これらのコア命令を超えるコンテキストが必要な場合に読み込む。ClaudeがMEMORY.mdを読むときのトークンコストは削減されませんが、いつ読むかのコントロールができます。単純なタスクでは読まない場合もあります。複雑なタスクでは1回読み込まれ、そのセッションの残りのコンテキストに残ります。
結果として、本当に必要なときだけ全トークンコストを支払い、単純なリクエストでは支払わなくて済みます。
MEMORY.mdの構造
# プロジェクトメモリ
## アーキテクチャ
[システム設計、主要コンポーネント、データフロー]
## APIとインフラ
[エンドポイント、認証パターン、外部サービスの詳細]
## 開発規約
[コードスタイルの詳細、推奨パターン、避けるパターン]
## デプロイ
[ビルド・テスト・リリース方法]
## 現在の作業
[アクティブなスプリント、現在のPR、未解決のイシュー — 定期的に更新]
## 過去の決定事項
[ADRと理由 — なぜXではなくYを選んだか]「現在の作業」セクションは特に重要です。頻繁に変わるコンテンツで、CLAUDE.mdに置くと古い情報が蓄積します。MEMORY.mdに置いて定期的に更新します。
条件付きセクションパターン
CLAUDE.mdの全セクションが全タスクに関係するわけではありません。どのセクションがいつ適用されるかをClaudeにヒントとして伝えることができます：
## フロントエンド作業（/src/componentsまたは/src/pagesで作業する場合に適用）
- /src/tokens/のデザインシステムトークンを常に使う
- デフォルトでサーバーコンポーネントを使う。"use client"は必要な場合のみ
- インラインスタイルよりTailwindユーティリティクラスを優先
## バックエンド作業（/apiまたは/servicesで作業する場合に適用）
- /lib/db.tsのクエリビルダーを使う — 生のSQLは禁止
- 全エンドポイントで入力にZodバリデーション必須
- エラーはconsole.errorではなく/lib/logger.tsでログを記録
## テスト（テストの作成または変更時に適用）
- ユニットテストはvitest、E2EはPlaywright
- テストコマンド: npm test（ユニット）/ npm run test:e2e（E2E）
- UIコンポーネントのスナップショットテストは禁止これによりCLAUDE.mdの全体が自動的にスコープされるわけではありません。全体がコンテキストに残ります。ただし、どのセクションを優先するかのガイドになります。バックエンドエンドポイントで作業しているとき、Claudeはフロントエンドセクションよりバックエンドセクションを自然に重視します。
トークン効率の高い命令の書き方
命令の品質はトークンコストに影響します。冗長な命令が常により良い命令とは限りません。
説明をルールに置き換える
改善前（冗長）：
TypeScriptを書く際、オブジェクト形状の定義にはtypeよりinterfaceを好んで使います。
なぜならinterfaceはより拡張性が高く、より良いエラーメッセージを出力するからです。
ただし、ユニオン型、マップ型、条件付き型については、interfaceがこれらのパターンを
表現できないため、型エイリアスを使います。改善後（ルール優先）：
TypeScript: オブジェクト形状には`interface`、ユニオン/マップ/条件付きには`type`を使う。ルール優先版は約70%短く、同様に実行可能です。ClaudeはトレードオフをすでにE知っています。トークンを払って既知の情報を伝えています。
自明な文を削除する
これらはトークンを追加しますが動作を変えません：
- 「クリーンで保守しやすいコードを書く」（Claudeはすでにそうしようとしている）
- 「複雑なコードに役立つコメントを追加する」（すでにデフォルト動作）
- 「ベストプラクティスに従う」（具体的な命令でない）
削除します。シグナルではなくノイズです。
大規模ナレッジベースのリファレンスパターン
広範なドキュメントを持つ大規模プロジェクトでは、CLAUDE.mdをナレッジストアではなくインデックスとして使います：
## リファレンス資料
プロジェクト固有のコンテキストが必要な場合は以下のファイルを参照：
- **アーキテクチャ**: docs/ARCHITECTURE.md
- **API仕様**: docs/api/README.md
- **データモデル**: prisma/schema.prisma + docs/DATA_MODEL.md
- **デプロイ**: docs/DEPLOYMENT.md
- **テスト基準**: docs/TESTING.md
現在のタスクに必要なものだけを読むこと。参照されたコンテンツの事前トークンコストはゼロです。Claudeは必要なときに特定のドキュメントを読みます。大規模なナレッジベース（1万トークン以上のドキュメント）では、セッションのトークンオーバーヘッドを80%以上削減できます。
実際の影響の測定
理論上のトークン数を知るだけでは不十分です。セッションで実際に何が起きているかを測定する必要があります。
CLAUDE.mdが重すぎるサイン
- ClaudeがCLAUDE.mdを要約・言い換えて返してくる（圧縮しようとしている）
- セッション序盤に
/compactが推奨される - 単純なタスクが遅い感じがする
- ファイルの深いところに埋まった命令をClaudeが見逃す
CLAUDE.mdが薄すぎるサイン
- 確立した規約についてClaudeが頻繁に確認を求めてくる
- 繰り返しの修正パターン（「違う、うちではXじゃなくてYを使う」を何度も言う）
- 同じタイプのタスクでセッション間の出力が一貫しない
コアCLAUDE.mdは通常600〜1,200トークンが適切な範囲で、拡張ナレッジはMEMORY.mdや参照ドキュメントに置きます。
基礎についてはCLAUDE.mdトークン最適化ガイドを参照してください。プロジェクトタイプ別のテンプレートはユースケーステンプレートで確認できます。実際のCLAUDE.mdのサンプルはギャラリーにあります。