HN 日本語サマリー

← 一覧へ戻る
AI・機械学習

Claude Codeセッションの価値を最大化する

Maximizing the value of your Claude Code sessions (claude.com)

282 pointsby twapi157 コメント

要約

Claude Codeセッションでトークン使用量を削減し、効率を最大化するためのヒントが紹介されています。タスク間でのクリアコマンドの使用、モデルや努力レベルの設定、ファイルのアットマーク指定、コマンドへのサイレントフラグ追加、不要なコンテキストの削除などが推奨されています。これにより、トークンあたりのコストを抑え、より価値の高い推論に集中させることができます。

全文翻訳

Claude Codeセッションの価値を最大化する方法

TL;DR

  • タスク間では/clearを実行してください。これにより、以前の無関係なコンテキストがモデルに送信されるのを防ぎ、トークン使用量を削減できます。
  • 開始前にモデルとエフォートレベルを設定してください。会話の途中でどちらかを変更すると、プロンプトキャッシュが無効になり、トークンコストが増加する可能性があります。
  • ファイル名を指定する代わりに、ファイルをアットメンション(@-mention)してください。ファイルはメッセージに直接添付され、Readコール(またはClaudeが検索する必要がある場合)を節約できます。
  • うるさいコマンドにはサイレントフラグを追加するか、サブエージェントで実行してください。コマンドの出力はファイルと同様に会話に追加され、セッションの残りの期間そこに留まります。
  • 新しいセッションでは/contextを一度実行してください。ロードされているもの(CLAUDE.md、MCPツール定義)が表示されるため、不要なものを削除できます。
  • キーボードから離れる前に/compactを実行してください。プロンプトキャッシュは1時間後に期限切れになり、キャッシュされている間は会話の要約がはるかに安価です。

価値の最大化

ごく最近まで、コードを記述するために使用していたツールは定額料金(または無料)でした。その日のテストを1つ修正したとしても、50個修正したとしても、エディタのコストは同じだったので、個々のタスクには独自の価格がありませんでした。

Claude Codeのようなエージェンティブコーディングツールでは、そうではありません。完了したタスクでも、使用方法によって異なるコストがかかる場合があります。

あるセッションでは、Claudeはテストと対象ファイルを読み込み、編集を行い、数回のターンで完了します。別のセッションでは、まずリポジトリをgrepし、同じ2つのファイルにたどり着くまでに12個のファイルを読み込み、それらの各ターンは、その日の朝から会話に追加された他のすべてのものも引きずります。

[画像: Claude Codeのセッションで、複数のファイルが読み込まれ、トークン使用量が増加している様子を示す図]

同じ修正ですが、使用したトークン数は異なり、モデルは必要のない10個のファイルを常に考慮する必要がありました。

トークンを効率的に使用することは、全体の使用量を減らすことを意味するわけではありません。それは、使用するトークンが実際に要求したことに対して確実に使われるようにすることを意味します。

したがって、トークンの価格を決定するもの、セッションが送信するトークンの数を決定するもの、そしてその過程で、セッションの実行方法にそれが何を意味するのかを見ていきましょう。

トークンの価格を決定するもの

トークンごとに請求されますが、実際に支払っているのは推論(モデルがトークンを処理するのにかかるGPU(またはTPU、またはモデルが実行されているもの)の時間)です。

トークンがどれだけ時間がかかるかを決定する3つの要因があります。実行しているモデル、それが入力トークン(入ってくる)か出力トークン(出ていく)か、そしてそれがキャッシュされたかどうかです。

モデル

より大きなモデルは、入力トークンと出力トークンの両方でより多くの作業を行います。どのモデルがどの種類の作業に適しているかは、それ自体がトピックであり、Claude CodeでClaudeモデルとエフォートレベルを選択するで説明しました。

この投稿では、これから説明するすべてがモデルの価格に掛け合わされることを知っておくだけで十分です。問題が本当に難しいか曖昧な場合はより大きなモデルを使用し、作業がルーチンである場合はより小さなモデルを使用してください。

[画像: モデルサイズとトークン処理時間の関係を示すグラフ]

曲線は説明目的のみです。実際のベンチマークデータを示すものではありません。

入力トークンと出力トークン

リクエストは2つのフェーズでGPUを通過し、それぞれコストが異なります。

まず、プリフィル中、モデルはリクエストとコンテキストを読み込みます。システムプロンプト、CLAUDE.md、メッセージ、およびそれ以降会話に追加されたすべて(Claudeが読み込んだファイルと実行したコマンドの出力)です。これらが入力トークンです。

次に、デコード中、モデルは出力トークンを書き込みます。思考、実行するツールコール、および表示されるテキストです。これは一度に1トークンずつ発生します。200トークンの応答は、モデルの実行が200回連続して行われることを意味します。トークンあたり、デコードはGPUを長時間ビジー状態にするため、出力の価格は入力の約5倍になります。

[画像: 入力トークンと出力トークンのコストの違いを示すグラフ]

セッションの出力トークンの多くは思考トークンであり、ターンあたりの思考量はエフォートレベルによって制御されます。モデルと同様に、/effortで選択したレベルは、次のセッションでもデフォルトとして維持されます。

「ヒント: 新しいセッションで/modelと/effortを一度実行して、実際に何が選択されているかを確認してください。どちらも前回選択したものを記憶しており、その決定は意図的なものであるべきです。」

「ヒント: セッションが単調な作業になるとわかっている場合は、MAX_THINKING_TOKENS=0 を設定すると、そのセッションの思考がオフになります(Fable 5を除く)。これは/effort low の下のステップです。」

プロンプトキャッシュ

リクエストが、サーバーが最近見たリクエストとまったく同じトークンで始まる場合、共有された開始部分の状態は同じになるため、サーバーはそれを以前のものから保持でき、それ以降の部分だけをプリフィルします。これはプロンプトキャッシュと呼ばれます。

キャッシュからの読み込みは、サーバーが状態を計算するのではなくロードするため、入力価格の0.1倍のコストがかかります。キャッシュへの書き込みトークンは、サーバーが状態を保持する必要もあるため、最大2倍まで、通常の入力よりも少しコストがかかります。しかし、書き込みはトークンごとに1回発生し、0.1倍の読み込みはそれ以降のすべてのターンで発生します。

Claude Codeはすべてのリクエストでプロンプトキャッシュを管理します。オンにする必要はありません。しかし、それを壊すことができるため、コストの急増を回避する方法を知ることが重要です。

utils.test.tsの失敗したテストを修正する」と入力したとしましょう。Claude Codeがそれを送信する方法は次のとおりです。

  1. Claude Codeは、システムプロンプト(ツール定義を含む)、CLAUDE.md、およびメッセージから最初のリクエストを組み立てて送信します(入力トークン)。まだキャッシュに何も入っていないため、すべてプリフィルされ、キャッシュに書き込まれます。
  2. モデルは、見ていないテストを修正できないため、しばらく考えてutils.test.tsのReadコールを返します(出力トークン)。Claude Codeはファイルを読み込み、会話に追加して、すべてを再度送信します(入力トークン)。今回は、リクエスト1のすべてが10分の1の価格でキャッシュから読み込まれ、フルプライスでプリフィルされる唯一の新しいものは、Readコールとファイルです。
  3. モデルはテスト対象のファイルを要求します(出力)。別のRead、別の追加、そしてすべてが再度送信されます。同じ話です。リクエスト1と2はキャッシュから、2番目のファイルはフルプライス(入力)で送信されます。
  4. モデルはEditを返します(出力)。Claude Codeはそれを適用し、結果を追加して、すべてを再度送信します。同じ話です。Editとその結果は新しいもので、それ以前のすべてはキャッシュ読み込み(入力)です。
  5. モデルはnpm testを実行します(出力)。Claude Codeはテスト出力を追加し、すべてを再度送信します。テスト出力が唯一新しい部分です(入力)。
  6. テストはパスし、モデルは短い要約を返します(出力)。ツールコールがないため、追加するものもリクエスト6もなく、完了です。

1回の小さな修正で5回のリクエストが発生し、それぞれがそれまでの会話全体を含んでいます。典型的なターンは不均衡です。数万トークンが入力され、数百トークンが出力されます。しかし、そのターンで新しいものだけがフルプライスでプリフィルされます。

これがターンごとの請求のすべてです。履歴のキャッシュ読み込み、新しいものに対するフル入力価格、および応答に対する出力価格です。

「これはサブスクリプションにも適用されます。これらの価格は直接表示されませんが、同じリクエストが制限を引き下げる原因となります。」

キャッシュはリクエストの最初から一致する必要があり、リクエストは常に同じ順序で送信されます。ツール定義、システムプロンプト、会話(CLAUDE.mdが先頭)です。

そのプレフィックスのいずれかが変更されると、それ以降のすべてが再度プリフィルされます。会話の最後にツール結果が追加されるのは理想的なケースです。なぜなら、それ以降に何も残らないからです。キャッシュを無効にするのは、リクエストのより前面を変更するもの、またはキャッシュのキーとなるものを変更するものです。

  • /model: 各モデルには独自のキャッシュがあるため、次のターンでは会話全体がフルプライスで再度プリフィルされます。(プランモードに出入りするたびにモデルを切り替えるopusplanも含まれます。)
  • /effort:: エフォートレベルもキャッシュのキーの一部であるため、同じ話です。そのため、どちらのコマンドも会話の途中で切り替える際に確認を求めてきます。
  • Fast mode: キーの一部でもあり、再プリフィルは高速モードの価格で行われるため、オンにする場合は最初にオンにしてください。(オフに戻すのはキャッシュ的には無料です。)
  • /compact: 会話がより短いものに置き換えられるため、その中の何も一致しなくなります(その前のシステムプロンプトは残ります)。要約自体の書き込みは、古い会話がまだキャッシュにある限り安価なので、長い休憩の前の方が後よりもはるかに安価です。
  • Time: 各ターンで時計はリセットされますが、キャッシュはサブスクリプションでは1時間、APIキーでは5分で期限切れになります(ENABLE_PROMPT_CACHING_1H=1で1時間に延長)。それ以降に戻ると、次のターンで会話全体が再度プリフィルされます。古いセッションを再開することもほとんどの場合そうなります。キャッシュは通常その時点では消えており、システムプロンプトは起動時に再構築されます。

これらのどれも、モデルやエフォートを切り替えるべきではないという意味ではありません。セッションの開始時や/clearの直後など、安価なタイミングと、長い会話の途中など、高価なタイミングがあることを意味します。

「ヒント: 直前の数ターンが望まない方向に行った場合、/compactを実行する代わりに、それらの直前に/rewindを使用してください。巻き戻しはそれらのターンを末尾からカットするだけなので、それ以前のすべてはキャッシュされており、コストはかかりません。コンパクト化は会話全体を書き直すため、常に何らかのコストがかかります。」

セッションが送信するトークン数を決定するもの

ここで知っておくべき主なことは、何も一度だけ送信されないということです。会話に最終的に含まれるもの、Claudeが読み込んだファイル、または実行したコマンドの出力は、セッションの残りの期間、それ以降の各ターンで再度送信されます。

キャッシュされるため、これらの再送信はそれぞれ安価ですが、安価でもゼロではなく、各ターンでモデルが考慮する必要のあるコンテキストのスペースを占有します。

それがセッションのコストモデル全体です。コンテキストにどれだけのトークンが含まれるか、それらがどれだけのターンそこに留まるか、そして同時にいくつのコンテキストを実行しているかです。

コンテキストに含まれるもの

コンテキストの一部は、何も入力する前にそこにあります。ツール定義、システムプロンプト、CLAUDE.md、および起動時にロードされるその他のものです。

「ヒント: 新しいセッションで/contextを実行して、何も入力する前に何が含まれているかを確認してください。CLAUDE.mdは特定の指示のために保持し、ワークフロー固有の指示はスキルに移動してください。スキルは使用時にのみロードされます。このセッションで必要のないMCPサーバーがある場合は、/mcpでオフにしてください。」

セッション中にほぼすべて追加されるものはツール結果です。Claudeが読み込んだファイルと、実行したコマンドの出力です。

Claudeがどれだけ読み込むかは、主に自分でどれだけ理解する必要があるかにかかっています。「テストが失敗している」と言うと、まずどのテストかを見つける必要があります。grepが数回、関連ファイルを見るために数個のファイルを開き、それらのすべての結果は、有用でなくなった後もコンテキストに残ります。

「utils.test.tsの失敗したテストを修正する」は検索をスキップし、ファイルに対する1回のReadコールで済みます。「@utils.test.tsの失敗したテストを修正する」はReadコールもかかりません。

[画像: ファイルの参照方法によるトークン使用量の違いを示す図]

「ヒント: ファイルを参照するときは、パスを入力する代わりにアットメンション(@-mention)してください。Claude Codeは、何も送信される前にファイルをメッセージに添付するため、最初の要求に含まれ、Readコールは発生しません。ファイル自体はどちらの場合もコンテキストで同じスペースを占めるため、会話ごとに1回だけ言及すればよく、会話中に再度アットメンションしても通常は2番目のコピーが添付されます。」

コンテキストを埋めるもう1つのものは、Claudeが実行するコマンドの出力です。テスト、ビルド、またはgit logを実行するたびに、その出力は読み込んだファイルと同様に会話に追加され、同じ数のターンだけそこに留まります。

実際には、非常に大きな出力は問題ありません。30,000文字を超えると、Claude Codeはその出力をファイルに書き込み、会話には短いプレビューとパスのみが追加されます(変更したい場合はBASH_MAX_OUTPUT_LENGTHを参照)。

問題はその下の部分です。1行ずつ400個の合格したテストを出力するテストランナーは、制限内に収まります。そして、その400行は、残りのすべてのターンの一部になります。

Claudeはしばしばフラグとtailでこれを処理してくれます。Claudeに任せたくない場合は、実行前にうるさいコマンドを書き直すドキュメントの小さなフックがあり、重要な行だけが返されるようになります。

「ヒント: 1日中実行する2〜3個のコマンドを、サイレントフラグを含めて、自分で入力する形式でCLAUDE.mdに入れてください(例:「run a single test file with npx vitest run <file> --reporter=dot」)。これは小さな追加ですが、それ以降のすべてのセッションで1ターンと数百行の出力を節約できます。」

それがどれだけのターン留まるか

1回の長いセッションは、同じ作業を数回の短いセッションに分散した場合よりも多くのコストがかかります。そして、予想以上に多くのコストがかかるのは、40ターン目も前の39ターンを再読み込みするためです。セッションのコンテキストを短く関連性の高いものにしたいので、あるタスクのコンテキストを次のタスクに引き継がないでください。新しいことを始める際には/clearを実行し、同じタスクの前の部分が完了したら/compactを実行してください。

[画像: 会話の長さとトークン使用量の関係を示すグラフ]

「ヒント: 後でセッションを再利用したい場合は、/clearする前に/renameしてください。/compactするときは、何を保持するかを指定するか、常に同じ内容であればCLAUDE.mdに「Compact instructions」セクションを設けてください。そして、1Mモデルを使用しており、以前あった自動コンパクト化のセーフティネットを希望する場合は、/autocompact 200kを実行してください(Claude Code v2.1.221+が必要です)。」

入力していない間に発生するターンにも注意してください。/loopは、設定したセッションで完全なターンとして発火し、その会話全体を毎回引き連れます。最後のターンから1時間以上経過している場合、さらにキャッシュミスが発生します。別のターミナルで新しいセッションを開始し、そこからループを実行してください。

サブエージェント

コンテキストから何かを除外するもう1つの方法は、それを別のコンテキストで実行することです。それがサブエージェントの目的です。サブエージェントは、独自のコンテキストウィンドウ、システムプロンプト、ツール、およびCLAUDE.mdを持ちますが、会話は持ちません。独自のターンを実行し、メインセッションに戻ってくるのはその回答だけです。完了すると、他のすべては破棄されます。

会話を持たないことの欠点は、サブエージェントがメインセッションがすでに持っていたものを再読み込みする必要がある場合があり、そのターンごとに独自のコストを支払うことです。小さなジョブでは、単なるオーバーヘッドです。

ログの処理など、保持する必要のない大量の出力が発生するジョブでは、これは価値があります。Claudeはしばしばそのような処理のためにサブエージェントを自動的に使用します。また、そうしない場合は直接依頼することもできます(「このログをサブエージェントで処理して」)。メインセッションには、サブエージェントが報告することを選択したものだけが返されることを覚えておいてください。

[画像: サブエージェントの使用例を示す図]

「ヒント: 何度も引き渡すうるさいジョブがある場合は、モデルをhaiku(またはsonnet)に設定した独自のサブエージェント定義を与えてください。そうしないと、メインセッションと同じモデルで実行されます。」

最初に確認すべき場所

上記のすべての中で、コストの順におおよそ4つの項目に注意を払う価値があります。

[画像: トークン使用量に影響を与える主要な要因のリストと相対的なコストを示す図]