Agent Cost Report

エージェントのコストレポート

Claude-Mem / Claude Code スキル。 実行時に使うのは、scripts/ のパイプライン（トランスクリプト → トークン → 金額 → Timing 形式のレポート）と、作成したラベルを確認する段階的な Mem Search レビューパスです。Notion のドラフトは仕様の履歴にすぎず、プロダクトでも、実行時の仕組みでも、リリース手段でもありません。

この SKILL.md を含むディレクトリの絶対パスを特定してください。すべてのヘルパーパスは、そのディレクトリからの相対パスです。${CLAUDE_SKILL_DIR} はショートカットです。python3 "${CLAUDE_SKILL_DIR}/scripts/acr.py" … のように実行します。必要なのは Python 3.9 以降の標準ライブラリのみです。また、America/Los_Angeles の IANA タイムゾーンデータが必要です。pip でのインストールは不要です。pip インストール不要のルールに対する唯一の例外は tzdata です。ただし、acr.py がタイムゾーンデータを利用できないと表示して終了した場合に限ります（標準の Windows Python にはタイムゾーンデータが含まれていません）。表示された行をユーザーに見せ、インストール前に AskUserQuestion で確認してください。許可された場合は、使用しているシェルに対応する行（Bash または cmd では引用符で囲まれた通常の行、PowerShell では PowerShell: の行）を実行し、失敗したコマンドを再実行します。代わりに PYTHONTZPATH を設定する場合、インストールは不要です。見た目の設定は scripts/acr/render.py にあります。ここにはありません。

目的

Claude-Mem のアクティビティを、マネージャーが読みやすいコストと失敗のレポートにまとめます。

プロダクトの構想：再利用可能なスキルで、Mem Search を介して Claude-Mem を検索し、実際の作業単位を再構成して、コストと失敗のカテゴリを割り当て、印刷可能なレポートを生成します。

洞察の指針

見出しには、ラベル付きの金額を小数点以下 2 桁で示します。この金額は、OpenRouter の公開リスト価格で算出した Claude Code のトランスクリプト（返信ごとの正確なトークン使用量）に基づくため、推定値です。実測されたプロバイダーの支出額は、認可された情報源から得られる場合にのみ表示します。金額のすぐ下には、ミスにかかったコスト、完了した成果、そしてその両方を共通の時間軸で示します。

レポートが答えるべき質問

1. どのような作業が完了しましたか？
2. それぞれの成果にいくらかかりましたか？
3. ループ、曖昧な対応、誤った方向への進行、手戻り、不適切なルーティングによって、どれだけ無駄が発生しましたか？
4. 許可されていないアクションを試みましたか？
5. マネージャーは次に何を変更すべきですか？

主な単位 = 完了した成果あたりのコスト（観測あたりのコストではありません）。

使用するタイミング

• 「エージェントのコストレポート」「成果あたりのコスト」「失敗の経済性」「このセッションには見合う価値があったか」「今週、エージェントにいくらかかったか」
• 経営層が成果の経済性を把握する必要がある、実際の Mem セッションの調査後
• 自己完結型の HTML ＋ JSON ＋ CSV ＋証拠が必要なサンプル／リリースパック

メモリー調査の仕組み：claude-mem の mem-search スキル（段階的な想起）。

デフォルトの対象範囲（常に適用）

• ユーザーが特定のセッション／期間／プロジェクトを指定しない限り、対象期間は今日を含めず、PT で直近の完了済み 7 日間です。end = 今日の PT 午前 0 時（排他的）、start = end − 7 days です。デフォルトの期間に、日の一部が含まれることはありません（G3、Alex 2026-09-25）。
• 明示的に期間を指定する場合：--start YYYY-MM-DD --end YYYY-MM-DD（PT の暦日。終了日は排他的）。明示された --end が今日より後の場合、最終日は「一部の期間、生成時刻 HH:MM PT」と表示します。
• 1 つのセッション：--session <content_session_id>。1 つのプロジェクトと期間：--project <name> --start … --end …（そのプロジェクトのワークツリーを含みます）。
• レポートの対象範囲欄には PT の期間を表示し、詳細には対象範囲内のすべてのセッション ID を列挙します。

段階的な Mem Search（常時）

claude-mem mem-search の3層構成に従います。コストは抑えます。

1. 検索 — ID のインデックス（タイトル、種類、トークンの目安）を取得します。
2. タイムライン — 関心のあるアンカーの周辺のみを確認します。
3. 観察記録 — 証拠として引用する対象を絞り込んだ ID に対して get_observations を実行します。

手順：

1. 対象範囲を確定します（デフォルト：直近7日間の完全な PT 日）。
2. 検索して ID を収集します。
3. コンテキストが不足している場合に限り、タイムラインを確認します。
4. 意図／実際の結果／成果／無駄／手戻り／ブロック／無許可／ステータスについて観察記録を取得します。
5. 名前を付けた作業項目と失敗イベントに分類します。
6. 明細ごとのコストを計算します。
7. HTML と、必要に応じて PDF（および json/csv/evidence）を生成します。
8. 証拠 ID は付録に残します。タイムライン全体をメインレポートにそのまま載せないでください。

ADHD プロセスの箇条書き：

• まず検索 → ID を選択 → コンテキストが不足している場合に限りタイムラインを確認 → 必要な観察記録のみを取得します。
• 作業項目のタイトルは管理者向けに作成します（「Chroma のクラッシュループ後に検索を復旧」）。観察記録のタイトルは証拠としてのみ使用します。
• 証拠の付録には観察記録の ID と短いタイトルを記載し、メインセクションでは成果を先に示します。

このスキルでは、検索パスがレビュー工程です（手順4を参照）。パイプラインはキーワードからカテゴリと失敗の種類を下書きします（label_source: keyword）。オーケストレーターは、引用された証拠 ID に基づき、各明細の category と failure_type を確認または変更し、review --apply で結果を適用します。レビューされていない項目には「下書きラベル」のマークが残り、フッターに件数が表示されます。

作業カテゴリ（常時）

Feature · Bug fix · Incident · Maintenance · Investigation · Experiment

失敗／無駄の種類（常時）

Looping · Hedging · Wrong turn · Rework · Regression · Premature completion · Unauthorized action · Suboptimal path · Duplicate work · Blocked work · Missed requirement · Unnecessary escalation · Context re-read · Model thrash · Fan-out waste · Recovery after miss

手戻りのロック（常時）： 手戻りはfailure_typeのみに分類します。作業カテゴリにはしません。カテゴリには意図した作業の種類を設定し、手戻りが発生した場合はfailure_type: Reworkを設定します。

1つの明細に作業カテゴリとfailure_typeの両方を設定できます（例：Maintenance + Looping）。

コストモデル

測定トークン数は Claude Code のトランスクリプト（~/.claude/projects/**/*.jsonl、アシスタントの返信は(message.id, requestId)で重複排除）から取得します。Codex のトランスクリプトも同じ方法で読み取ります。料金には OpenRouter の公開リスト価格（100万トークンあたり）を使用し、実行時に取得してレポートとともに保存します。

agent_cost_i (per reply, micro-dollars) =
      input × price.input + output × price.output
    + cache_write_5m × price.cache_write + cache_write_1h × price.cache_write_1h
    + cache_read × price.cache_read                    # cache_write_1h = listed rate, else 2 × input

agent_estimated_usd        = Σ agent_cost_i over every reply in the window (matched or not)   # ESTIMATED, the headline
extrapolated_unmeasured    = observer tokens of sessions with no transcript here × (measured $ per observer token)
                           # EXTRAPOLATED (low confidence); "all sessions measured" when nothing remains
observer_note_taker_est    = note-taker (observer) tokens, deduped per reply, × its input list price
                           # priced separately, never agent cost, never in the headline
mistakes_estimated_usd     = Σ agent_cost_i over the same-session union of wasted turns, each turn once   # low figure
cost_per_completed_outcome = Σ attributed $ for status ∈ {shipped, completed} / count(those work items)
waste_rate                 = Σ wasted_cost / Σ attributed $     recovery_share = Σ recovery_cost / Σ attributed $

明細はセッション単位です。attributed_usd は、トランスクリプトがこのマシンにある場合は推定額、ない場合は外挿額です。wasted_cost と recovery_cost は行動分析（以下を参照）から算出し、リボン、明細、ミスの行で共通の重複なしの集合を使用します。上限（やり直しのウィンドウにプロジェクト全体へのフォールバックを加えた額）は「詳細」に記載します。

ブロックされた無許可操作： direct_cost は $0、risk_exposure は high、action_status は blocked です。実際の金銭または修復コストが発生している場合を除き、risk_exposure は常に金額以外で表します。リスク金額を決して捏造しないでください。

confidence は、トークン数、モデル、成果が明確な場合はhigh、観察記録間の割り当てに判断が必要な場合はmedium、証拠が乏しい場合はlowです。

価格が設定されていないモデル（料金リストにないモデル、または負の「変動」価格のモデル）は、名前とトークン数を記載して金額には加算しません。価格を設定せず、暗黙にゼロとして扱うことはありません。

行動指標（レビューされるまではヒューリスティック）

同じトランスクリプトに対する2回目の処理では、ユーザーの各ターンを人間／ボット／不明に分類します（中継されたエージェントのプロンプトは、Alexの発言として扱いません）。不満エピソードを特定し、Frustration Arc研究のパターン検出器を実行します。検出対象は、人間によるゲートの捏造、動作していたものの破損、不適切または高額なモデル、過剰な設計、依頼されていない作業、偽の出力、虚偽の「完了」、不適切なツールまたは連絡先、不適切な外部送信（件数 × 宛先。金額は使いません）、メモリまたはルールの喪失、専門用語、原因の不明瞭さ、およびツールエラーと曖昧な表現（Alexの定義：回答がすでに得られているのに付け加えられた但し書き）です。サマリータイルは4つで、それ以外はすべて詳細に表示します。レビューまたは分類されるまでは、すべての件数に heuristic のラベルが付きます。オプションの分類器（--classify）はデフォルトではオフで、1回の実行につき上限は$2.00です。通常の推論用 OPENROUTER_API_KEY のみを使用し、使用額は別途表示します。

金額のラベル付け（必須）

ラベル	意味
Measured	承認された情報源からプロバイダーが報告した使用額（現時点では、UTCのバケットラベルとともに表示されるOpenRouterのキー単位のスナップショット）
Estimated	測定されたトランスクリプトトークン数 × OpenRouterのMTokあたりのリスト価格（上記の計算式）
Extrapolated	このマシンにトランスクリプトがないセッションについて、オブザーバーのトークン比率から算出。常に「信頼度低」
Unavailable	測定値なし。不明な場合はmeasured spend unavailableと記載し、決して$0 spentとはしない
risk_exposure	実際の金銭的負担（シート、返金、SLA）が発生している場合を除き、深刻度／定性的な評価

各明細項目のcost_basisは、estimated_usage、measured_provider、またはextrapolatedです。金額はすべて小数点以下2桁で表示します（$109.25）。すべての数値にラベルと根拠を付けます。

明細項目のスキーマ

line-items.csv／report.json.line_itemsの各行：

フィールド	説明
work_item_id	固定ID（WI-1 …）
title	作業項目の人間向けタイトル（レビュー時には必ず考案。下書きではセッションの最初のプロンプトを使用）
scope / project / worktree	期間、セッションまたはプロジェクト、主なプロジェクト、該当する場合はワークツリー
session_ids / content_session_id	MemセッションID（複数可）とトランスクリプトの結合キー
status	shipped / completed / in_progress / abandoned / blocked
category / work_category	6つの作業カテゴリのいずれか
failure_type / failure_signals	空欄、または失敗の種類（手戻りはここに記載）
cost_measured	数値またはunavailable
cost_estimated / cost_extrapolated / attributed_usd	リスト価格による推定額、トランスクリプトがないセッションの外挿額、および使用した金額
wasted_cost / recovery_cost / productive_cost	行動の統合結果に基づく米ドル額（該当なしの場合は0）
risk_exposure	none / low / medium / high（実際の金銭的負担がない限り、金額以外の評価）
evidence_ids / summary_ids	観察とサマリーのID
agent_tokens	{input, output, cache_write_5m, cache_write_1h, cache_read}
observer_tokens	記録係のトークン数。詳細にのみ記載
model / model_prices_usd_per_mtok	主なモデルと使用した価格
cost_basis	estimated_usage / measured_provider / extrapolated
label_source	keyword（下書き）/ llm / human。reviewed_byとreviewed_at_ptを含む
device	local、remote-N、またはmacなどのエクスポートラベル
behavior_counts	このセッションでのパターン検出件数
recommended_action / confidence / date_pt / notes	改善策を1つ、信頼度（高／中／低）、PTの日付、平易な文を1つ

納品物（必須）

acr.py は、以下の内容を含むディレクトリを1つ出力します。

1. report.html — 自己完結型（CSSをインラインで記述し、スクリプトや外部リソースは使用しない）、Timingスタイル
2. report.pdf — ヘッドレスChromeを使用して report.print.html から生成（PATH上の google-chrome を使用し、ない場合はmacOSおよびWindowsのChrome標準インストール先を使用）。Chromeが見つからない場合、実行時に「PDF skipped, HTML is canonical」と表示します
3. report.json — window、scope、spend、totals、by_day、by_model、by_device、line_items、wins、behavior、timeline
4. line-items.csv — 作業項目ごとに1行
5. evidence.json — 引用された観察ID、短いタイトル、observer tokens、model、session ids
6. labels.review.json — レビューパス用のラベル案

管理者向けHTMLセクション（必須の順序）

1. ヒーロー — タグ付きの金額（ESTIMATE / MEASURED）、根拠を示す文、「完了した作業 N 件、1件あたり約 $X」、外挿した項目、該当する場合は「測定済みのプロバイダー支出：利用不可」、ストーリーを示す文（手書きではなく、計算で生成）
2. 成功と失敗 — 失敗にかかったコストの行（少額の数値）、達成した成功（マージ済みPR、公開済みバージョン、称賛。セッションがPRに紐付くまではコストを「未測定」とする）、同じPT日軸上の2つのタイムライン
3. コストリボン — すべての作業をコストに応じたサイズのブロックで表示。無駄はハッチング表示、進行中はストライプ表示
4. 支出の内訳（作業の種類別のドーナツチャート）・日ごとの内訳（積み上げ棒グラフ。空の日には「エージェントの作業なし」と表示）・有用だった割合（リングと、タイルを最大4つ表示する行動ストリップ）
5. 完了した作業 — 作業項目ごとに1行の折りたたみ表示。高額なものから順に並べ、ラベル案にはその旨を表示
6. 注目すべき点 — 最大3件、計算で生成
7. 詳細とエビデンス（折りたたみ表示。PDFでは開く）— 成功、日ごとの失敗、上限値を含む行動パターン表、ルールの有効性、支出と料金、モデル、失敗の集計、作業項目、デバイス、未照合のトランスクリプト、未価格設定のモデル、ラベル数、誠実さに関するルール、CSVとJSONへのリンク

誠実さに関する必須ルール

肯定的な事実に関するルールのみ：

1. 推定か実測かを必ず明記します（cost_basis = estimated_usage または measured_provider）。
2. 未照合の場合は、必ず測定済みの支出は利用できませんと記載します。不明な支出について「$0を支出」と記載してはいけません。
3. 必ず完了した成果を単位として使用します（完了した成果1件あたりのコスト）。
4. risk_exposure は、実際の金銭または修復コストが発生する場合を除き、必ず金額以外で表します。
5. 観察タイトルはエビデンス専用とし、人が読む作業項目のタイトルは必ず新たに付けます。
6. Mem Searchは必ず段階的に行います。エビデンスIDは付録に記載します。
7. Reworkは必ず failure_type のみに記載します。
8. ユーザーが別の範囲を指定しない限り、対象範囲は必ず直近のセッションとします。

再構築で追加された、同じ精神に基づくルール：ノート作成者のコストは別項目とし、見出しの金額には含めません。キーワードラベルはレビューされるまでは案です。Grok BotとMacの数値は「利用不可」または「外挿（信頼度低）」とし、$0や推測値にはしません。ライブデータベースは読み取り専用でのみ開きます（すべての実行はスナップショット上で行います）。

レシピ（オーケストレーター）

すべてのコマンドはスキルディレクトリから実行します。OUT は1回分の実行ディレクトリです（例：/tmp/acr-weekly/run）。各ステップは冪等です。

1. 価格 — python3 scripts/acr.py prices --out $OUT（OpenRouter のリスト価格です。オフラインで実行するには --prices <saved prices.json> を指定します。キーは不要です）。
2. 収集 — python3 scripts/acr.py collect --out $OUT（デフォルトの期間）、または … --start YYYY-MM-DD --end YYYY-MM-DD、… --session <id>、… --project <name> --start … --end …。
3. 集計 — 同じ期間フラグを指定して python3 scripts/acr.py rollup --out $OUT を実行します。report.json、line-items.csv、evidence.json、labels.review.json を出力します。オプション：--no-gh（マージ済み PR の読み取り専用確認 gh pr view をスキップ）、--classify（上記を参照）、--rules-dir <house rules>（ルールの有効性）。
4. レビュー — labels.review.json の各項目について、その evidence_ids（タイムライン全体ではありません）に対して get_observations を実行し、category、failure_type、status、タイトルを確認または変更します。reviewed_by（モデル ID または Alex）を指定してレビュー済みファイルを書き出し、python3 scripts/acr.py review --apply <reviewed.json> --out $OUT で適用します。レビューされていない項目は「draft label」のままになります。
5. レンダリング — python3 scripts/acr.py render --in $OUT/report.json --out $OUT --print。
6. PDF — python3 scripts/acr.py pdf --out $OUT（Chrome が見つからない場合はメッセージを表示してスキップされます）。
7. 任意、Alex の許可が必要 — OpenRouter の実測使用額：環境に通常の推論キーがある場合、ステップ3の前に OPENROUTER_API_KEY=… python3 scripts/acr.py measure-openrouter --out $OUT を実行します。キーがない場合、ファイルには unavailable と記載され、それ以外は変更されません。
8. 任意、Alex の許可が必要 — Mac エクスポートのマージ：python3 scripts/acr.py rollup … --device-usage <device-usage-mac.json>（「不足とゲート」を参照）。
9. 絶対パス、スキルのスラッグ agent-cost-report、ラベル付きの主要な金額、ミスの行、成果、PDF の有無、およびレポートが5つのプロダクトに関する質問にどう答えているかを返します。

ギャップとゲート

以下はそれぞれ Alex の明示的な許可が必要です。それまでは、レポートに正直なフォールバックが表示されます。

• OpenRouter キー（Alex の許可が必要） — 家の安全なシークレット管理フローを通じて環境変数として提供される、通常の推論用 OPENROUTER_API_KEY を使用します。管理キーやプロビジョニングキーは決して使用せず、設定ファイルから読み込んだり、出力に表示または書き込んだりすることもありません。キーごとのエンドポイントでは UTC の日・週・月単位のスナップショットが得られるため、数値にはバケットラベルが表示され、バケットがレポート期間全体をカバーする場合に限り、ヒーロー表示が MEASURED に切り替わります。日ごとの範囲を取得するソース（/api/v1/activity）もありますが、管理キーが必要なため実装していません（G5）。
• Mac のトランスクリプト（Alex の許可が必要） — Alex の Mac でのセッションはこのマシン上にトランスクリプトがないため、デバイスからのエクスポートをマージするまでは、コストは EXTRAPOLATED（信頼度：低）です。次のいずれかを実行してください。Alex が Mac 上で、このスキルの通常のチェックアウトから（システムの python3 3.9 以降を使用して）python3 scripts/acr.py collect --export-device mac --start YYYY-MM-DD --end YYYY-MM-DD --out ~/acr-export を実行し、~/acr-export/device-usage-mac.json（ID、タイムスタンプ、トークン数、モデル名を含み、プロンプトや観察テキスト、設定、パスは含みません）を共有します。または、特定の実行について Alex が明示的に許可した後に限り（期間、マシン、宛先を指定）、オーケストレーションを行うエージェントが、家の登録済みマシン用ツールを介して登録済みの Mac 上で同じコマンドを実行し、device-usage-mac.json のみをこのマシンにコピーします。ある実行への許可は、次の実行への許可にはなりません（G6 で対象となったのは 9 月 18～26 日のみです）。--device-usage でマージすると、結合されたセッションは device: mac を伴う estimated_usage に切り替わります。
• Grok Bot（常に利用不可、シート数なし） — Grok Bot は Cursor のクラウドエージェントです。Cursor で週ごとの使用量を確認できるのはプラン画面のみです。API もエクスポート機能もなく、家にはそのための xAI キーもありません。レポートには正確に「Grok Bot usage: unavailable」と表示されます（G4）。金額も、シートごとの価格の推測も、シート数も記載しません。Alex が手動で提示する数値は、entered_by: Alex と日付を付けて measured_manual として入力します。推測で補うことはありません。これは新たな判断となります。
• GitHub の成果（読み取り専用） — マシン上のトランスクリプトとリリース時の観察記録に加えて、rollup は --wins-repo（デフォルトは thedotmack/claude-mem）で指定されたリポジトリについて、gh pr list --state merged を使ってマージ済み PR を一覧表示します。PT 期間内のマージ時刻で絞り込み、リポジトリと PR 番号で重複を除外します。gh がない場合、未認証の場合、またはレート制限に達した場合、このソースは詳細に「利用不可」と表示されますが、レポートの生成は完了します。ゼロとして扱うことはありません。--no-gh を指定すると、すべての gh 呼び出しが無効になります。
• 成果のコスト（R4 までは未計測） — 現時点ではセッションと PR が紐付けられていないため、すべての成果に「未計測（セッションが PR に紐付けられていません）」と表示されます。コミットに Claude-Session: <content_session_id> のトレーラーが付くようになった場合（G13：トレーラーのみ、単独の ID）、PR と公開の成果に ESTIMATED · session-linked のコストが表示されます。フォールバック推定値はありません（G11）。
• main へのマージ、npm 公開、/version-bump — それぞれ Alex の個別の許可が必要です。作業ブランチへのプッシュと PR の作成は通常の作業です。

コピーを同期した状態に保つ

プラグインディレクトリが信頼できる唯一の情報源です。python3 scripts/acr.py sync-check は、SKILL.md、CHECKSUMS.txt、scripts/** を、家のコピー（~/agent-data/workflows/agent-cost-report/）および4つのミラープラグイン（claude-mem-cursor、claude-mem-grok-bot、cowork、openclaw。それぞれ skills/agent-cost-report/ の下にあります）と比較し、差異があれば終了コード 1 を返します。--write を指定すると、プラグインから各コピー先にファイルをコピーして再確認します（G2）。CHECKSUMS.txt は sha256sum -c と互換性があります。

関連項目

• claude-mem の mem-search スキル — 段階的な再呼び出し
• plans/2026-09-25-agent-cost-report-weekly.md — 再構築計画、判断事項 G1～G16、検証対象

信条

Claude-Mem スキル · まず成果 · 推定値には明示 · デフォルトでは最新を表示 · 失敗の下に手戻りを分類 · 段階的な再呼び出し · HTML を正とする · エージェントの行動とコストの理由を人が確認できること。