Agent-almanac manage-token-budget

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/ja/skills/manage-token-budget" ~/.claude/skills/pjt222-agent-almanac-manage-token-budget-ac65ee && rm -rf "$T"

manifest: i18n/ja/skills/manage-token-budget/SKILL.md

source content

トークン予算の管理

サイクルごとのトークン使用量を追跡し、コンテキストスペースを消費するものを監査し、予算上限を強制し、圧力下で低価値なコンテキストをプルーニングし、完全なプロシージャをロードする前にメタデータを通じてルーティングすることで、エージェントシステムのコストとコンテキストフットプリントを制御します。核心的な原則: コンテキストウィンドウ内のすべてのトークンはその場所を正当化する必要があります。決定を情報するトークンは残り、出力に影響を与えずにスペースを占有するトークンはプルーニングされます。

コミュニティの証拠: 37時間の自律セッションが、30分のハートビートインターバルと冗長なシステム指示および未チェックのコンテキスト蓄積の組み合わせで$13.74のコストになりました。修正は、ハートビートを4時間インターバルに書き直し、通知のみモードに切り替え、ループからフィードブラウジングを排除することでした。このスキルはそのようなインシデントを防ぐパターンを体系化しています。

使用タイミング

コストが時間とともに蓄積する長時間稼働するエージェントループ（ハートビート、ポーリングサイクル、自律ワークフロー）を実行している場合
実行サイクル間でコンテキストウィンドウが予測不能に増加している場合
APIコストが予想ベースラインを超えてスパイクし、ポストモーテムが必要な場合
新しいエージェントワークフローを設計しており、最初からコストガードレールを組み込みたい場合
コストインシデント後に何が問題だったかを監査し、再発を防ぐ場合
システムプロンプト、メモリファイル、またはツールスキーマがコンテキストウィンドウを占有するほど大きくなった場合

入力

必須: 予算管理するエージェントシステムまたはワークフロー（実行中または計画中）
必須: 予算上限（期間あたりのドル金額、またはサイクルあたりのトークン制限）
任意: 現在のコストデータ（APIログ、請求ダッシュボードのエクスポート）
任意: ターゲットモデルのコンテキストウィンドウサイズ（デフォルト: モデルドキュメントを確認）
任意: 許容される劣化ポリシー（制限に達したときに何を削除できるか）

手順

ステップ1: サイクルごとのコスト追跡を確立する

すべての実行境界でトークン使用量をログに記録するようにエージェントループを計装します。

各サイクル（ハートビート、ポーリング、タスク実行）で以下を取得します：

入力トークン: システムプロンプト + メモリ + ツールスキーマ + 会話履歴 + 新しいユーザー/システムコンテンツ
出力トークン: ツール呼び出しを含むモデルのレスポンス
総コスト: 入力トークン × 入力価格 + 出力トークン × 出力価格
サイクルタイムスタンプ: サイクルが実行された時刻
サイクルトリガー: 何が開始したか（タイマー、イベント、ユーザーアクション）

これらをコンテキストウィンドウ自体ではなく構造化されたログ（JSON lines、CSV、またはデータベース）に保存します：

{"cycle": 47, "ts": "2026-03-12T14:30:00Z", "trigger": "heartbeat",
 "input_tokens": 18420, "output_tokens": 2105, "cost_usd": 0.0891,
 "cumulative_cost_usd": 3.42}

システムに計装がない場合は、API請求から推定します：

総コスト / サイクル数 = サイクルあたりの平均コスト
予想ベースライン（モデル価格 × 予想コンテキストサイズ）と比較

期待結果： サイクルごとのトークン数とコストを示すログ。どのサイクルが高コストでその理由を特定するのに十分な粒度を持つ。ログ自体はコンテキストウィンドウの外に存在する。

失敗時： 正確なトークン数が利用できない場合（一部のAPIは使用メタデータを返さない）、請求ダッシュボードを使用して平均値を導出します。大まかな追跡（1日のコスト / 1日のサイクル数）でさえトレンドを明らかにします。追跡が全くできない場合は、ステップ2に進んでコンテキスト監査から作業します — コンテキストサイズからコストを推定できます。

ステップ2: コンテキストウィンドウを監査する

コンテキストウィンドウを占有するものを測定し、サイズで消費者をランク付けします。

コンテキストをその構成要素に分解して各を測定します：

システムプロンプト: ベース指示、CLAUDE.mdコンテンツ、パーソナリティディレクティブ
メモリ: MEMORY.md、オートメモリ経由でロードされるトピックファイル
ツールスキーマ: MCPサーバーのツール定義、関数呼び出しスキーマ
スキルプロシージャ: アクティブなスキルにロードされた完全なSKILL.mdコンテンツ
会話履歴: 現在のセッションの以前のターン
動的コンテンツ: 現在のサイクルのツール出力、ファイルコンテンツ、検索結果

コンテキスト予算テーブルを作成します：

Context Budget Audit:
+------------------------+--------+------+-----------------------------------+
| Component              | Tokens | %    | Notes                             |
+------------------------+--------+------+-----------------------------------+
| System prompt          | 4,200  | 21%  | Includes CLAUDE.md chain          |
| Memory (auto-loaded)   | 3,800  | 19%  | MEMORY.md + 4 topic files         |
| Tool schemas           | 2,600  | 13%  | 3 MCP servers, 47 tools           |
| Active skill procedure | 1,900  |  9%  | Full SKILL.md loaded              |
| Conversation history   | 5,100  | 25%  | 12 prior turns                    |
| Current cycle content  | 2,400  | 12%  | Tool outputs from this cycle      |
+------------------------+--------+------+-----------------------------------+
| TOTAL                  | 20,000 | 100% | Model limit: 200,000             |
| Remaining headroom     |180,000 |      |                                   |
+------------------------+--------+------+-----------------------------------+

意思決定の価値に比べて不釣り合いに大きいコンポーネントにフラグを立てます。現在のタスクが決して参照しない4,000トークンのメモリファイルは純粋なオーバーヘッドです。

期待結果： 各コンテキスト消費者、そのサイズ、ウィンドウの割合を示すランク付けされたテーブル。少なくとも1つのコンポーネントが削減の候補として際立つ — 最も一般的なのは会話履歴または冗長なツール出力。

失敗時： コンポーネントごとの正確なトークン数の取得が難しい場合は、英語テキストの粗い近似として文字数 / 4 を使用します。構造化データ（JSON、YAML）の場合は文字数 / 3 を使用します。目標は相対的なランク付けであり、正確な測定ではありません。

ステップ3: 強制ポリシーで予算上限を設定する

ハードリミットとソフトリミットを定義し、それぞれに達したときに何が起こるかを指定します。

ソフトリミット（警告しきい値）: 通常はハードリミットの60〜75%。達したとき：
- 現在の使用量と残りの予算を含む警告をログに記録
- 最低価値コンテキストでの自発的プルーニング（ステップ4）を開始
- 該当する場合はサイクル頻度を下げる（例：ハートビートインターバルを30分から2時間に）
- 劣化したコンテキストで操作を継続
ハードリミット（停止しきい値）: 支出またはコンテキストサイズの絶対最大値。達したとき：
- 自律操作を即座に停止
- 人間のオペレーターにアラートを送信（通知、メール、ログエントリ）
- 再開のために現在の状態のサマリーを保存
- 人間がレビューして承認するまで別のサイクルを開始しない
サイクルごとの上限: 単一のサイクルの最大トークンまたはコスト。単一の暴走サイクルが予算全体を消費するのを防ぐ：
- サイクルが上限を超える場合は、ツール出力を切り捨てるか低優先度のアクションをスキップする
- ポストモーテム分析のために切り捨てをログに記録

ワークフロー設定に上限を文書化します：

token_budget:
  soft_limit_usd: 5.00        # warn and begin pruning
  hard_limit_usd: 10.00       # halt and alert
  per_cycle_cap_usd: 0.50     # max per individual cycle
  soft_limit_pct: 70           # % of context window triggering pruning
  hard_limit_pct: 90           # % of context window triggering halt
  enforcement: strict          # strict = halt on hard limit; advisory = log only
  alert_channel: notification  # how to notify the operator

期待結果： 3つのレベル（ソフト、ハード、サイクルごと）での文書化された予算上限と、それぞれの明示的な強制アクション。ポリシーは「制限に達したときに何が起こるか？」という質問に制限が到達する前に答える。

失敗時： 正確なドル制限の設定が時期尚早な場合（コストプロファイルが不明な新しいワークフロー）、コンテキストパーセンテージ制限のみから始め（ソフトを70%、ハードを90%）、24〜48時間のコスト追跡データの後にドル制限を追加します。アドバイザリモード（ログに記録するが停止しない）は較正期間中は許容されます。

ステップ4: 緊急プルーニングを実装する

制限に近づいたとき、低価値なコンテキストを体系的に削除して予算内に収まるようにします。

プルーニングの優先順位（最低価値から先に削除）：

古いツール出力: 既に行われた決定を情報した以前のサイクルの冗長な検索結果、ファイルコンテンツ、またはAPIレスポンス。決定は継続するが、証拠は削除できる。
冗長な会話ターン: 後の修正や改良によって置き換えられた初期のターン。ターン3がXを要求し、ターン7がYに改訂した場合、ターン3は冗長。
冗長なフォーマット: ツール出力のテーブル、ASCIIアート、装飾ヘッダー。出力に含まれていた内容の一行説明で要約する。
完了したサブタスクのコンテキスト: マルチステップタスクの場合、完全に完了したサブタスクのコンテキストで、出力がサマリーまたはファイルに取得されているもの。
非アクティブなスキルプロシージャ: スキルが以前のステップにロードされたが、もはや従われていない場合、その完全なプロシージャテキストは削除できる。
現在のタスクに無関係なメモリセクション: 関係のないプロジェクトや過去のセッションに関するオートロードされたメモリ。

プルーニングされた各アイテムに対して、一行のトゥームストーンを保存します：

[PRUNED: 2,400 tokens of npm audit output from cycle 12 — 3 vulnerabilities found, all patched]

トゥームストーンは約20トークンのコストがかかりますが、意思決定に関連する結論を保存します。

期待結果： プルーニング後にコンテキストウィンドウの使用量がソフトリミットを下回る。プルーニングされた各アイテムに結論を保存するトゥームストーンがある。重要な決定情報は失われない — 既に行われた決定の証拠のみ。

失敗時： 優先度レベル4までプルーニングしても使用量がソフトリミットを超えている場合、ワークフローは現在のサイクル頻度に対して根本的にコンテキストが重すぎる。人間のオペレーターにエスカレートする: 「プルーニング後にコンテキスト使用量がN%。選択肢: (a) サイクルインターバルを増やす、(b) サイクルあたりのスコープを減らす、(c) サブワークフローに分割する、(d) 高コストを受け入れる。」

ステップ5: スキルロードのためのプログレッシブディスクロージャを統合する

完全なスキルプロシージャをロードする前にレジストリメタデータを通じてルーティングする — 読み取りではなくルーティングにトークンを使用します。

パターン：

先にルーティング: タスクがスキルを必要とする場合、
```
_registry.yml
```
からスキルのレジストリエントリ（id、説明、ドメイン、複雑さ、タグ）を読む — 約3〜5行、〜50トークン
関連性の確認: レジストリの説明が現在のニーズと一致するか？一致しない場合は次の候補を確認する。これは誤ったSKILL.mdをロードするための〜500〜2000トークンの代わりにミスあたり〜50トークンのコスト
一致時にロード: レジストリエントリが関連性を確認した時のみ、完全なSKILL.mdプロシージャをロード
使用後にアンロード: スキルのプロシージャが完了した後、完全なテキストはプルーニングできる（ステップ4、優先度5）— 行われたことのサマリーのみ保持

他の大きなコンテキストペイロードに同じパターンを適用します：

メモリファイル: 先にMEMORY.mdのインデックス行を読む; トピックが関連する時のみトピックファイルをロード
ツールドキュメント: ルーティングにツール名と一行説明を使用; 呼び出されるツールにのみ完全なスキーマをロード
ファイルコンテンツ: 先にファイルリストと関数シグネチャを読む; 変更される関数にのみ完全なファイルコンテンツをロード

プログレッシブディスクロージャなし:
  5つの候補スキルをロード → 5 × 1,500トークン = 7,500トークン → 1つのスキルを使用

プログレッシブディスクロージャあり:
  5つのレジストリエントリを通じてルーティング → 5 × 50トークン = 250トークン
  1つの一致したスキルをロード → 1 × 1,500トークン = 1,500トークン
  合計: 1,750トークン（77%削減）

期待結果： スキルのロードが2フェーズパターンに従う: メタデータによる軽量ルーティング、確認された一致時のみ完全ロード。同じパターンがメモリ、ツールスキーマ、ファイルコンテンツにも適用される。

失敗時： レジストリメタデータがルーティングに不十分な場合（説明が曖昧すぎる、タグが欠落している）、プログレッシブディスクロージャを放棄するのではなくレジストリエントリを改善します。修正はより良いメタデータであり、より多くのコンテキストのロードではありません。

ステップ6: コスト意識のあるサイクルインターバルを設計する

任意のスケジュールではなく、コストデータに基づいてサイクルインターバルを設定します。

現在のサイクルインターバルでの1時間あたりのコストを計算します：
- ```
cost_per_hour = avg_cost_per_cycle × cycles_per_hour
```
- 例: 2サイクル/時間で$0.09/サイクル = $0.18/時間 = $4.32/日
予算と比較します：
- ```
hours_until_hard_limit = (hard_limit - cumulative_cost) / cost_per_hour
```
- hours_until_hard_limitが意図した実行時間より短い場合は、サイクルインターバルを延長する
最小有効インターバルを決定します：
- 監視されているシステムの変化の最速レートは何か？データソースが4時間ごとに更新される場合、30分ごとのポーリングは8サイクルのうち7つを無駄にする
- データの更新レートにサイクルインターバルを一致させる、イベントへの不安ではなく
- イベント駆動システムの場合、可能な場合はポーリングをWebhookまたはプッシュ通知に置き換える
インターバルを適用します：

変更前: 30分ハートビート、冗長な処理
  → 48サイクル/日 × $0.09/サイクル = $4.32/日

変更後: 4時間ハートビート、通知のみ
  → 6サイクル/日 × $0.04/サイクル = $0.24/日
  → 94%コスト削減

期待結果： サイクルインターバルがコストデータによって正当化され、監視されているシステムの更新レートと一致している。インターバルとコストのトレードオフが文書化されており、将来の調整にベースラインがある。

失敗時： システムが低レイテンシのレスポンスを必要とし、より長いインターバルを許容できない場合は、代わりにサイクルごとのコストを削減します（小さなシステムプロンプト、ロードされるツールスキーマの削減、要約された履歴）。予算の方程式には2つのレバーがあります: 頻度とサイクルごとのコスト。

ステップ7: 予算コントロールを検証する

すべてのコントロールが機能しており、システムが予算内で運用されていることを確認します。

追跡の検証: 3〜5サイクルを実行し、サイクルごとのログが正確なトークン数で書き込まれていることを確認
ソフトリミットテスト: 一時的にソフトリミットを下げ、警告が発動しプルーニングが始まることを確認
ハードリミットテスト: 一時的にハードリミットを下げ、システムが停止してアラートを送ることを確認
サイクルごとの上限テスト: 大きなツール出力を注入し、上限を超えるのではなく切り捨てられることを確認
プログレッシブディスクロージャテスト: スキルロードシーケンスをトレースし、完全なSKILL.mdをロードする前にレジストリを通じてルーティングすることを確認
コスト予測: 検証データから以下を予測：
- 現在の設定での1日のコスト
- 現在の消費率でハードリミットまでの日数
- 予想月間コスト

Budget Validation Report:
+-----------------------+----------+--------+
| Check                 | Expected | Actual |
+-----------------------+----------+--------+
| Per-cycle logging     | Present  |        |
| Soft limit warning    | Fires    |        |
| Hard limit halt       | Halts    |        |
| Per-cycle cap         | Truncates|        |
| Progressive disclosure| Routes   |        |
| Daily cost projection | < $X.XX  |        |
+-----------------------+----------+--------+

期待結果： 5つのコントロール（追跡、ソフトリミット、ハードリミット、サイクルごとの上限、プログレッシブディスクロージャ）すべてが機能していることが確認される。コスト予測が意図された予算内にある。

失敗時： コントロールが発動しない場合は、強制メカニズムが単に文書化されているのではなく、実際の実行ループに接続されていることを確認します。強制なしの設定は計画であり、コントロールではありません。コスト予測が予算を超える場合は、ステップ6に戻ってサイクルインターバルまたはサイクルごとのコストを調整します。

バリデーション

よくある落とし穴

コンテキストウィンドウでの追跡: サイクルごとのログを会話履歴の中に保存すると、制御しようとしているものそのものを膨らませます。外部にログを記録し（ファイル、データベース、API）、現在のサマリーのみをコンテキストに保持します。
強制なしのソフトリミット: 誰も見ない警告はコントロールではありません。ソフトリミットは可視のアクションをトリガーする必要があります — プルーニング、インターバルの延長、またはオペレーターへの通知。システムがソフトリミットを黙って超えられる場合、そうします。
データを超えたプルーニングの決定: 決定が行われる前にツール出力を削除すると情報が失われます。決定を情報した後にのみ証拠をプルーニングします。トゥームストーンパターンは証拠を削除しながら結論を保存します。
データ更新ではなく不安にサイクルインターバルを合わせる: 4時間ごとに更新されるソースを30分ごとにポーリングすると、サイクルの87.5%が無駄になります。インターバルを設定する前にデータソースの実際の更新レートを測定します。
ルーティングのために完全なスキルをロードする: 「これは正しいスキルか？」を決定するために400行のSKILL.mdを読むと、3行のレジストリエントリを読むより10〜20倍のコストがかかります。先にメタデータを通じてルーティングし、確認された一致時のみプロシージャをロードします。
システムプロンプトを無視する: システムプロンプト、CLAUDE.mdチェーン、およびオートロードされたメモリは不可視のコストです — すべてのサイクルで支払われます。48サイクル/日のループの5,000トークンのシステムプロンプトは、指示だけで1日240,000の入力トークンのコストがかかります。最初にこれらを監査してトリミングします。
人間へのエスカレーションなしの予算上限: 予算制限に達し、黙って劣化する（人間にアラートを送る代わりに）自律システムは、ダメージを蓄積する可能性があります。ハードリミットには人間の通知チャネルを含める必要があります。