CLAUDE.md のトークンコストと適切な長さ

CLAUDE.md は、セッション開始時に Claude Code がコンテキストウィンドウにロードする、常駐指示を書いた Markdown ファイルです。システムプロンプトの一部ではなく、Claude Code はそれをユーザーメッセージとして直後に送信し、Claude は設定としてではなくガイダンスとして扱います。

モデルはリクエスト間で状態を保持しないため、Claude Code は毎回全コンテキストを再送します：システムプロンプト、プロジェクトコンテキスト、過去のメッセージ、ツール結果すべてです。ツール使用の各ラウンドは新たな呼び出しになるので、5つのファイルを読んでテストを実行させるプロンプトでも、CLAUDE.md 全体が複数のリクエストに含まれます。

要するに、各行はすべてのリクエストで課金され、キャッシュが有効な間は割引が適用されますが、キャッシュが再構築されるたびに通常の入力価格以上になります。ファイルはできるだけ短く保ち、毎回必要ない内容はオンデマンドで読み込むファイルへ移動しましょう。

どのファイルがいつロードされるか

Claude Code は見つけたメモリーファイルをすべて連結し、上書きはしません。2026年9月時点の Claude Code ドキュメントでは、以下のソースが列挙されています。

• →管理ポリシー: IT が展開する組織全体の CLAUDE.md（例: Linux の /etc/claude-code/CLAUDE.md）。除外できません。
• →ユーザー: ~/.claude/CLAUDE.md と ~/.claude/rules/ 内のルール。マシン上のすべてのプロジェクトに適用されます。
• →プロジェクト: ./CLAUDE.md または ./.claude/CLAUDE.md、加えて paths フィールドがないすべての .claude/rules/ ファイル。バージョン管理で共有されます。
• →ローカル: ./CLAUDE.local.md。特定プロジェクト向けの自分用メモで、.gitignore に追加します。
• →自動メモリ: リポジトリ用に Claude が保持する MEMORY.md インデックスの最初の 200 行または 25KB。参照先のトピックファイルは必要時にのみ読み込まれます。

作業ディレクトリとその上位ディレクトリのファイルは起動時にロードされます。サブディレクトリの CLAUDE.md はそのディレクトリ内のファイルが読み込まれたときにのみロードされ、paths を持つルールも対象ファイルが読まれたときだけです。インポートは罠で、@path/to/file 行は起動時にそのファイルを最大4階層まで再帰的に取り込みます。そのため、長いファイルをインポートに分割してもトークンは削減されません。

キャッシュが無料にならない理由

プロンプトキャッシュを使用すると、API は各リクエストの先頭部分を直近に処理した内容と比較し、同一部分は割引料金で請求します。Claude Code は変更頻度が低いものを先頭に配置し、システムプロンプトとツール定義、次にプロジェクトコンテキスト（メモリーファイル）、最後に会話を送ります。通常のターンでは、CLAUDE.md はキャッシュ読み取りとして扱われます。

Anthropic が公表している API 料金（2026年9月）では、キャッシュ読み取りはほとんどの Claude モデルで基本入力価格の 1/10、最新モデルではさらに低くなります。キャッシュ書き込みは 5 分間の有効期限で基本価格の 1.25 倍、1 時間の場合は 2 倍です。プレフィックスを書き直す必要があるたびに、CLAUDE.md は通常入力より高い料金で課金されます。これが頻繁に起こります：

• →キャッシュ有効期限を超える休止後：Claude サブスクリプションのメイン会話は 1 時間、API キー使用時はデフォルトで 5 分。
• →モデルを切り替えたとき（モデルごとにキャッシュが別）や、ほとんどのモデルでエフォートレベルを変更したとき。
• →それ以前のツール定義が変わったとき。例: セッション途中で接続する MCP サーバーのツールが事前にロードされる場合。
• →組み込みの Explore と Plan を除くすべてのサブエージェントでは、各エージェントが独自のコンテキストに CLAUDE.md をロードし、デフォルトで 5 分間のキャッシュを構築します（サブスクリプションでも同様）。
• →セッション開始ディレクトリごとの作業ツリーやディレクトリでも、キャッシュは実質的にそのディレクトリ単位でスコープされます。

キャッシュは価格を変えるだけでサイズは変わりません。ファイルはすべてのリクエストでウィンドウを占有し、会話用の余裕が減り自動圧縮が早まります。長いファイルはルールごとの注意が分散するため、遵守度が低下します。サブスクリプションでは請求書はありませんが、同じコンテキストがプランの使用上限を消費します。

自分のコストを確認する方法

新しいセッションを開き、何も入力する前にウィンドウ内の内容を確認します：

$/context

/memory はメモリーファイルを一覧表示し、任意のファイルをエディタで開きます。Claude Code v2.1.251 以降、/usage は Prompt cache (main) 行を追加し、キャッシュから供給された入力の割合とミス回数を示します。ミス回数が増えるということは、プレフィックス（メモリーファイル含む）が再度書き直されていることを意味します。

何を入れるべきか

Anthropic の各行に対するテストは「削除したら Claude が誤動作するか？」です。問題なければ削除します。残るものは通常短くなります：

• →Claude が推測できないビルド・テスト・lint コマンド。
• →デフォルトと異なるコードスタイル規則（フォーマッタが既に適用しているものは除く）。
• →リポジトリのエチケット：ブランチ名、コミット・プルリクエストの規約。
• →プロジェクト固有のアーキテクチャ決定。
• →環境固有の注意点（必須変数や必ず起動している必要があるサービスなど）。
• →落とし穴：既に誰かの午後を浪費させたような、直感的でない挙動。

各ルールは検証可能な形で記述してください。例: npm test をコミット前に実行する、は有効ですが、変更をテストする、は不十分です。ドキュメントの目標はファイルあたり 200 行未満です。

どこへ移すか、移すべきもの

肥大化した CLAUDE.md の多くは間違っているわけではなく、場所が不適切です。コンテンツの種類ごとにコストの低い保存場所があります：

• →Claude がコードから読める情報（ディレクトリ構成、依存リスト、ファイルごとの説明など）は削除してください。
• →API リファレンスやスタイルガイドなどの長い参照資料は別ファイルに保存し、@ を付けずにパスだけを記述します。Claude はタスクで必要になったときにのみ開きます。
• →リリースチェックリストのような多段階手順はスキル化してください。スキルの短い説明だけがセッション開始時にロードされ、残りは使用時にロードされます。
• →コードベースの一部に対するルールは、paths パターンを持つ .claude/rules/ ファイル、またはそのサブディレクトリの CLAUDE.md に配置します。どちらも対象ファイルが読まれたときにのみロードされます。
• →毎回実行が必要な処理（例: 編集後のフォーマット）はフックにしてください。フックは出力を返さない限りコンテキストを消費せず、指示とは異なり強制されます。

削減手順

Claude Code に同梱されているチェックアップから始めます。v2.1.206 以降、/doctor はチェックインされた CLAUDE.md に対して削除提案を行います。コードベースから導出できる内容は削除し、落とし穴やツールデフォルトと異なる根拠・規約は残し、常にロードされるガイダンスはスキルやオンデマンドでロードされるネストファイルへ移動します。

$/doctor

その後、手作業で数回見直します：

• →Claude が自動的に従うルールを削除し、動作が変わらないか確認します。
• →メンテナ向けのメモはブロックレベルの HTML コメントに変換します。Claude Code はモデルに届く前に <!-- ... --> ブロックを除去します。
• →矛盾を解消します。相反する2つのルールは二重に課金され、Claude がどちらかを選択する可能性があります。
• →モノレポでは claudeMdExcludes 設定で他チームのファイルを除外します。
• →何も必要としないカスタムサブエージェントには、定義に omitClaudeMd: true を設定します（v2.1.271 以降）。

AGENTS.md と Codex CLI

Codex CLI は代わりに AGENTS.md を読み取ります。2026年9月のドキュメントによると、実行ごとに（対話インターフェースでは通常セッションごとに）指示チェーンを構築します：

• →グローバル: ~/.codex、または設定されていれば CODEX_HOME、AGENTS.override.md が存在すればそれ、なければ AGENTS.md。
• →プロジェクト: プロジェクトルート（通常は Git ルート）から起動ディレクトリまで、ディレクトリごとに最大1ファイル、順に AGENTS.override.md、AGENTS.md、project_doc_fallback_filenames に列挙された名前。
• →ルートから下へ結合し、空ファイルはスキップ、合計サイズが project_doc_max_bytes（デフォルト 32 KiB）に達したら追加を停止します。

結果はセッションの最初のターンに組み込まれ、以降のリクエストに引き継がれます。Codex の使用上限を長持ちさせるためのヒントは AGENTS.md を縮小し、管理対象ディレクトリにファイルをネストすることです。2026年9月時点の料金表では、キャッシュ入力は新規入力の 1/10 で請求され、キャッシュ書き込み料金は別途ありません。モデルが受け取る指示を見るには：

$codex debug prompt-input

1つのファイルで両エージェントに対応できます。v2.1.277 以降、作業ディレクトリまたは上位に CLAUDE.md や CLAUDE.local.md が無い場合、Claude Code は AGENTS.md をプロジェクト指示として読み取ります。そうでなければ、CLAUDE.md の先頭に @AGENTS.md を記述してください。Claude Code は AGENTS.override.md を読み取りません。

固定費と変動費

指示ファイルを削減すると請求の固定部分が小さくなります。残りは各タスクが追加で読むファイル、コマンド出力、履歴です。対象ファイルを明示し、タスクごとに新しいセッションを開始すればこの部分も抑えられます。

上限を厳密に設定したい場合、capsul が既にサインインしている Claude Code または Codex CLI を操作し、タスクが要求する内容を設定したトークン予算内で送信し、除外した部分を報告します。測定結果はベンチマークページに掲載されています。