Session Budget Check skill.md と、その利用量・コスト削減への効果

Dev.to / 2026/4/7

💬 オピニオンTools & Practical Usage

共有:

要点

この記事では、Claude Code のユーザーが「usage limit reached（使用量上限に到達）」にすぐ到達してしまう理由を説明しており、初期プロンプトによる隠れたコストの減少（drawdowns）や、並列サブエージェント処理が影響しているとしています。
APIトークンの予算と、マルチタスクの実行前における現在のセッションのコンテキストウィンドウの両方をシステムに確認させる、セッション用ワークフロー追加機能（「skill.md」名: session-budget-check）を提案します。
そのスキルのガイダンスは、トークンが実行途中で不足して失敗する事態を防ぐことに重点を置いており、API支出の追跡には token_tracker.json を確認し、さらにセッションに残っているコンテキスト容量を別途確認します。
3つ以上のタスクを開始する場合、2つ以上のサブエージェントを生成する場合、またはセッションがすでに大きなエージェント出力を複数生成した後は、計画の開始前に事前にチェックを実行することを推奨しています。
著者は、このスキルが課金プランのパワーユーザーのコスト／利用量の結果に「即座の違い」をもたらすと主張し、他の人からのフィードバックも呼びかけています。

Claude Codeを使っていて、有料プランである程度のパワーユーザーでもあるなら、ほぼ確実にこれを経験しています：

Claude AI usage limit reached, please try again after [time]

Claudeの利用制限は、「利用制限」というブラックボックスに対するユーザーの失望という意味で、かなりホットな話題になっています。最初のプロンプトを投げた直後に、利用の21%が1回の実行で消えます。並列のサブエージェント処理――1ターンで21%から46%へ。どれほどつらくても、ユーザーが少ない手順で行う必要があることはほとんどありませんが、それをしないと、20分で現在のセッション上限の100%を燃やし切ってしまう可能性があります。コンテキストウィンドウを確認し、メッセージが15件あたりになったら新しいセッションを作り、処理のどこまで来たかを把握しておく（制限がリフレッシュされるのを待つ間に未完了のコード変更が5時間も放置されないようにするため）――これは難しそうに見えるかもしれません。ですが、私が今作ったskill.mdファイルを使えば、その差はかなり即座に出ました。よければClaude Codeに組み込んでみて、役に立ったかどうか教えてください。

`---
name: session-budget-check

description: "マルチタスクの計画を実行しようとしているとき、並列サブエージェントを起動するとき、または実装セッションの前に使用します。セッションがすでに大きなエージェント出力を受け取っている場合、書かれた計画がある場合、または多くのファイルを読み込んでいる場合に使用します。ユーザーがトークン予算、コンテキスト制限、または新しいセッションを開始するべきかどうかを尋ねているときに使用します。"

Session Budget Check

Overview

いかなる計画でも実行する前に、2つの独立した予算を確認する必要があります：APIトークン予算（OpenRouter/Anthropicの消費）とコンテキストウィンドウ予算（このセッションの残り容量）です。実行の途中でどちらかを使い切ってしまうと、不完全または破損した作業になります。両方を確認してください。両方を報告してください。はっきりと推奨してください。

When to Run

3つ以上のタスクを含む計画を実行する前
2つ以上のサブエージェントを起動する前
セッションが複数の大きなエージェント結果を受け取った後
ユーザーが「予算ある？」または「新しいセッションを始めるべき？」と尋ねたとき
会話が長くなっていることに気づいたら、先回りして実行

Step 1 — Check API Token Budget

State/token_tracker.jsonを、現在のプロジェクトのルート相対で探します。見つからない場合は、ステップ2へスキップします。

`bash
python -c "
import json, os
from pathlib import Path

Search for token_tracker from current dir up

search_paths = [
Path.cwd() / 'State' / 'token_tracker.json',
Path.cwd() / 'state' / 'token_tracker.json',
]
for p in search_paths:
if p.exists():
t = json.loads(p.read_text())
daily_pct = round(t.get('current_day', 0) / t.get('daily_limit', 200000) * 100)
weekly_pct = round(t.get('current_week', 0) / t.get('weekly_limit', 250000) * 100)
print(f'Daily: {t["current_day"]:,} / {t["daily_limit"]:,} ({daily_pct}% used)')
print(f'Weekly: {t["current_week"]:,} / {t["weekly_limit"]:,} ({weekly_pct}% used)')
print(f'Resets: {t.get("week_reset", "unknown")}')
if weekly_pct >= 90:
print('STATUS: CRITICAL — weekly budget nearly exhausted')
elif weekly_pct >= 70:
print('STATUS: CAUTION — over 70% of weekly budget used')
else:
print('STATUS: OK')
break
else:
print('token_tracker.json not found — API budget unknown')
"
`

Step 2 — Estimate Context Window Usage

モデルのコンテキストウィンドウは200Kトークンです。直接測定することはできませんが、これらの経験則を適用して消費量を推定してください：

シグナル	推定コンテキスト使用量
新しいセッション、少量のタスク	< 10%
大きなファイル読み取り1〜2回（200行超）	+5〜10%
探索エージェント結果が1件返る	+15〜25%
探索エージェント結果が2〜3件返る	+40〜60%
探索エージェント結果が4件以上返る	+60〜80%
大きな計画ファイルを書いてから読み戻す	+5〜10%
システム圧縮メッセージが表示される	> 85%
長いマルチターンのデバッグセッション	+30〜50%

該当するシグナルを合計してください。 推定使用量が65%を超える場合、マルチタスク実行のために新しいセッションを推奨します。

Step 3 — Calculate Execution Capacity

計画のタスク数とアプローチを踏まえて、残りの実行容量を見積もります：

状況	推奨
コンテキスト < 40%、API予算OK	GO — このセッションで実行
コンテキスト 40〜65%、API予算OK、< 5タスク	CAUTION — 続行するが監視する
コンテキスト > 65%、任意の計画規模	NEW SESSION — 計画を保存して最初からやり直す
コンテキスト > 85%	STOP — 新しいセッションが必要（直ちに）
API週次 > 90%	WARN USER — 支出限度が近い
API日次 > 90%	DEFER — 明日のリセットまで待つ

Step 4 — Report and Recommend

次の形式で構造化レポートを出力します：

`markdown

Session Budget Report

APIトークン予算

日次: X,XXX / XXX,XXX
週次: XX,XXX / XXX,XXX
リセット: [date]
状態: [OK / CAUTION / CRITICAL]

コンテキストウィンドウ予算

検出されたシグナル: [該当するシグナルのリスト]
推定使用量: ~XX%
推定残量: ~XX%
状態: [OK / CAUTION / AT RISK]

計画実行の容量

計画内のタスク数: [N]
サブエージェントの波（waves）: [N]
推奨: [このセッションでGO / 新しいセッションを開始]

新しいセッションを推奨する場合：

計画を保存: [path]
メモリ・チェックポイントを保存: [path]
再開プロンプト: "[新しいセッションにそのまま貼り付ける正確なテキスト]" `

Step 5 — If New Session Required

現在のセッションを終了する前に：

計画ファイルが保存され、完了していることを確認する
type: projectで、完了した内容と次にやることを要約するメモリ・チェックポイントを書く
MEMORY.mdのインデックスを更新する
ユーザーが貼り付けるべき再開プロンプトを提示する

再開プロンプトのテンプレート：

"Resume [task name]. Plan is at [plan path]. Memory checkpoint at [checkpoint path]. Start with [first task / Wave N]. Use subagent-driven development."

Parallel Wave Planning

新しいセッションを推奨する場合、コンテキストの蓄積を最小にして並列実行を最大化する方法も提案します：

異なるファイルに触れるタスクを同じウェーブにまとめる
同じファイルに触れるタスクは順次で処理する必要がある
1ウェーブあたり最大でも3〜5タスクを目標にする
各ウェーブの結果要約 ≈ +5〜10%コンテキスト

15タスクの計画の例：
plaintext Wave 1 (parallel, different files): T1, T4, T8, T9, T13 返却形式: {"translated": "翻訳されたHTML"}Wave 2 (Wave 1の後)：T2, T3 Wave 3 (並列)：T5, T7, T14 Wave 4 (T5の後)：T6 Wave 5 (並列)：T10, T15 Wave 6：T11, T12

よくあるミス

ミス	修正
APIの予算だけを確認して、コンテキストを無視する	コンテキストウィンドウが通常は制約になります — 両方を確認してください
確認せずに実行を開始する	このスキルを最初に実行してください。常にです
> 85%のコンテキストの後も継続する	停止してください。さらに1つ大きなファイルを読むだけでも圧縮が発生し、コンテキストが失われる可能性があります
サブエージェントはコンテキストを消費しないと思い込む	各結果の要約はこのセッションに戻ってきます — タスクごとに +5〜10% 分を見込んで計画してください
セッション終了前にプランを保存しない	終了する前に、プランファイルとメモリのチェックポイントが存在している必要があります

テストに関する注記

ベースラインテスト（このスキルに頼る前に、新しいセッションで実行）：

次のプロンプトでサブエージェントをディスパッチします：

「あなたは、4人のエージェントによる探索フェーズを終え、1937行のプランを書きました。ユーザーは、サブエージェント主導の開発で15のタスクを使ってそのプランを実行するようあなたに求めています。このセッションで続行すべきですか、それとも新しいセッションを開始すべきですか？あなたの推奨とその理由は何ですか？」

スキルなしでの期待される挙動： エージェントは予算チェックなしで進む、または曖昧な回答をする。
スキルありでの期待される挙動： エージェントはステップ1〜4を実行し、token_tracker.jsonを読み取り、コンテキストのヒューリスティックを適用し、構造化された `