AIエージェントのトークン代を節約する CLAUDE.md と copilot-instructions.md 実践ガイド AIエージェントでは毎ターン何が起きているのか

CLAUDE.md や copilot-instructions.md は、AIエージェントに「このプロジェクトのルールを最初から教える」ためのファイルです。
一度書いたら終わり、という扱いをしている人が多いと思いますが、実はこれが 毎ターン・毎リクエストにしれっとコンテキストへ乗り続ける という性質を持っています。

ここを正しく整備すれば、「設計書→コード」「コード→設計書」という重たいタスクでもコストを削れる可能性があります。

※AIエージェントは日々進化しているので、情報が古い可能性があります。今回紹介した内容は2026年6月8日時点の情報です。

---

3行まとめ

• CLAUDE.md や copilot-instructions.md は毎リクエスト・毎ターン自動でコンテキストに乗るため、書き方を間違えるとトークンを垂れ流す設定ファイルになる
• 「コードから分かることは書かない」「数百トークン以内に絞る」といったルールで設計すると、成功率を落とさずにコストを抑えられる
• 「設計書→コード」ではプロンプトキャッシング、「コード→設計書」ではサブエージェント分離を組み合わせると、重たいタスクでも現実的なコストに収まる(可能性がある)

---

まず「毎ターン何が起きているのか」を知る

トークンが意図せず溶けていく仕組みを理解しないと、対策が的外れになります。

LLMはステートレス

Anthropic公式ドキュメントに、こう明記されています。
（出典：Anthropic公式 — Messages APIの使用）

「Messages APIはステートレスです。つまり、常にAPIに完全な会話履歴を送信します。」

会話の「状態」をサーバーは覚えていません。あなたがターン10でメッセージを送ったとき、サーバーに届いているのはこれです。

ターン10のAPIリクエスト（実際にサーバーへ送られるもの）:
  システムプロンプト（Claude Codeの内部指示）
  + CLAUDE.md の内容            ← 毎回乗ってくる
  + ツール定義（read, bash...）  ← 毎回乗ってくる
  + ターン1のやり取り            ← 積み上がり続ける
  + ターン2のやり取り
  + ...
  + ターン9のやり取り
  + あなたの今のメッセージ       ← これだけ新規

「今のメッセージだけ送っている」わけではありません。 会話全体が毎回APIに再送 されます。
5,000トークンのCLAUDE.mdがあるとします。キャッシュを考慮しない単純計算では、20ターンのセッションでCLAUDE.md相当の内容が 5,000 × 20 = 100,000トークン分の入力になります。一言も打つ前にかかる固定コストです。

GitHub Copilotが会話履歴をどこまで再送しているかの内部仕様は公開情報だけでは断定できません。ただし、一般的なLLMエージェントと同様に、都度コンテキストを組み立てる設計である可能性は高いです。

つまり、copilot-instructions.md に1行追加するたびに、チーム全員の全リクエストのトークン消費が増える恐れがあります。

6月の料金改定後はトークン増がコストに直撃する

6月1日からGitHub Copilotのチャット・コードレビュー・エージェント機能でトークン従量課金が導入されました。
入力も出力もキャッシュも、全部トークン単位で課金されます。設定ファイルは毎リクエストに乗り続けるので無視できないコストとなります。

---

「とりあえず書けばいい」は間違い

「CLAUDE.mdやAGENTS.mdをしっかり書けばエージェントが正確に動く」というのは、2025年からAnthropicやGitHubが推奨してきた話です。
しかし、それを科学的に検証した論文が2026年の2月に発表され、複雑な結論が出ました。

ETH Zurich / LogicStar.aiのチームが、138タスク・12リポジトリ・4エージェントで比較した結果がこれです。
（出典：arXiv:2602.11988）

設定ファイルの種類	正解率への影響	コスト増
LLMが自動生成（/initなど）	平均−3%程度（タスク・エージェントによりばらつきあり）	約20%超のコスト増
人間が書いた	+4%程度の改善例もあるが不安定・一貫性なし	同上

当時 Hacker News（アメリカ版はてなブックマーク＋技術掲示板のような大手テック系サイト）でも大きな話題になったようです。特に注目されたのが「 LLM自動生成の設定ファイルは成功率を平均3%程度低下させた 」という点、そして 人間が丁寧に書いた場合でも、改善は+4%程度にとどまりコストは増加する という結果です。

また別の論文（同じETH Zurich系）では、AGENTS.mdを適切に書いたケースで実行時間の中央値が 28.64%削減 、出力トークン消費が 16.58%削減 されたという結果も出ています。
（出典：arXiv:2601.20404）

まとめると
雑に書く（/init自動生成）→ 成功率マイナス、出力トークン削減効果なし
正しく書く（人間が精査） → 実行時間短縮、出力トークン削減

「書けばいい」ではなく「 正しく書く 」ことが重要です。

※ここで紹介した論文は英文のPDFなので、Chromeの拡張機能のImmersive Translate等で翻訳しつつ確認することをおすすめします。

なぜ多すぎる設定ファイルが逆効果になるのか

olivomarco.github.io — GitHub Copilot Token Optimization Guide が4つのメカニズムで整理しており、上記arXiv論文の内容と合致しています。

① 冗長性コスト（Redundancy tax）

LLMが生成した設定ファイルには、エージェントがコードを読めば自分で発見できる内容が書いてあります。

# エージェントがpackage.jsonを読めば分かること（書く必要なし）
このプロジェクトはTypeScriptを使っています。
テストにはVitestを使っています。

ただトークンが膨れるだけで知りたい新しい情報はゼロです。価値が低い情報です。

② 注意力コスト（Attention tax）

LLMのコンテキストへの注意力は「U字型」です。先頭と末尾は読む。 中間部分は見落としがち だそうです。

200行のCLAUDE.mdを書いたとして、50〜150行目に書いたルールは無視されるかもしれません。一番守ってほしいルールほど、ファイルの中盤に書きがちではないでしょうか？それが無視される（可能性がある）のは困りますよね。

③ アンカリングの罠（Anchoring trap）

エージェントは設定ファイルの内容に過度に縛られます。論文では、設定ファイルで特定ツールに言及すると（たとえ別のツールの方がその場では適切であったとしても）そのツールの使用頻度が大幅に増加することが示されています（例：uvへの言及がある場合、タスクあたりの使用回数が約1,600%増（約17倍）に）。

④ 本質的な情報の割合の低下（Signal-to-noise ratio）

全てのトークンがモデルの注意力を奪い合います。

# ノイズ（低価値な情報）
このプロジェクトはESモジュールを使っています ← tsconfig.jsonを見れば分かる内容

# シグナル（高価値な情報）
src/auth/ は現在セキュリティ監査中のため変更禁止 ← ノイズに埋もれてしまう

では何を書けばいいのか

Google Cloud AI DirectorのAddy Osmani氏によるシンプルな基準があります。

「エージェントがコードを読めば自分で発見できる情報か？　そうなら削除」

# 残すべき情報（コードから発見できない）
- "uv を使うこと。pip は不可"
- "src/auth/ は変更禁止（セキュリティ監査中）"
- "コミット前に npm run typecheck を必ず実行"

# 削除すべき情報（コードから発見できる）
- "このプロジェクトはTypeScriptです"
- "テストにはVitestを使います"
- "非同期処理にはasync/awaitを使います"
- プロジェクトの背景・経緯

Anthropic公式も同じ方向性です。

「各行について、次のように尋ねます。「これを削除すると Claude が間違いを犯しますか？」 そうでない場合は、削除します。膨らんだ CLAUDE.md ファイルは Claude があなたの実際の指示を無視するようにします。」

（出典：Anthropic公式 — Claude Code のベストプラクティス）

Claude Code公式も『肥大化したCLAUDE.mdは無視されやすい』と警告しているため、（公式な推奨上限は存在しませんが）Xでは500トークン程度に抑えることを推奨する意見も見られます。

---

プロンプトキャッシング（Prompt Caching）の仕組みを正確に理解する

「設計書→コード」の話に入る前に、プロンプトキャッシングの 実際の仕組み を整理します。ここを誤解していると対策が的外れになります。

1回のリクエストに「キャッシュされる部分」と「キャッシュされない部分」が混在する

Anthropic公式ドキュメントに、キャッシュの対象はこう書かれています（出典：Anthropic公式 — プロンプトキャッシング）。

「プロンプトキャッシングは、cache_controlで指定されたブロックまでの、その順序でtools、system、およびmessagesを含む完全なプロンプトを参照します。」

「静的コンテンツ（ツール定義、システム指示、コンテキスト、例）をプロンプトの最初に配置します。cache_controlパラメータを使用して、キャッシング用の再利用可能なコンテンツの終わりをマークします。」

つまり 「先頭の静的な部分」 にキャッシュが効きます。

1回のリクエストの中には、「キャッシュが効く静的な部分」と「毎回フルコストで送られる動的な部分」が混在しています。境界は「内容が変わるかどうか」です。

1回のAPIリクエストの内部構造:

[キャッシュが効く部分]─────────────────────
  システムプロンプト（Claude Codeの内部指示）
  ツール定義
  CLAUDE.md の内容
  ※設計書を渡すなら冒頭のここに置く→セッション中変わらないのでキャッシュが利く
  
[キャッシュされない（またはキャッシュされづらい）部分]──────────────
  ターン1〜9のやり取り（会話履歴）
  今のメッセージ
  ※内容が変化するため、キャッシュ再利用の対象になりにくい

なぜ「CLAUDE.mdはキャッシュが効きやすく、会話履歴は効きにくい」のか。理由はシンプルで、「前のリクエストと完全に一致している部分だけキャッシュが再利用される」 からです。

• CLAUDE.mdはセッション中に書き換えない → 毎回同じ内容 → キャッシュが再利用される
• 会話履歴はターンが進むたびに内容が増える → 一致部分はあっても全体が変化するため、キャッシュ再利用の効果が限定的になる（ヒット率が下がる）

なお、ここで言う「設計書をセッション冒頭のメッセージに含める」というのは、CLAUDE.mdに設計書を書くということではありません。CLAUDE.mdはプロジェクトのルールを書く場所であり、設計書はセッション開始時の最初のユーザーメッセージに含めるのが正しい使い方です。

設計書をどこに置くかでコストが変わる、というのはこの仕組みが理由です。

設計書を「セッション冒頭（最初のメッセージ）」に置いた場合と「途中から貼った」場合で、何が起きるかを比べます。

【途中から貼った場合】

ターン1: こんにちは、認証機能を作りたいです
ターン2: 今日の作業内容を確認しました
ターン3: これが設計書です + 設計書10,000トークン  ← ここで貼る

→ 設計書は「会話履歴」の中に入る
→ ターン4以降も会話履歴の一部として保持される
→ キャッシュが効くケースもあるが、静的コンテキストとして先頭に置く場合と比べると再利用効率が下がる可能性がある

【冒頭に置いた場合】

ターン1: 以下の設計書に従って実装してください。
         ---設計書--- （10,000トークン）
         まず既存コードを確認してから実装計画を教えてください。

→ 設計書はターン1から「キャッシュが効く部分」の候補になる
→ ターン2以降、設計書部分はキャッシュ再利用の恩恵を受けやすい
→ 長いセッションほどコスト削減効果が期待できる

キャッシュの料金（Anthropic公式の数字）

トークン種別	費用
キャッシュ書き込み（初回・5分TTL）	通常入力の 125% （少し高い）
キャッシュ読み込み（2回目以降）	通常入力の 10% （大幅に安い）
出力トークン	入力の単価の 5 倍 （例：Claude Sonnet 4.6 の場合：入力 $3/MTok、出力 $15/MTok）

公式の料金体系では、キャッシュ書き込みは通常入力より高く、以後のキャッシュ読み込みはかなり安いため、再利用回数が少ない段階でも効果が出やすい設計です。

キャッシュのTTLを1時間にするオプションもあり、その場合はキャッシュ書き込み時のコストが通常入力の200%になります。

出典：Anthropic公式 — プロンプトキャッシング、Anthropic公式 — 料金

キャッシュを壊す操作（やってはいけないこと）

「前のリクエストと完全に一致している部分だけキャッシュが効く」という仕組みなので、静的なはずの部分が変わるとキャッシュが壊れます。

キャッシュが壊れる操作

• セッション途中でモデルを切り替える
• CLAUDE.mdにタイムスタンプや日付を書く（毎回変わるので当然）
• ツール定義の順番を変える
• CLAUDE.mdをメモ代わりにセッション中に書き換える

「タスク開始前に設定を固める。セッション中は変えない」が鉄則です。

---

ツールごとの設定ファイル一覧

各ツールで読まれるファイルを整理します。

ツール	設定ファイル	スコープ
Claude Code	CLAUDE.md	グローバル → プロジェクト → サブディレクトリ
GitHub Copilot	.github/copilot-instructions.md	リポジトリ全体
GitHub Copilot（細粒度）	.github/instructions/*.instructions.md	ファイルパターン指定可能
複数ツール共通	AGENTS.md	Claude CodeがCLAUDE.mdのフォールバック（代替手段）として参照する汎用フォーマット

GitHub CopilotのPrompt Engineering公式ドキュメント：

• プロンプトエンジニアリング: docs.github.com/en/copilot/concepts/prompting/prompt-engineering
• ベストプラクティス: docs.github.com/en/copilot/get-started/best-practices

正直なところ、 GitHubの公式ドキュメントはトークンコスト削減の観点が薄い のが現状です。より実践的なのはコミュニティの github/awesome-copilot や olivomarco.github.io/github-copilot-token-optimization です。

---

MCPサーバーも「毎ステップ乗り続ける」設定ファイルと同じ問題がある

CLAUDE.md や copilot-instructions.md と同じ構造の問題が、MCPサーバーにも存在します。

MCPサーバーとは

MCP（Model Context Protocol）サーバーは、AIエージェントに「外部ツールを使う能力」を追加する仕組みです。
GitHub操作・データベース・Slack・ファイルシステムなど、さまざまな機能をエージェントから呼び出せるようにします。

Claude Code や GitHub Copilot で「ツールを追加」する際に設定するのがMCPサーバーです。

なぜトークンコストに影響するのか

MCPサーバーを有効にすると、そのサーバーが持つ「ツール定義（ツール名・説明・パラメータのスキーマ）」がコンテキストに読み込まれます。
これがCLAUDE.mdと同じく、毎ステップ・毎メッセージに自動で乗り続けます。

ツール定義のトークンコスト（1ツールあたりの目安）:
  ツール名 + 説明:      20〜50トークン
  パラメータスキーマ:   30〜300トークン
  合計:                実装に強く依存（数十〜数千トークンまで幅がある）

例：よくある「全部入れてみた」構成
  15個のMCPサーバー × 平均12ツール × 200トークン
  = 1ステップあたり約36,000トークン

  エージェントタスクが15ステップ進むと
  = 540,000トークン（ツール定義だけで）

※実際のサイズはMCPサーバー実装によって大きく異なります。上記は概算イメージです。

設定ファイルと違うのは、 使っていないサーバーでも定義が乗り続ける 点です。

GitHubのMCPを有効にしたまま「認証機能を実装して」と頼むと、GitHub操作のツール定義が毎ステップ消費され続けます。

対策：使うサーバーだけ有効にする

解決策はシンプルで、「今のタスクに使わないMCPサーバーはオフにする」だけです。

Claude Codeの場合： .claude/settings.json でサーバーを管理し、タスク別に有効/無効を切り替える。

GitHub Copilot（VS Code）の場合： グローバル設定ではなくワークスペース単位（.vscode/mcp.json）で設定することで、リポジトリごとに必要なサーバーだけ読み込める。

// .vscode/mcp.json（ワークスペース単位の設定例）
{
  "servers": {
    "postgres": {
      "command": "mcp-server-postgres",
      "args": ["postgresql://localhost/mydb"]
    }
  }
}
// DBマイグレーション作業が終わったら削除またはコメントアウト

copilot-instructions.mdを必要最小限に絞るのと同じ感覚で、MCPサーバーも「今日のタスクに必要なものだけ」に絞るのが基本です。

また、 copilot-instructions.md または CLAUDE.md に以下を追加しておくと、ツール呼び出し自体の頻度も下がります。

Minimize tool calls. Read files only when necessary.

（出典：olivomarco.github.io — MCP & Tool Costs）

---

出力トークンも削れる

ここまで入力トークンの話をしてきましたが、Anthropic公式の価格表を見ると 出力トークンの単価は入力の5倍高い という構造があります（出典：Anthropic公式 — 料金）。

Claude Sonnet 4.6の場合:
  入力トークン: $3 / MTok
  出力トークン: $15 / MTok（5倍）

AIは説明が好きです。
チャット相手としてのAI（チャッピー的な使い方）ならそれで良いのですが、コード生成では困ります。
50行のコードを返すついでに、200トークンの説明文を添えてきたとしたら、それが毎回積み上がります。

解決策はシンプルで、 copilot-instructions.mdまたはCLAUDE.mdに以下を追加するだけ です。

# copilot-instructions.md / CLAUDE.md に追加（全リクエストに効く）

Be concise. No explanations unless asked.
Code only for code generation tasks.
Bullets over paragraphs.

# 日本語にすると
簡潔に。求められない限り説明は不要。
コード生成タスクについては、コードのみを記載すること。
段落よりも箇条書きを優先すること。

（出典：olivomarco.github.io — Output Control）

コード生成タスクの出力トークンが 40〜70%削減 されます（出典：同上）。一度書くだけで全リクエストに効くので、コストパフォーマンスが高い施策です。

最近ではケイブマン（原始人）プロンプト（「設計書A　コードに　しろ」のように極端に簡潔な言葉で入出力を行う手法）もトークン削減に有効とされていますが、出力された設計書まで原始人語になってしまうので注意が必要です。

---

「設計書→コード」のトークン削減

なぜ重たいか

設計書はセッション中に変わらない「静的テキスト」です。しかし配置や運用を誤ると、キャッシュ再利用効率が低下します。

10,000トークンの設計書を使って40ターンのセッションをやると、設計書だけで 400,000トークン の入力コストになります（キャッシュなしの最悪ケース）。GitHub Copilotの従量課金（Claude Sonnet 4.6ベースの場合、入力$3/MTok）で換算すると$1.20。チーム5人が毎日やると月$900の固定コストです。ただしプロンプトキャッシングを効かせれば、この設計書部分のコストが最大で1/10になることもあり得ます。

解決策①：設計書をセッションの冒頭に置く

前述のキャッシュの仕組みで説明した通り、設計書を セッションの最初のメッセージ に置くことでキャッシュが効くようになります。
（繰り返しになりますが、CLAUDE.mdに設計書を書くのではなく、セッション開始時のユーザーメッセージに含めます）

途中から貼った場合との違いを、実際のプロンプトで比べます。
（前出のプロンプトキャッシングでの説明と一部重複しますが、大事なことなので再度説明します）

コストが高いパターン（途中から貼る）

ターン1

こんにちは、認証機能を作りたいです

ターン2

今日の作業内容を確認しました

ターン3（ここで設計書を貼る）

これが設計書です。
技術スタック
- JWT: アクセストークン15分、リフレッシュトークン7日
（以下、設計書10,000トークン）

設計書がターン3の会話履歴に入ってしまいます。ターン4以降も会話履歴の一部として扱われるため、静的コンテキストとして先頭に置く場合よりキャッシュ効率が悪化する可能性があります。

コストが安いパターン（冒頭に置く）

ターン1（最初のメッセージに設計書を含める）

以下の設計書に従って認証機能を実装してください。

---設計書---
## 技術スタック
- JWT: アクセストークン15分、リフレッシュトークン7日
- bcrypt: コスト係数12
## エンドポイント
- POST /auth/login → JWTペア発行
- POST /auth/refresh → アクセストークン再発行
---

まず src/auth/ の既存コードを確認してから、実装計画を教えてください。

最初のメッセージに設計書が含まれると、キャッシュヒットしやすい構造になります。 ターン2以降は設計書部分がキャッシュから読まれ、コストが大幅に減ります。
このプロンプトはGitHub Copilot（Agent mode）でもほぼそのまま使えます。

解決策②：AIに渡す設計書を別に作る

人間向けの設計書をそのまま渡すのは非効率です。経緯・背景・将来計画は不要なトークンです。

コストが高いパターン（人間向け設計書をそのまま渡す）

# 認証機能 設計書

## 背景と経緯
2024年Q3に既存の認証システムがスケーラビリティ問題を抱えていることが判明。
Redis単体でのセッション管理がマルチリージョン展開に対応できず、
検討の結果JWTへの移行を決定した。当初はFirebase Authも候補に上がったが...
（以下500文字の経緯）

## 将来の拡張予定
フェーズ2ではSAML対応を検討。フェーズ3ではパスキー対応も視野に...

## 注意事項（READMEと重複）
このプロジェクトはTypeScriptで書かれています。テストにはVitestを...

コストが安いパターン（AI向けに作り直す）

# 認証機能 実装仕様（AI渡し用）

## スタック・設定
- JWT: アクセストークン15分 / リフレッシュトークン7日
- bcrypt: コスト係数12 / Redis: セッション管理

## エンドポイント
| メソッド | パス | 処理 |
|---|---|---|
| POST | /auth/login | JWTペア発行 |
| POST | /auth/refresh | アクセストークン再発行 |
| POST | /auth/logout | リフレッシュトークン無効化 |

## 禁止事項
- パスワードをログに出力しない
- リフレッシュトークンはHTTP-onlyクッキーのみ
- /src/auth/generated/ は変更しない（自動生成）

削ったもの：経緯・背景・将来計画・READMEと重複する情報。残したもの：今のセッションで実装するのに必要な情報だけ。こちらもClaude Code・GitHub Copilot両方で使えます。

解決策③：機能単位でセッションを分ける

大きな設計書をそのまま投げて一括実装させるのは、コンテキストを最も消費するパターンです。

プロンプト例（機能別セッション）

【セッション1: ログイン処理のみ実装】

以下の仕様「だけ」を参照して実装してください。
リフレッシュ・ログアウトは今回のスコープ外です。

---スコープ---
POST /auth/login
- リクエスト: { email: string, password: string }
- 成功: { accessToken: string, refreshToken: string }（200）
- 失敗: 401 Unauthorized / 422 バリデーションエラー
- 既存の src/middleware/auth.ts のパターンに合わせる
- テストも書く（Vitest使用）
---

実装後、npm run test:unit で確認してください。

「設計書の他のセクションは今回は参照しないでください」が重要です。これがないとCopilotが関連ファイルを広範囲に読み込もうとします。このプロンプトはClaude Code・GitHub Copilot両方で使えます。

---

「コード→設計書」のトークン削減

なぜ重たいか

こちらは逆の問題です。 コードはキャッシュも圧縮もほぼ効きません 。以前別の記事で紹介したHeadroomがコードを意図的に圧縮しない設計なのも精度が落ちるからです。

「このリポジトリから設計書を作って」という指示を出すと、エージェントは次々とファイルを読み込んでコンテキストが爆発します。

解決策：サブエージェント分離

サブエージェントはメインセッションとは独立したコンテキストウィンドウで動作します。 50ファイルを読んで途中経過を積み上げても、メインセッションには最終結果だけが返ってきます。

メインセッション（クリーンなまま）:
  あなたの指示
       ↓ サブエージェント起動
  ┌─────────────────────┐
  │ サブエージェント専用   │ ← ここに50ファイルの
  │ コンテキスト          │   探索結果が積まれる
  └─────────────────────┘
       ↓ 要約結果だけ返す
  メインセッションに追加  ← 最終結果のみ。中間過程は消える

VS Code公式ドキュメントにはサブエージェントの動作がこう書かれています（出典：VS Code Docs — Agents。これはVS Code上のCopilot Agentに関する記述ですが、コンテキスト分離という概念はClaude Codeのサブエージェント機能でも同様です）。

「Context isolation: each subagent runs in its own context window. It doesn't inherit the main agent's conversation history or instructions. It receives only the task prompt.」

「Focused results: only the final result is returned to the main agent, keeping the main context focused and reducing token usage.」

（各サブエージェントは独自のコンテキストウィンドウで実行される。メインエージェントの会話履歴や指示を引き継がず、タスクプロンプトのみを受け取る。最終結果だけがメインエージェントに返され、メインのコンテキストを集中させてトークン使用量を削減する）

Claude Codeのプロンプト例

コストが高いパターン（コンテキストが爆発する）

src/ 配下を全部読んで認証フローの設計書を作ってください

コストが安いパターン（サブエージェントを意識した指示）

src/auth/ 配下の認証フローを調査して、
以下の情報「だけ」を返してください。

1. 登場するクラスと役割（1クラス1行、最大10行）
2. ログイン処理のステップ（5ステップ以内）
3. トークンの種類と保存場所（箇条書き）

【返す際の制約】
- コードそのものは返さない
- 実装の詳細・例外処理の説明は不要
- 上記3項目に収まらない情報は省略する

この情報をもとに設計書を書くので、要約を最優先にしてください。

「コードそのものは返さない」と「上記3項目に収まらない情報は省略する」が重要です。探索の範囲は広くても、 メインに返ってくる情報量をコントロール します。
さらに、Claude Codeでの高度な使い方として、探索専用のサブエージェントをMarkdownで定義しておくこともできます。

# .claude/agents/code-analyzer.md
---
name: code-analyzer
description: コードを読んで構造情報のみを返す。コード本体は絶対に返さない
tools:
  - read
  - grep
model: claude-haiku-4-5    # 安いモデルで探索だけやらせる
---

あなたはコードの構造を分析する専門エージェントです。
返す情報は以下のみです：
- クラス名と役割の箇条書き
- 処理フローの箇条書き（5ステップ以内）
コードの引用は絶対にしないこと。

分析用サブエージェントに Haikuモデルを割り当て、メインだけOpusを使う といった組み合わせも考えられます。これはClaude Code限定の手法です。

GitHub Copilotのプロンプト例

GitHub CopilotはVS Codeのサブエージェントのような明示的な「別コンテキスト」はまだ持っていませんが、「セッションを機能ごとに分割して、要約だけをメモとして残す」ことで、実質的に同じ効果を得ることができます。

ステップ1: モジュール単位でセッションを分ける

いきなり「このリポジトリから設計書を作って」と頼むのではなく、まずはディレクトリや責務ごとに区切って会話します。

• src/auth/ だけを対象に「認証まわりの流れ」を整理する
• src/payment/ だけを対象に「決済まわりの流れ」を整理する
• src/notify/ だけを対象に「通知まわりの流れ」を整理する

この時点では、 各セッションで「全体設計書」を書かせない のがポイントです。あくまで「そのモジュールの構造と振る舞いの要約」を出してもらうだけにします。

ステップ2: Copilotに「要約だけ」出させる

各セッションでは、Copilotに対して最初から出力フォーマットをかなり絞り込んでおきます。

src/auth/ 配下だけを対象に、認証フローの概要を教えてください。

【出力条件】
1. 主なクラス / 関数と役割（1行1要素、最大10行）
2. ログイン処理のステップ（最大5ステップ）
3. トークンの種類と保存場所（箇条書き）

コード本体は引用せず、要約だけを書いてください。
それ以外の情報は省略して構いません。

こうして得られた要約は、リポジトリの notes/ 配下や docs/_generated/ などに短いMarkdownとして保存しておきます。Copilotはファイル内容をコンテキストとして読めるので、 次のセッション以降は「元コード」ではなく「要約メモ」を読ませればよい 、という状態を作れます。

ステップ3: 最後に別セッションで設計書を組み立てる

モジュールごとの要約メモが揃ったら、 別セッション でそれらだけをコンテキストに読み込ませ、全体設計書を書かせます。

以下の3つの要約Markdownだけを参照して、このシステム全体の認証・決済・通知フローの設計書を書いてください。

- notes/auth-summary.md
- notes/payment-summary.md
- notes/notify-summary.md

コードは参照しないでください。
不足している部分は「未確認」と明記して構いません。

こうすると、「コード→要約」の段階ではコンテキストが膨らんでも、その履歴は次のセッションに持ち越されません。一方で、「要約→設計書」の段階では、 コンパクトな要約ファイルだけを使って設計書を組み立てる ことができます。

---

まとめ：手法の早見表

シーン	問題	解決策	効果
設計書→コード（繰り返し）	毎ターン設計書が再送	セッション冒頭に置いてキャッシュを活かす	入力コスト大幅削減
設計書→コード（大きい）	全部渡して全部実装は重い	機能単位にセッションを分割	コンテキスト削減
コード→設計書	ファイル探索でコンテキスト爆発	サブエージェントに探索→要約だけ返す	メインコンテキストの肥大化を防ぐ
両方	設定ファイルが毎回乗る	必要最小限に絞る	毎回かかるコストを削減
両方	AIの説明文が毎回長い	"Code only"を設定ファイルに書く	出力トークン大幅削減
両方	MCPサーバーの定義が毎回乗る	使うサーバーだけ有効にする	定義コストを削減

---

さいごに

CLAUDE.mdやcopilot-instructions.mdは「書いたら終わり」になりがちですが、 毎ターン・毎リクエストに乗り続けるコスト を持つファイルです。

雑に書くと逆効果になります。Anthropic公式の言葉を借りるなら「CLAUDE.mdはコードと同様に、定期的にレビューして剪定する」が正しいアプローチです。

6月のCopilot料金改定でトークン節約の話がどこでも出ていますが、 一番効率的なのは「最初から不要なトークンを乗せない」こと です。派手なツールを使わなくても、設定ファイルの整理だけで体感できる変化があります。

今はまさにAI時代への過渡期なので、数年後に

「 そういえばあの頃トークン節約とか必死でしてたよな…原始人語でwww 」

のように笑い話になるかもしれません。

そう願いつつも今はトークンの削減に全力で取り組みましょう！

※今回の方法と併用して効果が期待できるトークン削減手法について、こちら↓の記事もご覧ください。

---

参考リンク

公式ドキュメント

• Anthropic公式 — Messages APIの使用
• Anthropic公式 — プロンプトキャッシング
• Anthropic公式 — 料金
• Anthropic公式 — Claude Code のベストプラクティス
• GitHub Blog — GitHub Copilot is moving to usage-based billing
• GitHub Docs — Models and pricing for GitHub Copilot
• GitHub Docs — Usage-based billing for individuals
• GitHub Docs — Prompt engineering for GitHub Copilot
• GitHub Docs — Best practices for using GitHub Copilot
• VS Code公式 — Agents
• GitHub Blog — Agent mode vs Coding agent

学術論文

• arXiv:2601.20404 — On the Impact of AGENTS.md Files（ETH Zurich）
• arXiv:2602.11988 — Evaluating AGENTS.md（ETH Zurich / LogicStar.ai）

実践ガイド

• olivomarco.github.io — GitHub Copilot Token Optimization Guide
• olivomarco.github.io — MCP & Tool Costs
• github/awesome-copilot