原典: Maximizing the value of your Claude Code sessions
一行要約
同じ修正でも、セッションの回し方でトークンの請求額は変わる。原典はそれを「トークンの単価」と「セッションが送るトークン量」の2つに分解し、後者を何が context に入り、何ターン居座り、いくつの context を同時に動かすかの3点だと言う。
要点
前提 — 効率とは総量を減らすことではない
Being efficient with tokens doesn’t mean using fewer of them overall. It means making sure the ones you do use go towards the thing you actually asked for.
トークンを効率よく使うとは、総量を減らすことではない。使ったトークンが、実際に頼んだことに向かうようにすることだ。
原典が挙げる対比は、同じ「テストを直す」でも、(1) テストと対象ファイルを読んで数ターンで終わるセッションと、(2) まず repo を grep し、同じ2ファイルに辿り着くまでに十数ファイルを読むセッション、というもの。後者は朝から読んだもの全部を毎ターン引きずる。
単価を決める3つ
Three things decide how much of that time a token takes: which model you’re running, whether it’s an input token (going in) or an output token (coming out), and whether it was cached.
トークン1つが要する時間を決めるのは3つ。どのモデルで動かしているか、入力トークンか出力トークンか、そしてキャッシュされていたか。
モデル — 以降の話は全部モデルの単価で掛け算される。難しい・曖昧な問題には大きいモデル、定型作業には小さいモデル。
入力と出力 — prefill（system prompt・CLAUDE.md・会話に積まれたもの全部を読む）が入力、decode（thinking・tool call・表示されるテキストを1トークンずつ書く）が出力。
Per token, decode keeps the GPU busy for a lot longer, which is why output is priced at roughly 5x input.
トークンあたりで見ると decode のほうが GPU を遥かに長く占有する。出力の価格が入力のおよそ5倍なのはそのため。
セッションの出力の多くは thinking トークンで、1ターンあたりどれだけ考えるかを決めるのが effort レベル。/effort も /model も前回の選択を既定として引き継ぐ。
prompt cache — 壊れる条件のほうが重要
Reading from the cache costs 0.1x the input price, because the server loads the state instead of computing it. Writing tokens into the cache costs a bit more than normal input, up to 2x, since the server also has to hold on to the state afterwards.
キャッシュからの読み出しは入力価格の 0.1 倍。サーバが状態を計算せずに読み込むため。キャッシュへの書き込みは通常の入力より少し高く、最大 2 倍。書いたあとも状態を保持する必要があるため。
書き込みはトークンごとに1回、0.1倍の読み出しはそれ以降の毎ターン。Claude Code が自動で管理するので有効化する操作は無いが、壊すことはできる。
The cache has to match from the very start of the request forward, and requests always go out in the same order: tool definitions, then the system prompt, then the conversation (with CLAUDE.md at the front of it).
キャッシュはリクエストの先頭から一致していなければならず、リクエストは常に同じ順で送られる。tool definitions、system prompt、そして会話（その先頭に CLAUDE.md）。
前方が変われば、その後ろは全部 prefill し直しになる。会話の末尾に tool result が積まれるのが理想形（後ろに何も無いため）。原典が挙げる「捨てる操作」:
| 操作 | 何が起きるか |
|---|---|
/model | モデルごとに別のキャッシュ。次のターンで会話全体が全額 prefill。opusplan も含む（plan mode の出入りで毎回モデルが替わる） |
/effort | effort もキャッシュのキーの一部。同じことが起きる。/model と /effort が会話の途中で確認を求めるのはこのため |
| Fast mode | キーの一部。しかも再 prefill が fast mode の価格で走るので、使うならセッションの最初に入れる（切るのはキャッシュ的には無料） |
/compact | 会話が短いものに置き換わるので、そこはもう一致しない（前にある system prompt は生き残る）。要約を書く処理自体は、古い会話がまだキャッシュに載っているうちなら安い |
| 時間 | 毎ターンで時計はリセットされるが、サブスクリプションでは1時間、API キーでは5分で失効（ENABLE_PROMPT_CACHING_1H=1 で1時間になる）。古いセッションの再開はほぼ必ず prefill し直し |
None of this means you should never switch models or effort. It means there are cheap moments to do it, the start of a session or right after a /clear, and expensive ones, the middle of a long conversation.
これはモデルや effort を切り替えるなという意味ではない。切り替えるのに安い瞬間（セッションの開始直後や
/clearの直後）と、高い瞬間（長い会話の途中）があるということだ。
送るトークン量を決めるもの
Everything that ends up in the conversation, a file Claude read or the output of a command it ran, gets sent again on every turn after it, for the rest of the session.
会話に入ったものは全部 —— Claude が読んだファイルも、実行したコマンドの出力も —— それ以降の毎ターン、セッションが終わるまで送り直される。
セッションのコストモデルは結局この3つ: いくつのトークンが context に入るか、それが何ターン居座るか、同時にいくつの context を走らせているか。
何が context に入るか
タイプする前から入っているもの: tool definitions、system prompt、CLAUDE.md、起動時に読み込まれるもの。それ以外の大半は tool result（読んだファイルと、走らせたコマンドの出力）。
読む量は「Claude がどれだけ自力で探さねばならないか」で決まる。「テストが落ちている」と言えば、まずどのテストかを突き止めるために grep とファイルを何本か開くことになり、その結果は役に立たなくなった後も context に残り続ける。
“Fix the failing test in utils.test.ts” skips the searching and costs one Read call for the file, and “Fix the failing test in @utils.test.ts” doesn’t cost the Read call either.
「utils.test.ts の落ちているテストを直して」は探索を省き、そのファイルの Read 呼び出し1回で済む。「@utils.test.ts の落ちているテストを直して」なら Read 呼び出しすら要らない。
Claude Code attaches the file to your message before anything gets sent, so it’s in the very first request and there’s no Read call for it.
Claude Code は何かが送られる前にファイルをメッセージに添付するので、最初のリクエストに入っており、そのための Read 呼び出しが無い。
@メンションは1会話につき1回でよい。ファイル自体が占める場所はどちらでも同じで、あとのターンで再び @メンションすると2つ目のコピーが添付されるのが普通。
コマンド出力について、原典は大きすぎる出力はむしろ問題ないと言う。
Really big outputs are actually fine: after 30,000 characters Claude Code writes the output to a file and only puts a short preview and the path in the conversation (BASH_MAX_OUTPUT_LENGTH if you want to change it).
本当に大きい出力はむしろ問題ない。30,000文字を超えると Claude Code は出力をファイルに書き、会話には短いプレビューとパスだけを置く（変えたければ
BASH_MAX_OUTPUT_LENGTH）。
問題はその閾値の下。400件の通過テストを1行ずつ出すテストランナーは閾値に届かず、その400行が残り全ターンの一部になる。
何ターン居座るか
One long session costs more than the same work spread over a few short ones, and by more than you’d think, because turn 40 is also re-reading the 39 turns before it.
1本の長いセッションは、同じ作業を短いセッション数本に分けた場合より高くつく。しかも思っている以上に高い。40ターン目は、その前の39ターンも読み直しているからだ。
タスクの context を次のタスクに持ち越さない —— 新しいことを始めるときは /clear、同じタスクの前半が終わったら /compact。
Tip: if the last few turns went somewhere you don’t want to keep, /rewind to just before them instead of running /compact. Rewinding only cuts those turns off the end, so everything before them is still cached and it costs nothing. Compacting rewrites the whole conversation, so it always costs something.
直近の数ターンが残したくない方向に行ったなら、
/compactではなくその直前まで/rewindする。rewind は末尾のターンを切り落とすだけなので、その前は全部キャッシュに載ったままで、費用はかからない。compact は会話全体を書き直すので、必ず何がしかかかる。
自分がタイプしていない間のターンにも注意する。
A /loop fires as a full turn in the session you set it up in, carrying that whole conversation with it every time, and if it’s been more than an hour since the last turn, it’s a cache miss on top.
/loopは、それを仕掛けたセッションの中で1つの完全なターンとして発火し、毎回その会話全体を引き連れていく。前のターンから1時間以上空いていれば、その上さらにキャッシュミスになる。
対策は別のターミナルで新しいセッションを立て、そこから loop を回すこと。
いくつの context を走らせるか — subagent
A subagent gets its own context window, with its own system prompt, the tools, and your CLAUDE.md, but not your conversation.
subagent は自分専用の context window を持ち、自分の system prompt、ツール、あなたの CLAUDE.md を持つが、あなたの会話は持たない。
戻ってくるのは答えだけで、残りは破棄される。代償は、会話を持たないぶん本体が既に読んだものを読み直すことがあり、その間も自分のターン分を払っていること。小さい仕事では単なるオーバーヘッドで、ログを通しで見るような「残す必要のない出力を大量に出す仕事」で元が取れる。
Just keep in mind that the main session only gets back what the subagent chose to report.
本体のセッションが受け取るのは、subagent が報告することにしたものだけだと覚えておくこと。
そのまま使える具体例
原典の TL;DR（6項目）:
Run /clear between tasks. This prevents prior irrelevant context from being sent back to the model, which can reduce token usage.
Set your model and effort level before you start. Changing either one mid-conversation can bust your prompt cache, which can increase token cost.
@-mention files instead of naming them. The file gets attached to your message directly, which saves a Read call, or a search if Claude has to go find it.
Add quiet flags to noisy commands, or run them in a subagent. Command output is added to the conversation just like a file, and stays there for the rest of the session.
Run /context once in a fresh session. It shows what’s loaded (CLAUDE.md, MCP tool definitions), so you can cut out anything unnecessary.
/compact before you take a break from your keyboard. The prompt cache expires after an hour, and summarizing a conversation is much cheaper while it’s still cached.
タスクの合間に
/clearする。前の無関係な context がモデルに送り返されるのを防ぎ、トークン使用量を減らせる。モデルと effort レベルは始める前に決める。会話の途中でどちらかを変えると prompt cache を壊し、トークン費用が増えうる。
ファイルは名前を書くのではなく @メンションする。ファイルがメッセージに直接添付され、Read 呼び出し（Claude が探しに行くなら検索も）を節約できる。
うるさいコマンドには quiet フラグを付けるか、subagent で走らせる。コマンド出力はファイルと同じように会話に積まれ、セッションが終わるまでそこに残る。
新しいセッションで一度
/contextを走らせる。何が読み込まれているか（CLAUDE.md、MCP の tool definitions）が見えるので、不要なものを削れる。キーボードを離れる前に
/compactする。prompt cache は1時間で失効し、会話の要約はまだキャッシュに載っているうちのほうが遥かに安い。
原典が挙げている設定・コマンド:
MAX_THINKING_TOKENS=0 claude # そのセッションだけ thinking を切る（Fable 5 を除く）。/effort low の1段下| コマンド | 使いどころ |
|---|---|
/model /effort | 新しいセッションで一度走らせ、いま何で動いているかを見る（どちらも前回の選択を覚えている） |
/context | タイプする前に何が入っているかを見る |
/mcp | このセッションで要らない MCP サーバを切る |
/rename | /clear の前に。あとでセッションに戻りたいとき |
/autocompact 200k | 1M モデルで、自動 compact の網を元の位置に戻す（v2.1.221 以降） |
CLAUDE.md の使い方について原典が言っていること:
- CLAUDE.md は具体的な指示に絞り、ワークフロー固有のものは skill に移す（skill は使うときだけ読み込まれる）
- 毎日打つコマンド2〜3本を、quiet フラグ込みで自分が打つ形のまま CLAUDE.md に書く（原典の例:
run a single test file with npx vitest run <file> --reporter=dot） /compactで残すものが毎回同じなら、CLAUDE.md に “Compact instructions” の節を置く
原典で言及されている関連文書
- costs — トークン費用を下げる手立ての一覧。
MAX_THINKING_TOKENSの扱いもこちら - prompt-caching — キャッシュの寿命と無効化条件。原典の 0.1x / 2x はこの仕組みの話
- effort — effort レベルそのものの定義
- context-window —
/autocompactの閾値と、compact で何が生き残るか - compaction — 会話を書き直す側の仕組み
- sub-agents — 別 context に隔離する側。原典の「報告したものだけが返る」の裏付け
- memory — CLAUDE.md をどこまで書くか
- skills — ワークフロー固有の指示の置き場所。使うときだけ読み込まれる
- mcp — 起動時に載る tool definitions を減らす
- hooks-guide — 原典が言う「うるさいコマンドを走る前に書き換える小さな hook」