Claude Code トークン最適化ガイド: /usageでコストと品質を両立する

Claude Code のトークン最適化は、単なる節約術ではありません。会話が重くなると返答が遅くなり、古い前提が混ざり、同じ説明や同じログを何度も読ませることになります。結果として、コストだけでなく、修正回数とレビュー時間も増えます。

2026年6月時点では、最初に見るべきコマンドは /usage です。公式コマンド一覧では /usage が「セッションコスト、プラン利用制限、活動統計」を表示するコマンドとして説明され、/cost と /stats はエイリアスとして扱われています。つまり /cost が完全に消えたという話ではありませんが、読者に案内する入口は /usage にそろえた方が混乱が少ないです。

この記事では、初心者でも実務に入れやすい順に「見る」「減らす」「分ける」「測る」で整理します。専門用語も最初に言い換えます。hook は「特定のタイミングで自動実行するシェル処理」、subagent は「別の会話枠で調査や作業を担当する小さなエージェント」、ハーネスは「エージェントを安全に動かす足場」です。

flowchart LR
  A["見る: /usage と /context"] --> B["減らす: CLAUDE.md と入力を整理"]
  B --> C["分ける: hooks / skills / subagents"]
  C --> D["測る: OpenTelemetry と運用ルール"]

/usageで現状を切り分ける

/usage は毎回打つものではありません。作業開始時、大きなツール実行の直後、会話が遅くなったと感じた時、別の人やエージェントへ引き継ぐ前に見ると原因を分けやすくなります。Pro、Max、Team、Enterprise では、スキル、サブエージェント、プラグイン、MCP サーバーごとの内訳も表示されます。表示はローカル履歴に基づく近似なので、他の端末や claude.ai の利用までは含みません。

特に注意したいのは、請求確認と作業改善を分けることです。/usage の Session ブロックに出る金額はローカル推定です。API 課金の実請求や管理者向けの集計は Claude Console の Usage 画面で確認します。サブスクリプション利用者は、Session cost の数字だけを見て「この金額がそのまま請求される」と判断しない方が安全です。

# Claude Code の会話欄で実行する
/usage
/context

# 会話が長くなり、判断だけ残したい時
/compact Preserve changed files, failing tests, decisions, and unresolved questions.

# 無関係なタスクへ移る時
/clear

この3つは役割が違います。/usage は使用状況の確認、/context は何が会話窓を占めているかの確認、/compact はそのセッションの作業履歴を要約して残す操作です。/clear は前の文脈を捨てて新しい作業に入るための切り替えです。最適化の最初の失敗は、この違いを理解せず、何でも CLAUDE.md に追記したり、逆に必要な決定まで /clear で消したりすることです。

毎回読む情報を小さくする

トークンは「いま入力した文章」だけで増えるわけではありません。会話履歴、CLAUDE.md、読み込ませたログ、ツール定義、テスト出力、前の調査メモも文脈になります。そこで、情報を次の3種類に分けます。

種類	置き場所	例
毎回必要	短い CLAUDE.md	ビルド、テスト、重要な禁止事項
今回だけ必要	会話と /compact	変更ファイル、失敗テスト、未解決の判断
見たら捨てる	コマンドで絞った出力	長いログ、生成差分、全件検索結果

公式の Memory ドキュメントでは、CLAUDE.md は起動時にコンテキストとして読み込まれると説明されています。長いファイルほど毎回の負担になり、200行を超えるようなファイルは追従性も落ちやすいとされています。@path で別ファイルに分けても、起動時に読み込むならトークン削減にはなりません。構造化には役立ちますが、節約目的では「常時必要か」を先に見ます。

# CLAUDE.md

## Project commands
- Build: npm run build
- Test: npm run test
- Type check: npm run typecheck

## Fast navigation
- API code: src/api/
- UI components: src/components/
- Tests: tests/

## Avoid by default
- Do not scan node_modules/, dist/, coverage/, or generated clients.
- Do not paste full logs. Ask for the failing command and the last relevant lines.

## Compact instructions
When compacting, preserve changed files, failing tests, decisions, credentials policy, and next actions.

この程度なら、毎回読み込む価値があります。反対に、PR レビュー専用の長い観点、記事翻訳の細かい表記、DB 移行だけの手順は、CLAUDE.md から外してスキルや別ドキュメントへ移します。スキルは必要になった時だけ呼び出す前提にできるため、低頻度の詳細手順と相性が良いです。

入力データを渡す前に絞る

初心者が一番コストを増やしやすいのは、ログや差分を丸ごと貼ることです。Claude Code は大量のテキストも読めますが、読む必要がない行まで渡すと、返答が遅くなり、重要なエラー行が埋もれます。減らすべきなのは証拠ではなくノイズです。

# 直近ログから対象 request_id とエラー周辺だけを渡す
tail -n 800 logs/app.log | grep -E -n -C 4 "request_id=abc123|ERROR|WARN"

# PR の全量を読ませる前に、変更ファイルと規模を見る
git diff --stat
git diff -- src/auth.ts tests/auth.test.ts

# テストの全出力を保存しつつ、Claude には失敗周辺だけ見せる
npm test 2>&1 | tee test.log
grep -E -n -C 6 "FAIL|ERROR|Error|failed|Assertion" test.log | head -160

この例はそのまま Bash で動きます。Windows の PowerShell なら grep の代わりに Select-String を使えば同じ発想で絞れます。大事なのは、後から必要になった時のために tee test.log で全文を手元へ残し、Claude へは最初から失敗周辺だけ渡すことです。

hookでうるさい出力を整える

同じフィルタを毎回手で打つなら、hook にできます。hook は便利ですが、エラーを隠すための仕組みではありません。巨大な出力を、Claude が次の判断に使える行へ縮めるための仕組みです。チーム共有前に、自分の環境で必ず確認してください。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
set -euo pipefail

input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')

case "$cmd" in
  npm\ test*|pnpm\ test*|pytest*|go\ test*)
    filtered="$cmd 2>&1 | grep -E -n -C 6 '(FAIL|ERROR|Error|failed|Assertion)' | head -160"
    jq -n --arg command "$filtered" '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "ask",
        permissionDecisionReason: "Run test command with filtered output",
        updatedInput: { command: $command }
      }
    }'
    ;;
  *)
    echo '{}'
    ;;
esac

このスクリプトは jq が必要です。permissionDecision を ask にしているので、Claude Code は変更後のコマンドをユーザーに確認します。慣れても、いきなり allow にしない方が安全です。テストが通った時の全文サマリーや exit code の扱いまで厳密にしたい場合は、ラッパースクリプトに分けて、元のログを必ずファイルへ保存する設計にしてください。

サブエージェントとスキルへ分ける

サブエージェントは、長い調査をメイン会話に残さないために使います。たとえば「公式ドキュメントを確認して、該当する変更点だけ返して」「10言語の翻訳差分を確認して、問題ファイルだけ返して」のように、成果物を短く指定します。メイン会話に返すのは、結論、変更ファイル、根拠リンク、未解決点だけです。

ただし、サブエージェントも無料ではありません。別の文脈窓を持つため、増やしすぎると合計トークンは増えます。特に複数のエージェントチームを長時間動かす場合、各メンバーが CLAUDE.md、ツール、スキル、会話履歴を持つことを忘れないでください。分ける目的は「全部を並列化すること」ではなく「メインの判断文脈を汚さないこと」です。

スキルは、低頻度だが手順が長い作業に向いています。たとえば「記事品質レビュー」「PPTX 作成」「OpenTelemetry ダッシュボード作成」などは、常時 CLAUDE.md に置くより、必要時に呼び出す形の方がトークンを節約しやすいです。毎回使う3行だけを CLAUDE.md に残し、詳細はスキルへ逃がす、という分担が現実的です。

チーム利用はOpenTelemetryで測る

個人利用なら /usage と /context で十分なことが多いです。チームで同じ作業を繰り返すなら、OpenTelemetry を使うと、コスト、入力トークン、出力トークン、キャッシュ読み取り、モデル、所要時間、ツール利用を共通の指標にできます。最初から本番の監視基盤へつなぐ必要はありません。まずは console exporter で、どんなイベントが出るかを見ます。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_LOGS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=10000
export OTEL_LOGS_EXPORT_INTERVAL=5000

claude

チームで見るべき数字は、単純な token 数だけではありません。私は「使用量」「修正回数」「検証通過」「公開後の手直し」を並べて見ます。token が三割減っても、レビュー指摘や再生成が増えたなら失敗です。Claude Code のトークン最適化は、最小 token を競うゲームではなく、同じ品質をより少ない文脈で出す運用設計です。

使えるユースケース

ログ調査

本番ログを丸ごと渡す代わりに、対象の request ID、直近の ERROR、前後数行、発生時刻、期待していた状態を渡します。Claude は「証拠」を必要としますが、「全ログ」は必要ありません。最初に80行程度で仮説を作らせ、不足したら範囲を広げる方が速く、原因もぶれにくいです。

コードレビュー

PR 全体をいきなり読ませるのではなく、git diff --stat、変更ファイル、失敗テスト、レビュー観点を渡します。セキュリティ、性能、後方互換性のように観点を分けると、同じ差分を何度も読み直す回数が減ります。レビュー結果には「根拠ファイル」「再現コマンド」「修正が必要な優先度」を必ず含めます。

多言語の記事運用

10言語の記事を一つの会話で全部持つと、後半ほど古い訳語や前の修正方針が混ざります。日本語を canonical として固定し、各ロケールは別コンテキストで自然さ、内部リンク、description、updatedDate、CTA を確認します。メイン会話へ戻すのは、変更ファイルと品質チェックだけで十分です。

研修日の同時利用

研修では、普段より多くの人が同時に Claude Code を使います。公式のコスト管理ドキュメントにも、チーム規模や同時利用を見て TPM/RPM を考える必要があると説明されています。演習前に「最初に読むファイルは5つまで」「失敗ログは最後の160行まで」「範囲を広げる前に理由を書く」というルールを配るだけで、同じ教材でも使用量が安定します。

避けたい失敗例

• /cost だけを案内する。現在は /usage を主語にし、/cost と /stats はエイリアスとして補足する方が正確です。請求額は Console 側で確認します。
• 情報を削りすぎる。再現手順、期待値、失敗コマンド、重要な決定まで削ると、Claude が前提を再発見するために余計なトークンを使います。
• CLAUDE.md を運用ノート置き場にする。毎回必要ない手順まで入れると、全セッションで払い続ける固定費になります。
• MCP サーバーを増やしすぎる。公式ドキュメントではツール定義が遅延されると説明されていますが、使わないサーバーは /mcp で見直します。gh、aws、gcloud、sentry-cli など CLI で十分な作業は CLI の方が軽い場合があります。
• hook で失敗を隠す。失敗行だけに絞るのは有効ですが、元ログを保存せずに要約だけ残すと、あとで検証不能になります。
• サブエージェントを増やせば安いと思い込む。長い出力を隔離するには有効ですが、別文脈が増える分、合計コストは増えることがあります。

小さな監査スクリプト

最後に、Claude へ渡す作業要約を作る小さな Node.js スクリプトを置いておきます。依存パッケージなしで動きます。test.log があれば失敗行だけを抜き出し、変更ファイルと diff 規模を Markdown で出します。

#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";

function git(args) {
  return execFileSync("git", args, { encoding: "utf8" }).trim();
}

const testLogPath = process.argv[2];
const changedFiles = git(["diff", "--name-only"])
  .split(/\r?\n/)
  .filter(Boolean);
const diffStat = git(["diff", "--stat"]);
const testLog = testLogPath && existsSync(testLogPath)
  ? readFileSync(testLogPath, "utf8")
  : "";
const failures = testLog
  .split(/\r?\n/)
  .filter((line) => /(FAIL|ERROR|Error|failed|Assertion)/.test(line))
  .slice(0, 80);

console.log("# Claude handoff brief\n");
console.log("## Changed files");
console.log(changedFiles.length ? changedFiles.map((file) => `- ${file}`).join("\n") : "- None");
console.log("\n## Diff stat");
console.log(diffStat || "No diff");
console.log("\n## Test failures");
console.log(failures.length ? failures.map((line) => `- ${line}`).join("\n") : "- No matching failure lines");

mkdir -p scripts
# 上の内容を scripts/claude-brief.mjs に保存した後で実行
node scripts/claude-brief.mjs test.log > claude-brief.md

この claude-brief.md を会話に貼れば、Claude は全ログや全 diff を読まずに、まず必要な範囲から判断できます。もちろん、原因特定に足りなければ追加でファイルやログを渡します。最初から全部渡さないことが大切です。

確認した公式ドキュメント

• 公式の Commands で /usage、/context、/compact、/clear の位置づけを確認しました。
• 公式の Manage costs effectively で、/usage の見方、Console での請求確認、MCP、hooks、skills、subagents、extended thinking のコスト観点を確認しました。
• 公式の How Claude remembers your project で、CLAUDE.md と auto memory の扱い、長いメモリの注意点を確認しました。
• 公式の Hooks reference と Monitoring で、PreToolUse hook と OpenTelemetry の設定を確認しました。

関連して、作業速度そのものを上げたい場合は Claude Code 速度最適化 を、権限と承認の整理は Claude Code 権限ガイド を、エージェントの足場全体は ハーネスエンジニアリングガイド を読むとつながります。

実際に試した結果

この記事の書き直しでは、同じ slug の10言語ファイルを対象に、まず日本語を canonical として整理し、/usage、CLAUDE.md、hook、OpenTelemetry、サブエージェント分担の説明を公式ドキュメントに合わせ直しました。以前のように会話へ全ログを貼る進め方ではなく、git diff --stat、失敗行の抽出、変更ファイル一覧を先に渡す形にすると、確認すべき論点が早く固まりました。

実務で一番効いたのは、CLAUDE.md を「毎回必要な短いルール」に戻すことでした。記事運用、翻訳、レビュー、公開確認を全部1つの会話へ抱え込むより、固定情報、今回の判断、一時ログを分けた方が、手戻りが少なくなります。個人で再利用できるチェックリストやプロンプトは ClaudeCodeLabの商品一覧 へ、チームで導入ルール、権限、レビュー、研修をまとめて整えたい場合は Claude Code研修・導入相談 へ進んでください。