ClaudeCodeSDKでAPI破産を防ぐために知っておきたいこと

はじめに

この記事は、筆者が実際にClaudeCodeSDKを使用中に遭遇した異常なトークン消費問題（数時間で$126.58のコスト発生）について、その原因分析と対策をまとめたものです。

記事の信頼性について

• 実データベース: ccusageツールの出力、セッションファイルの内容など、すべて実際のデータを使用
• 推理部分の明示: 再帰呼び出しのメカニズムについては状況証拠に基づく分析です
• 安全性重視: 問題の再現実験は行わず、既存データの分析のみで検証

---

突然の利用制限到達 - 何が起こったのか？

「なんだこれ...」

Aくんは画面に表示されたメッセージを何度も読み返した。いつものようにClaudeCodeを使って開発を進めていたはずなのに、突然こんな表示が出てきたのだ。

⎿ Claude usage limit reached. Your limit will reset at 1pm
(Asia/Tokyo).

「利用制限に到達って...そんなにたくさん使った覚えはないんだけどなぁ」

美咲がAくんの後ろからそっと覗き込む。

「先輩、それってどういう意味ですか？」

「うーん、簡単に言うとClaudeの使いすぎで一時的に利用停止になったってことかな。でも僕、普通に記事評価システムのコードを書いてもらってただけなのに...」

結愛がコーヒーカップを持ちながら近づいてくる。

「何騒いでるの？また何か新しいツールに手を出して失敗した？」

「そうじゃないよ！ClaudeCodeSDKを使った記事評価システムを作ってて、普通に開発してただけなんだ。それなのに突然利用制限に引っかかって...」

「SDK？」美咲が首をかしげる。「それって何ですか？」

Aくんが振り返る。「ClaudeCodeSDKは、ClaudeCodeをPythonから制御できるライブラリなんだ。例えばこんな感じで使える」

from claude_code_sdk import query, ClaudeCodeOptions, AssistantMessage, TextBlock

# Simple query
async for message in query(prompt="Hello Claude"):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(block.text)

https://github.com/anthropics/claude-code-sdk-python

「なるほど、プログラムからClaudeCodeを操作できるんですね！」

「そう。それで記事の品質評価とかファクトチェックを自動化しようと思ってたんだ。でも...」

結愛が眉をひそめる。「それで利用制限？普通そんなことある？」

「それが僕も分からなくて。でも実際に調べてみたら、とんでもないことが分かったんだ」

異常なトークン消費の発覚

Aくんは別のターミナルを開いて、ccusage dailyと入力した。

「え、まって...これヤバくない？」

画面に表示されたレポートを見て、美咲が驚く。

「2025年7月10日のところ、Cost (USD)が$126.58って書いてありますよ！」

「そうなんだ。僕はClaudeのProプラン（月額20ドル）で契約してる。定額制だからコストを気にしたことなかったんだけど...」

結愛がレポートをじっと見つめる。「Total Tokensも異常ね。134,305,101トークンって...普通じゃない」

「もしこれが従量課金だったら、その日だけで126.58ドルかかってたってことですか？」美咲の声が震える。

「そういうことになる。月額20ドルのつもりが、一日で126ドル使ってたかもしれないってことだ」

「ちょっと待って」結愛が腕を組む。「SDK使っただけでそんなことになる？何か特別なことした？」

異常事態の始まり

「それがね...」Aくんが画面をスクロールして前日のデータを指す。「7月9日までは普通なんだ。$18.33で、確かにいつもより多いけど許容範囲。でも10日になった途端に$126.58に跳ね上がってる」

美咲が興味深そうにデータを見る。「Cache Createの数値も桁違いですね。24,395,219って...何をしたんですか？」

「記事評価システムの実装とテストをClaudeCodeにお願いしただけなんだ。auto-acceptモードにしてたから、テストも自動で実行されてたけど...」

結愛が何かに気づいたような表情を見せる。

「まさか...」

「何？何か心当たりがある？」

「ClaudeCodeとSDK、同じプロジェクトで動かしてた？」

「うん、もちろん。効率的だと思って同じディレクトリで...」

結愛が深いため息をつく。

「それが原因かもしれない。何かの無限ループが発生した可能性があるわ」

無限ループの可能性

「無限ループ？」美咲が聞き返す。

「ClaudeCodeがSDKを実行して、そのSDKが何らかの理由でまたClaudeCodeを呼び出して...もしかして循環してしまったのかも」

Aくんの顔が青ざめる。

「そんなことって...本当に起こるの？」

「まだ推測だけど、auto-acceptモードなら人間の確認なしにどんどん実行し続けるでしょ？もし終了条件がなかったら...」

「確かに...僕はテスト実行も含めて全部自動でやってもらってた」

美咲が不安そうに呟く。

「でも、これって他の人にも起こりうることですよね...？」

「可能性はあるわね」結愛が考え込む。「ただ、まだ仮説の段階だから、詳しく調べてみないと分からない」

「まず、なぜそんな循環が起こるのか、仕組みを理解する必要があるわね」

Aくんが決意を固める。

「よし、徹底的に調べてみよう。この問題を理解して、みんなが同じ轍を踏まないようにしなければ」

「そうですね！私も手伝います」美咲が元気よく答える。

結愛も小さく頷く。

「...まあ、面白そうだから付き合ってあげる」

調査の方針

「ただし」結愛が注意を促す。「再現実験は絶対にやっちゃダメよ。また同じことが起こったら、今度こそ本当に大変なことになる」

「そうですね。理論的な分析から始めましょう」

「まずはClaudeCodeとSDKがどういう関係にあるのか、そこから調べてみましょう」美咲が提案する。

Aくんが頷く。

「SDKがどうやってClaudeCodeと連携するのか、その仕組みが分かれば、なぜ無限ループが起こったのかも見えてくるかもしれない」

こうして、ClaudeCodeSDKで発生した謎の大量トークン消費の調査が始まった。三人はまず、ClaudeCodeとSDKの関係性について詳しく調べることから始めることにした。

再帰呼び出しの謎 - AIが自分自身を呼び出している？

「ClaudeCodeとSDKの関係を調べてみたんだけど...」結愛がラップトップの画面を二人に見せる。

美咲が興味深そうに覗き込む。

「何が分かったんですか？」

「ClaudeCodeSDKは、実際にはClaudeCode APIを内部で呼び出すラッパーなのよ」

SDKの正体とトークン消費の問題

結愛が図を描きながら説明する。

「つまり、こういう構造になってる：」

User → ClaudeCode → SDK → ClaudeCode API

美咲が疑問を投げかける。

「でも、なんでそんな無限ループみたいなことが起こるんでしょう？普通ならSDKの結果って、ClaudeCodeに影響しないものじゃないですか？」

結愛が鋭い指摘をする。

「そうよね。もしSDKとClaudeCodeが完全に別々のセッションを使っていたら、こんな問題は起こらないはず...」

Aくんが困惑する。

「えーっと...」

「Aくん、SDKを実装するとき、何か特別な設定をした？セッション関連のオプションとか」結愛が探るように聞く。

Aくんは腕を組んで考え込む。

「うーん...最初はうまく動いていたような気がするんだけど...」

「最初はうまく動いていた？」美咲が聞き返す。「ということは、途中で何か変更したってことですか？」

Aくんの表情が変わる。

「あ！そうだ！最初は何も設定しないで使ってたんだ」

結愛が理解する。

「つまり、毎回新しいセッションでAPIを呼び出していた、と」

「そう！そのときは問題なく動いてた。でも...」Aくんが思い出しながら続ける。

「記事評価システムで、ファクトチェック、品質評価、SEO評価の3つの処理をするとき、すごくトークンを食ってることに気づいたんだ」

美咲が促す。

「どのくらい？」

セッション共有なし:
ファクトチェック: 記事全文(10,000文字) + プロンプト → 結果
品質評価: 記事全文(10,000文字) + プロンプト → 結果  
SEO評価: 記事全文(10,000文字) + プロンプト → 結果
合計: 30,000文字分のトークン

「それで、トークンを節約する方法を調べたら、セッション共有という方法があることを知って...」

結愛が重要な点を聞く。

「それで、セッション共有を有効にしたのね」

「そう」Aくんが頷く。「効率的だと思って」

美咲が詳細を求める。

「セッション共有を有効にするとどうなるんですか？」

from claude_code_sdk import query, ClaudeCodeOptions

# セッションを共有する設定
options = ClaudeCodeOptions(
    continue_conversation=True
)

async for message in query(prompt="記事を評価して", options=options):
    print(message)

「こうすると、同じセッション情報を使い回せるから：」

セッション共有あり:
最初だけ: 記事全文(10,000文字) + プロンプト → 結果
2回目以降: プロンプトのみ → 結果（記事は既にセッションに含まれている）
合計: 10,000文字分のトークン（3分の1に削減！）

結愛が眉をひそめる。

「ちょっと待って...」

美咲も気づき始める。

「あれ？セッションが共有されてるってことは...」

効率化が招いた罠

「3分の1にトークンを削減できたから、良いアイデアだと思ったんだけど...」Aくんが不安そうに言う。

「でも」結愛が重要な点に気づく。「もしClaudeCodeがSDKを実行すると...」

美咲が理解し始める。

「セッションが共有されてるから、SDKの結果がClaudeCodeに直接影響する？」

「まさにそれよ！」結愛が興奮する。

セッション共有なしの場合：

ClaudeCode → SDK → 処理結果 → Pythonスクリプト（終了）

セッション共有ありの場合：

ClaudeCode → SDK → 処理結果 → ClaudeCode（新しいユーザー指示だと誤認識）
     ↑                              ↓
     ←←←← 新しい指示 ←←←←←←←←←←←←←

「つまり、セッション共有があると、SDKの出力結果をClaudeCodeが『ユーザーからの新しいタスク』として認識してしまう！」

美咲が理解する。

「それで、auto-acceptモードだから人間の確認なしに新しいタスクを自動開始しちゃうんですね」

「その通り。効率化のためのセッション共有が、結果的に再帰呼び出しを可能にしてしまった」

問題の核心発見

Aくんが愕然とする。

「ということは...僕がセッション共有を有効にしたことで、再帰呼び出しが可能になってしまったってことか？」

「そういうこと」結愛が確信を持って答える。「セッション共有なしなら、SDKの結果はClaudeCodeに直接影響しない。でもセッション共有ありだと...」

美咲が理解する。

「出力がそのまま入力に繋がっちゃうんですね！」

「まさに電子回路の正帰還ループよ。効率化のつもりが、とんでもない罠だった」

条件の整理

結愛が状況を整理する。

「つまり、以下の条件が揃って初めて問題が発生する：」

1. セッション共有の有効化（continue_conversation=True）
2. auto-acceptモードの使用
3. ClaudeCodeからのSDK実行
4. 人間の監視不足

「これらが全て揃うケースは珍しいから、今まで大きな問題になってこなかった」

Aくんが苦笑いする。

「僕は運悪く、全ての条件を満たしてしまったわけか...」

証拠の必要性

「でも」結愛が慎重に言う。「まだ理論の段階。本当にこれが原因かどうか、証拠で確認する必要がある」

「どうやって確認するんですか？」美咲が聞く。

「ClaudeCodeはセッション情報をローカルファイルに保存してる。そのファイルを分析すれば、実際に再帰呼び出しが発生したかどうか分かるはず」

Aくんが前向きになる。

「そうだね。推理だけじゃなくて、実際のデータで証明しよう」

「ただし」結愛が警告する。「もしこの仮説が正しければ、同じような状況にある他の開発者にも、同じリスクがある。これは個人の問題じゃなくて、コミュニティ全体の問題よ」

美咲が決意を示す。

「だからこそ、しっかり調べて、みんなに共有しないといけませんね」

三人は、セッション共有という「効率化」が意図しない再帰呼び出しを引き起こす可能性があることを理解した。次は、実際のセッション情報を分析して、この仮説を証明する番だった。

証拠を探せ - セッション情報からの推理

「それじゃあ、実際にセッション情報を見てみましょう」結愛がターミナルを開く。

Aくんが問題のディレクトリに移動する。

「あったあった。これが問題の日のセッションファイルだ」

du -h ~/.claude/projects/-Users-user-projects-article-eval-system/* | sort -hr | head -5
1.8M    006ba999-5d87-45e9-8bd4-01362786f2fe.jsonl
308K    cf35f4ed-bf65-4eb1-84a4-60743d93f688.jsonl
268K    931377ed-c748-46ff-a8c8-c841550cfd62.jsonl
260K    1a58876f-1a6d-4cd0-802c-57aa427fe510.jsonl
244K    05ff5891-4abb-4474-bc66-cc082ea4e17d.jsonl

美咲が覗き込む。

「ファイル名がUUID形式になってるんですね。それに...一番大きいファイルが1.8MBもある。他は200〜300KB程度なのに」

「そう、通常のセッションファイルは数十KBから多くても数百KBよ」結愛が指摘する。「1.8MBは明らかに異常。しかも、複数のセッションファイルがあるということは...」

Aくんが気づく。

「再帰呼び出しで新しいセッションが次々と作られていたってことか！」

異常なタイムスタンプパターン

「jqコマンドで一番大きいファイルのデータを抽出してみましょう」結愛が操作する。

jq 'select(.type == "assistant") | {timestamp: .timestamp, usage: .message.usage}' cf35f4ed-bf65-4eb1-84a4-60743d93f688.jsonl

「うわぁ...」美咲が驚く。「同じタイムスタンプが大量に並んでる」

美咲が疑問を呈する。

「ところで、この数値の意味がよく分からないんですが...cache_creation_input_tokensって何ですか？」

結愛が説明する。

「正確な定義は分からないけど、名前から推測すると4種類のトークンがあるのよ」

「まず、input_tokensは普通の入力トークン。output_tokensは出力トークン。これは分かりやすいわね」

「で、cache_creation_input_tokensは新しくキャッシュに保存するデータのトークン数、cache_read_input_tokensはキャッシュから読み込むデータのトークン数だと思う」

美咲が理解する。

「つまり、最初はキャッシュがないから全部新規作成で、2回目以降は前のキャッシュを読み込んで新しい部分だけ追加するってことですか？」

「その通り！しかも、見て。キャッシュトークンが段階的に増加してるわ」結愛が指摘する。

{
  "timestamp": "2025-07-09T04:22:03.229Z",
  "usage": {
    "input_tokens": 3,
    "cache_creation_input_tokens": 14592,
    "cache_read_input_tokens": 0,
    "output_tokens": 8
  }
}
{
  "timestamp": "2025-07-09T04:22:03.229Z",
  "usage": {
    "input_tokens": 5,
    "cache_creation_input_tokens": 229,
    "cache_read_input_tokens": 14592,
    "output_tokens": 26
  }
}
{
  "timestamp": "2025-07-09T04:22:03.229Z",
  "usage": {
    "input_tokens": 6,
    "cache_creation_input_tokens": 3374,
    "cache_read_input_tokens": 14821,
    "output_tokens": 40
  }
}
{
  "timestamp": "2025-07-09T04:22:03.229Z",
  "usage": {
    "input_tokens": 103,
    "cache_creation_input_tokens": 361,
    "cache_read_input_tokens": 18195,
    "output_tokens": 40
  }
}

「見て！」結愛が重要な点を指摘する。「2025-07-09T04:22:03.229Zのタイムスタンプが何度も出てくる。しかも全く同じミリ秒まで一致してる」

Aくんが困惑する。

「普通に考えて、人間が手動で操作してたらこんなにピッタリ同じ時刻に複数のリクエストなんて送れないよね？」

「まさにその通りよ」結愛が頷く。「これは明らかに自動実行の痕跡ね」

cache読み込みパターンの発見

「注目してほしいのは、この読み書きパターンよ」結愛が重要な点を説明する。

美咲が数値を見比べる。

「あれ？最初のレコードでcache_creation_input_tokensが14,592なのに、次のレコードでcache_read_input_tokensが14,592になってる」

「そう！それが決定的な証拠なの」結愛が興奮する。「最初に作成されたキャッシュが、次のリクエストで即座に読み込まれてる」

Aくんが理解する。

「つまり、一つのリクエストが新しいセッション情報を作って、その直後に別のリクエストがそれを読み込んでる...そしてまた新しい情報を追加する」

「まさにフィードバックループの構造ね」

累積効果の証拠

「さらに見て。cache_read_input_tokensがどんどん増加してるでしょ？」

1回目: cache_read = 0 → cache_create = 14,592
2回目: cache_read = 14,592 → cache_create = 229  
3回目: cache_read = 14,821 → cache_create = 3,374
4回目: cache_read = 18,195 → cache_create = 361

「前のステップで作られたキャッシュが次のステップで読み込まれて、さらに新しいキャッシュが追加される...」

美咲が興奮する。

「つまり、AIが何かを出力して、すぐに別のAIがそれを読み込んで...ってことですか？」

「まさに再帰呼び出しの証拠よ」結愛が確信を持って答える。

状況証拠の整合性

Aくんがパズルのピースを組み合わせる。

「そうか...僕がClaudeCodeにSDKのテストを自動実行してもらって、そのSDKがまたClaudeCodeにアクセスして...」

「そしてセッションが共有されてるから、その結果がまた次のリクエストに含まれて、どんどん大きくなっていく」

結愛が最終的な分析を示す。

「データの流れを整理すると：」

1. 午前4時22分3秒（UTC）: 同一タイムスタンプでの連続リクエスト
2. キャッシュ作成と読み込みの循環: 作ったキャッシュをすぐに読み込む
3. 段階的なセッション肥大化: 14,592 → 18,195 → さらに増加
4. 再帰呼び出しパターン: 人間には不可能な同時刻リクエスト
5. ccusageで確認された高額な費用: 予想外の大量トークン消費

再現実験をしない理由

美咲が素朴な疑問を抱く。

「でも、本当に再帰呼び出しが原因かどうか、もう一度実験してみませんか？」

結愛とAくんが同時に首を振る。

「絶対ダメ！」

「今度同じことが起こったら、利用制限じゃ済まないかもしれない。下手したら本当に高額な請求がくる可能性もあるし、悪質な利用だと誤解されてアカウントがBANされる危険性もある」

「DDoS攻撃みたいなもの？」美咲が疑問を投げかける。「大量のリクエストを短時間で送り続けて、サーバーに負荷をかける攻撃のことです」

結愛が驚く。

「へぇ、美咲ちゃんも知ってるのね。その通りよ。今回のケースだと、意図せずにAPI端点に大量のリクエストを送り続けてたから、そういう攻撃と区別がつかないかもしれない」

「それに」結愛が付け加える。「既に十分な状況証拠が揃ってる。セッションデータの異常なパターン、同一タイムスタンプでの大量リクエスト、キャッシュサイズの急激な増加...これだけあれば推理としては十分よ」

データが語る真実

「結局のところ」Aくんが振り返る。「僕は効率化のつもりで、とんでもない罠にハマってしまったんだ」

「でも、おかげで重要な問題を発見できたじゃない」美咲が明るく言う。「これで他の人は同じ失敗をしなくて済みますね」

結愛が頷く。

「そうね。次は具体的な対策を考えましょう。同じような問題を防ぐ方法があるはずよ」

三人は、セッション情報の詳細な分析から、再帰呼び出しの発生を裏付ける十分な証拠を発見した。状況証拠のみとはいえ、データが示すパターンは明確で、彼らの推理が正しいことを強く示唆していた。しかし、問題を理解することと、それを解決することは別の話だった。

対策と予防 - 同じ轍を踏まないために

「さて」結愛が新しいホワイトボードを用意する。「問題を理解できたところで、実際の対策を考えましょう。特に従量課金のAPIを使っている人は、今回のような問題が発生したら金銭的なリスクが桁違いに大きくなる」

「どういうことですか？」美咲が聞く。

「Aくんは月額制だったから利用制限で止まったけど、従量課金なら上限設定がない限り処理は止まらない。数千ドル、数万ドルの請求になっていた可能性もあるのよ」

「どうすれば、Aくん先輩と同じような問題を避けられるんでしょうか？」

「いくつかのアプローチがあるわ」結愛がリストを作り始める。

基本対策：セッション分離

「一番確実な方法は、ClaudeCodeとSDKを別々のプロジェクトで実行することよ」

Aくんが理解する。

「つまり、SDKを使うプログラムは、別のディレクトリで開発するってことか」

「そういうこと。例えば：」

# ClaudeCodeでの開発
/home/user/projects/main-project/
├── src/
├── tests/
└── .claude/

# SDKを使う評価システム
/home/user/projects/evaluation-tools/
├── evaluation.py
├── requirements.txt
└── .claude/  # 別のセッション

「このようにプロジェクトを分けることで、セッション情報が混在することを防げるの」

美咲が理解する。

「なるほど、別のセッションになるから、セッション共有の問題は起こらないんですね」

「ただし」結愛が重要な点を付け加える。「これだけでは不十分なの。ClaudeCodeがSDKを実行する限り、プロジェクトが分かれていても同じ問題が発生する可能性があるわ」

「じゃあ、どうすればいいんですか？」

「重要なのは、ClaudeCodeにSDKを実行させないことよ。SDKは人間が手動で実行するか、ClaudeCode以外のシステムから実行する必要がある」

対策2：auto-acceptモードの無効化

「次に重要なのは、auto-acceptモードを使わないことね」結愛が強調する。

「auto-acceptモードって、そんなに危険なんですか？」

Aくんが苦笑いする。

「確かにESCキーを2回押せば止められるんだけど、それって人間が常に監視してることが前提なんだよね。実際は作業を任せて他のことをしてることが多いから...」

「そう」結愛が頷く。「ClaudeCodeが独自判断でテストを実行したり、ファイルのクリーンアップをして重要なファイルを消してしまうこともある。人間が監視していないと、問題が起こっても気づけないのよ」

「SDKを使う場合は特に注意が必要よ。手動確認モードにして、一つ一つのステップを確認しながら進める方が安全」

# 安全な実行例
1. ClaudeCodeにコード作成を依頼
2. 生成されたコードを手動で確認
3. 問題なければ手動で実行
4. 結果を確認してから次のステップ

対策3：権限制限とコマンド制御

「実は、ClaudeCodeには実行できるコマンドを制限する機能があるのよ」結愛が興味深そうに言う。

「本当ですか？」美咲が驚く。

「/permissionsコマンドで設定できるの。例えば、特定のコマンドを実行禁止にしたり、許可するコマンドを制限したりできる」

Aくんが理解する。

「つまり、SDKを内部で使うようなコマンドを禁止設定にしておけば、再帰呼び出しを防げるってことか」

「まさにその通りよ」結愛が頷く。「設定には2つのレベルがあるの。グローバル設定は~/.claude/settings.jsonに、プロジェクト固有の設定は各プロジェクトの.claude/settings.jsonに自動生成される。プロジェクトごとに細かく制御したい場合は、プロジェクト設定を使うことができるわ」

{
  "permissions": {
    "deny": [
      "Bash(python:sdk_script.py)",
      "Bash(node:sdk_tools.js)"
    ]
  }
}

対策4：セッション管理とコンテキスト制御

「最後に、セッション管理について重要な選択肢があるの」結愛が説明する。

Aくんが興味を示す。

「セッション管理って、具体的にはどんなことができるんですか？」

「ClaudeCodeには/clearと/compactというスラッシュコマンドがあるのよ」

# 会話履歴を完全にクリア（新しい会話を開始）
/clear

# 会話を圧縮してコンテキスト使用量を削減
/compact

# 特定の焦点で圧縮（オプション）
/compact [focus instructions]

「/clearは会話履歴を完全に削除するから、セッション共有の恩恵は失うけど、セッションサイズの肥大化は一時的に抑制できる。ただし、根本的な解決にはならないの」

美咲が確認する。

「/compactの方はどうなんですか？」

「/compactは会話内容を要約・圧縮して保持するから、重要な情報は残しつつ、コンテキストサイズを削減できるの。ClaudeCodeは95%の容量を超えると自動的に圧縮も行うけど、手動で実行することもできる」

「どうして根本的な解決にならないんですか？」美咲が疑問を持つ。

「なぜなら、ClaudeCodeが再びSDKを実行すれば、同じ再帰呼び出しが発生するからよ。セッションをクリアしても、auto-acceptモードとセッション共有の組み合わせという根本的な問題は解決されていない」

「なるほど、セッション管理は応急処置で、本当の対策は別にあるってことですね」

実用的な運用ルール

美咲がまとめを求める。

「つまり、SDKを使うときの実用的なルールは何でしょうか？」

結愛が整理する。

「以下の4つのルールを守ることを推奨するわ：」

1. 最重要原則: ClaudeCodeにSDKを実行させない（人間が手動で実行）
2. 分離の原則: SDKを使うプロジェクトは別ディレクトリで開発
3. 手動確認: auto-acceptモードは使わず、手動で各ステップを確認
4. 権限制限: SDKを使うコマンドの実行を制限

他の開発者への啓発

Aくんが責任を感じて言う。

「この問題、他の開発者にも知らせるべきだよね。同じような罠にハマる人が出てくるかもしれない」

「そうね。ブログ記事や技術コミュニティで共有することで、みんなが安全にSDKを使えるようになる」

美咲が前向きに提案する。

「私たちの体験を記事にして、注意喚起することもできますね！」

おまけ：ccusageで使用量を可視化する

「そう言えば」美咲が思い出したように言う。「Aくん先輩が最初に異常に気づくきっかけになった、ccusageっていうツールについて教えてもらえませんか？」

「あぁ、ccusage！」Aくんが表情を明るくする。「これがなかったら、今回の問題に気づくことすらできなかった」

結愛が興味深そうに聞く。

「GitHubで話題になってるツールよね。どんな特徴があるの？」

ccusageの基本情報

「ccusageは、ClaudeCodeの使用量を詳細に分析できるツールなんだ」Aくんが説明する。

「2025年5月末に公開されて、現在で既に3900スターを獲得してる。開発も活発で、668コミットに131フォークだから、かなり注目されてるツールだよ」

美咲が驚く。

「すごく人気なんですね！」

「完全オフラインで動作するのが最大の特徴なのね」結愛が補足する。「ClaudeCodeが生成したセッション情報ファイルを直接解析するから、ネットワーク接続なしで使用量をチェックできるのよ」

事後分析での威力

「今回の問題発見では、日次レポート機能が決定的だった」Aくんが振り返る。

ccusage daily

「このコマンド一つで、日別の使用量とコストが一目瞭然になる。7月10日の$133.20という異常な数値がすぐに分かった」

美咲が確認する。

「普通はどのくらいの使用量なんですか？」

「僕の場合、通常は1日$1〜15程度。それが$126って、明らかに異常だったんだ」

ライブモニタリング機能の魅力と限界

「ccusageにはblocks --liveっていうリアルタイム監視機能もあるんだ」Aくんがスクリーンショットを見せながら説明する。

「セッション状況、現在の使用量、トークン消費率、コスト予測まで表示される。すごく便利な機能だよ」

結愛が重要な点を指摘する。

「ただし、これは解析ツールであって予防ツールではないのよね」

「どういうことですか？」

「再帰呼び出しが発生してから気づくことはできるけど、既にトークンを大量消費した後になってしまう。今回のような暴走を止めるには、人間が常に監視している必要があるの」

Aくんが苦笑いする。

「確かに。ライブモニタリングがあっても、auto-acceptモードで放置してたら意味がない。結局、人間の注意深い監視が前提なんだよね」

詳細情報

「ccusageの作者は、このツールについて詳しい紹介記事も書いてるんだ」

https://zenn.dev/ryoppippi/articles/6c9a8fe6629cd6

結愛が補足する。

「機能の詳細や使い方については、GitHubの公式リポジトリを確認するのが一番正確よ」

https://github.com/ryoppippi/ccusage

美咲が興味を示す。

「作者の方はどんな人なんですか？」

「活発な開発者で、Claude関連のツールにも詳しい方みたい」Aくんが答える。「このツールのおかげで、多くのClaudeユーザーが使用量管理できるようになった」

今回の体験で学んだ活用法

「ccusageを使った今回の分析で、いくつかの活用パターンが見えてきた」結愛がまとめる。

異常検知パターン:

• 日次コストが通常の10倍以上
• 短時間（1〜2時間）での極端な使用量集中
• Cache Create Tokensの異常な増加

「こういうパターンが見えたら、即座に作業を停止して原因調査をする必要がある」

Aくんが付け加える。

「特に、開発作業後は必ずccusageでチェックする習慣をつけることにした。異常があれば翌日まで持ち越さないようにね」

監視ツールとしての位置づけ

「ccusageのようなツールは、AI時代の開発において必須になってくると思う」結愛が展望を語る。「ただし、解析・分析ツールとして活用し、根本的な予防策と組み合わせることが重要よ」

Aくんが頷く。

「ccusageで異常を発見したら、今日話した対策を実行する。この組み合わせが大切なんだ」

「最後に」Aくんが感謝を込めて言う。「このツールがなかったら、問題の存在すら気づけなかった。開発者の方には本当に感謝してる」

美咲が締めくくる。

「私たちも、この経験を共有することで、コミュニティに貢献できればいいですね」