anytime-token-budget

name	anytime-token-budget
effort	medium
description	Trail の trail.db(session_costs/sessions)を集計し、セッション粒度の LLM コスト(token budget)レポートを前回比デルタで生成する。Opus コスト占有率・cache_read 二乗膨張・「高コスト×/compact 未使用」セッション衛生を定量化し、閾値超なら改善提案へ昇格する。「/anytime-token-budget」「token budget」「トークン予算」「LLM コスト」「Opus コスト」「セッションコスト分析」の指示、または週次スケジュールからの起動で使用する。

anytime-token-budget — LLM コストの定期分析

更新日: 2026-06-23

Trail が蓄積する trail.db を集計し、セッション粒度の LLM コストレポートを出力する。狙いは RC2（Opus メインの超長大セッションが /clear・/compact なしで継続し cache_read が「文脈サイズ×ターン数」で二乗膨張する）の継続監視。anytime-dev-health の集計レベルの cost glance と異なり、本スキルはセッション別ランキング・モデル別内訳・セッション衛生（高コスト×compact 未使用）・週次トレンドを扱う。

• 分析対象 DB（read-only）: <workspace>/.anytime/trail/db/trail.db
• 主テーブル: session_costs（session×model 別・estimated_cost_usd 算出済み）/ sessions（message_count / peak_context_tokens / compact_count / sub_agent_count / git_branch / start_time）
• 出力先: /Shared/anytime-markdown-docs/（report/_signals/token-budget/ ＝スナップショット、report/ ＝レポート、proposal/ ＝閾値超の改善提案）
• 背景: RC2 の根本原因分析は proposal/20260622-trail-data-driven-dev-improvement.ja.md、トークン削減の既往分析は report/20260619-feature-token-consumption-analysis.ja.md / proposal/20260619-token-usage-reduction.ja.md を参照。

手順

0. 前提

• DB は read-only・出力は docs のみ・自動実装/マージはしない。
• grounding は node:sqlite で完結し MCP 非依存（headless claude -p でも完走する）。
• estimated_cost_usd は推定値（サブスク枠の相対比較用）。絶対額でなく占有率・デルタ・集中度で読む。

1. grounding（決定論・LLM 不要）

スキル同梱の集計スクリプトを実行し、signals snapshot(JSON) を得て保存する。

mkdir -p /Shared/anytime-markdown-docs/report/_signals/token-budget
node .claude/skills/anytime-token-budget/grounding.cjs > /Shared/anytime-markdown-docs/report/_signals/token-budget/<YYYYMMDD>.json

• <YYYYMMDD> は snapshot の generatedAt を JST に変換した日付。保存先は初回未作成のため上記 mkdir -p で必ず先に用意する。
• DB が cwd 相対で見つからない場合は引数で明示: node .claude/skills/anytime-token-budget/grounding.cjs <workspace>/.anytime/trail/db。
• 出力の errors 配列を必ず確認する。空でなければ（スキーマ変化等でクエリが失敗している）、その旨をレポート冒頭に明記し、該当シグナルは「測定不能」として扱う（誤った 0 を真値にしない）。

2. デルタ検出（最重要）

report/_signals/token-budget/ から今回より前の最新スナップショットを 1 つ選び、主要メトリクスを今回と比較する。比較対象メトリクス:

メトリクス	源	悪化方向
Opus コスト占有率 totals.opusCostSharePct	session_costs	上昇
Opus cache_read 占有率 totals.opusCacheReadSharePct	session_costs	上昇
top15 セッションのコスト集中 totals.top15SessionsCostSharePct	session_costs	上昇
直近 7d コスト trend.last7dCost（対 prior7dCost）	session_costs+sessions	上昇
高コスト×compact 未使用 hygiene.expensiveNoCompact	join	上昇
超長大×compact 未使用 hygiene.longNoCompact	sessions	上昇
高コストセッション数 hygiene.expensiveSessions	session_costs	上昇

• 各メトリクスを 新規発生 / 悪化 / 改善 / 横ばい に分類する。
• topSessions は前回スナップショットに無い hygieneFlag='expensive-no-compact' の新規セッションを特に注視する。
• 前回スナップショットが無い（初回）場合は全メトリクスを「初期値（baseline）」として記録し、デルタ比較はスキップする。

3. レポート（常時出力）

/Shared/anytime-markdown-docs/report/<YYYYMMDD>-token-budget.ja.md を出力する。anytime-markdown-output スキルの書式（frontmatter type: report）に従う。

構成:

• frontmatter（title / date / type: report / lang: ja / author / excerpt）
• サマリ: 前回比で悪化/改善した上位シグナルを 3〜5 行（Opus 占有率・直近コスト・衛生）。
• デルタ表: メトリクス / 前回 / 今回 / 変化（↑↓→・新規）。変化があった行を上に。
• モデル別コスト内訳: byModel（model / sessions / cost / cacheRead）。Opus 比率を強調。
• コスト上位セッション: topSessions を表で（session / cost / messageCount / peakContextTokens / compactCount / gitBranch / hygieneFlag）。
• セッション衛生: hygiene（expensiveNoCompact 等）と所見。
• 週次トレンド: trend.weekly。
• grounding errors（あれば）: 測定不能だったシグナル。
• 末尾に「次アクション候補」を箇条書き（提案に昇格したものは proposal へのリンク）。

出力後 bash ~/.claude/scripts/validate-markdown.sh <file> で検証する。

4. 改善提案への昇格（閾値超のみ）

下記いずれかを満たすシグナルがあれば、anytime-proposal スキル（既定 lightweight・1 提案 = 1 論点）で改善提案を生成し proposal/<YYYYMMDD>-<topic>.ja.md に出力する。満たさなければレポートのみで終了。

昇格閾値（いずれか）:

• totals.opusCostSharePct が 90% 超かつ前回比 +3pt 以上（Opus 偏重の進行）。
• trend.last7dCost が trend.prior7dCost の +30% 以上（コスト急増）。
• hygiene.expensiveNoCompact が前回比 +5 以上、または高コストセッションの過半が compact 未使用。
• topSessions に前回スナップショットに無い hygieneFlag='expensive-no-compact' の新規セッションが出現。
• totals.top15SessionsCostSharePct が前回比 +5pt 以上（少数セッションへの集中悪化）。

提案の方向は RC2 の恒久/暫定対策（P6 モデル委譲徹底・T1 セッション衛生通知・T2 本レポート・T3 retention）に紐付ける。deep モード（anytime-proposal --deep）は複数シグナルの同時悪化時かユーザー明示時のみ。

5. ガードレール / 申し送り

• grounding が errors を返したら silent に 0 を採用しない（測定不能として明示）。
• レポートは毎回出すが、proposal は閾値超のみ（ノイズ抑制）。
• estimated_cost_usd は推定。占有率・デルタで読み、絶対額の精度を主張しない。
• DB の値は ingest ラグ（数十分〜Reload Window）を含む。直近セッションは未集計の場合がある旨をレポートに注記。
• 閾値（EXPENSIVE_COST_USD=20 / LONG_SESSION_MSGS=1000）は grounding.cjs 冒頭の定数。運用実績に応じて調整可。

スケジューラ連携（本スキルの範囲外）

本スキルはスケジューラ非依存の可搬コア。週次自動実行の配線（Desktop Scheduled Task 等）は anytime-dev-health と同じ選定論点（plan/20260622-periodic-dev-health-analysis.ja.md）に従う。手動でも /anytime-token-budget で実行できる。