Claude Codeの「ブラックボックス問題」

Claude Codeに複雑なタスクを投げて30分。ターミナルにはカーソルが点滅するだけ。トークンカウンターは着実に増えていく。キャンセルすべきか、もう少し待つべきか。判断材料がありません。

これは「AIコーディングエージェントのブラックボックス問題」です。実際に筆者が経験した典型的なケースを挙げます。

ケース1: サブエージェントの無限ループ

リサーチ用のサブエージェントを6つ並列起動する構成で、1つが同じファイルを繰り返し読み続けていました。他の5つはとっくに完了しているのに、全体が1つに引きずられて20分以上待機。ターミナル上では「まだ処理中」としか見えません。

ケース2: 無駄なファイル読み直し

ある機能実装を依頼したところ、完了までに約15分。後から可視化ツールで確認すると、同じ設定ファイルを8回、同じソースファイルを12回読み直していました。コンテキストウィンドウの圧縮後に再読み込みが増える傾向を観測しました。

ケース3: トークンコストの想定外の膨張

「簡単なバグ修正」のつもりが、Claude Codeが関連ファイルを芋づる式に調査し、入力トークンだけで50万を超えていました。$3以上のコストです。事前にトークン消費の推移が見えていれば、途中で方針を変えられたはずです。

こうした問題に対して、現在3つの可視化ツールが登場しています。本記事では、それぞれを実際に導入した体験をもとに、セットアップから使用感、使い分けまでを整理します。

1. claude-devtools: 5分で始められるリアルタイム監視

claude-devtoolsは、Claude Codeのセッションログを読み取り、実行内容を可視化するデスクトップアプリケーションです。~/.claude/ ディレクトリのログを非侵襲的に解析します。Claude Code自体の設定変更は不要です。

セットアップ

macOSの場合はHomebrewで完結します。

brew install --cask claude-devtools

Linux/Windowsの場合は、GitHubリリースページから .AppImage、.deb、.exe をダウンロードします。

Docker環境でも動作します。

docker run --network none \
  -p 3456:3456 \
  -v ~/.claude:/data/.claude:ro \
  claude-devtools

--network none で起動すれば外部通信を完全に遮断できます。

環境変数	デフォルト	用途
`CLAUDE_ROOT`	`~/.claude`	データディレクトリのパス
`HOST`	`0.0.0.0`	バインドアドレス
`PORT`	`3456`	リッスンポート

使ってみて分かったこと

インストールして最初のセッションを開いた瞬間、いくつかの発見がありました。

トークン消費の内訳が見える

devtoolsはトークン消費を7カテゴリに分類して表示します。筆者のあるセッション（1回分の測定）を分析したところ、入力トークンの約40%が「ファイル読み取り結果」でした。つまり、Claude Codeに渡しているCLAUDE.mdやルールファイルの内容が、毎ターン大量のトークンを消費していたのです。

この発見をきっかけに、CLAUDE.mdを約30%削減しました。冗長な説明や重複するルールを整理した結果、1セッションあたりのトークン消費が目に見えて減りました。

コンテキスト圧縮の発生タイミングが分かる

「圧縮イベント可視化」機能により、コンテキストウィンドウの上限に達した瞬間を検出できます。あるセッションでは、15分の作業中に3回の圧縮が発生していました。圧縮が起きた後、同じファイルの再読み込みが増える傾向を観測しました。

圧縮の頻度が高すぎる場合、タスクの粒度が大きすぎるというシグナルです。

サブエージェントの動きが追える

実行ツリー表示で、メインエージェントとサブエージェントの関係がツリー構造で見えます。どのサブエージェントがどのタスクを担当し、どれが完了してどれが停滞しているかが一目瞭然です。

主な機能一覧

機能	説明
コンテキスト再構築	トークン消費を7カテゴリに分類して表示
圧縮イベント可視化	コンテキスト上限到達時の圧縮を検出
ツール呼び出しインスペクタ	構文ハイライト付きの入出力表示、インラインdiff
カスタム通知トリガー	`.env`アクセスやエラー発生を通知
サブエージェント可視化	実行ツリーとカラーコード化されたメッセージ
マルチペイン	複数セッションの並行表示
SSH遠隔セッション	リモートマシンの `~/.claude/` に接続

完全にローカルで動作し、外部APIキーは不要です。--network none でDockerを起動すればネットワーク通信も完全に遮断できます。

2. OpenTelemetry連携: メトリクスとイベントで見えるボトルネック

Claude Codeは公式にOpenTelemetry（OTel）連携をサポートしています。devtoolsがリアルタイム監視なら、OTelは「事後分析と定量的な改善」に強い仕組みです。

公式がサポートするのはメトリクス（時系列データ）とイベント（ログ/イベントプロトコル経由）の2種類です。トレース（Span）のネイティブエクスポートは公式仕様に含まれていません。

公式OTel連携のセットアップ

環境変数を設定するだけで有効化できます。

# テレメトリを有効化
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# エクスポーターを設定（それぞれ任意）
export OTEL_METRICS_EXPORTER=otlp       # otlp, prometheus, console
export OTEL_LOGS_EXPORTER=otlp          # otlp, console

# OTLPエンドポイント
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

claude

バックエンドはPrometheus、Datadog、Honeycomb、Grafana（Loki/Tempo）等、OTLPを受け取れる任意の基盤が使えます。既にGrafanaやDatadogを運用している組織なら、OTLPエクスポーターを追加するだけで統合できます。

公式がエクスポートするデータ

メトリクス（claude_code.*）:

メトリクス名	説明
`claude_code.token.usage`	トークン消費量（input/output/cacheRead/cacheCreation別）
`claude_code.cost.usage`	セッションコスト（USD）
`claude_code.session.count`	セッション開始数
`claude_code.lines_of_code.count`	コード変更行数（追加/削除別）
`claude_code.active_time.total`	アクティブ時間（秒）
`claude_code.commit.count`	gitコミット数
`claude_code.pull_request.count`	PR作成数

イベント（OTEL_LOGS_EXPORTER設定時）:

イベント名	内容
`claude_code.user_prompt`	プロンプト送信（内容はデフォルトで非記録、長さのみ）
`claude_code.tool_result`	ツール実行結果（ツール名、成否、実行時間等）
`claude_code.api_request`	APIリクエスト（モデル、コスト、トークン数等）
`claude_code.api_error`	APIエラー

独自トレース化による拡張: Span構造の実装

公式OTel連携はメトリクスとイベントのエクスポートですが、セッションログ（~/.claude/projects/以下のJSONL）を独自に解析してSpan/トレースに変換する手法もあります。参考記事（Zennの実装例）では、以下の3階層Span構造を独自実装しています。

Span階層	内容
Session	セッション全体（ルートSpan）
Turn	ユーザー発言と応答の1往復
Tool_call	個別のツール実行

この手法をJaeger等のトレースバックエンドと組み合わせると、ウォーターフォール表示でターン間の依存関係やボトルネックを視覚的に確認できます。ただし、これはClaude Code公式の機能ではなく、ユーザーによる独自実装である点に注意してください。

セキュリティに関する注意: 公式ドキュメントによると、ツール実行イベントのtool_parametersフィールドにはBashコマンドやファイルパスが含まれます。コマンドに秘密情報が含まれる可能性がある場合は、テレメトリバックエンド側でフィルタリングやリダクションを設定してください。ユーザープロンプトの内容はデフォルトでは記録されません（OTEL_LOG_USER_PROMPTS=1で有効化可能）。

OTelから見えた「隠れたボトルネック」

筆者が1セッション（130回のツール呼び出し）を分析した結果です（サンプル数1のため、あくまで参考値です）。

指標	値
Bash実行	90回（69.2%）、平均13.8秒
TaskOutput（サブエージェント待機）	20回（15.4%）、平均79.2秒
エラー率	12.3%
キャッシュ効率	99.6%
最長ターン	313秒

注目すべきはサブエージェント待機の平均79秒です。回数は全体の15%に過ぎませんが、合計待機時間では全体の半分以上を占めていました。ツール呼び出しの回数だけを見ていては、このボトルネックには気づけません。

独自トレース化を行った場合、Jaeger等のウォーターフォール表示で24時間の活動を1画面で俯瞰できます。公式のメトリクス・イベントだけでも、以下のような改善アクションを導けます。

claude_code.token.usageのtype別分析でキャッシュ効率を確認し、CLAUDE.mdの構造を見直す
claude_code.tool_resultイベントのsuccess率からエラーが多いツールを特定し、フック設定を改善する
ツール実行時間（duration_ms）からサブエージェントの待機ボトルネックを特定し、分割粒度を調整する

企業規模での導入: ZOZOの事例

個人利用では「環境変数を設定してPrometheusやconsole出力で確認して終わり」ですが、企業規模になると話が変わります。

ZOZOテクノロジーズの事例（執筆時点ではてなブックマーク約190件を集めた記事）では、数百名規模のエンジニア組織にOpenTelemetryの収集基盤を導入しています。この事例から見える個人利用との違いは以下の点です。

観点	個人利用	企業規模
バックエンド	Prometheus等の単体構成	OTel Collector → 複数バックエンド
データ保持	数日〜数週間	月単位、コンプライアンス要件あり
認証・認可	不要	チーム別のアクセス制御が必須
アラート	手動確認	閾値超過で自動通知
コスト管理	個人の感覚値	部門別のトークン消費レポート

Claude Codeのチーム導入が進む中、「誰がどのくらいトークンを消費しているか」「特定のプロジェクトでエラー率が高くないか」を組織レベルで把握する需要は確実に増えています。OTelの知識は、個人の生産性改善だけでなく、チーム基盤の設計にも直結します。

既にGrafanaやDatadogを使っている組織なら、OTLPエクスポーターを追加するだけでClaude Codeのメトリクスとイベントを既存ダッシュボードに統合できます。新しい監視基盤を立てる必要はありません。

3. cmux: マルチプロジェクトの司令塔

cmuxは「AIエージェント向けに設計されたターミナルマルチプレクサ」です。tmuxのようにペイン分割ができるうえ、CLIからの操作を完全に自動化できます。

前述の2つとの根本的な違い: claude-devtoolsとOTelはClaude Codeのセッションログやテレメトリを解析する「Claude Code自体の実行観測ツール」です。一方、cmuxはcmux上で別ペインとして起動したエージェントプロセスの可視化と操作を行うツールであり、比較軸が異なります。cmuxは「Claude Codeの中身を覗く」のではなく、「複数のClaude Codeインスタンスを外側から管理する」という位置づけです。

セットアップ

Claude Codeのプラグインとしてインストールします。

# Plugin（推奨）
claude /plugin install hummer98/using-cmux

cmuxセッション内でClaude Codeを起動すると、環境変数 CMUX_SOCKET_PATH を自動検出してスキルがロードされます。追加の設定は不要です。

実際のワークフロー: 3プロジェクト並列開発

筆者の場合、本業のWebアプリ開発、副業のAPI開発、個人プロジェクトのCLIツール開発を並行して進めることがあります。cmuxを使った場合の典型的なワークフローです。

# ワークスペース1: 本業のWebアプリ
cmux new-split right
cmux send --surface surface:1 "cd ~/dev/webapp && claude"

# ワークスペース2: 副業のAPI
cmux new-split right
cmux send --surface surface:2 "cd ~/dev/api && claude"

# ワークスペース3: 個人プロジェクト
cmux new-split right
cmux send --surface surface:3 "cd ~/dev/cli-tool && claude"

各ペインの内容はいつでも読み取れます。

# 各ペインの現在の状態を確認
cmux read-screen --surface surface:1
cmux read-screen --surface surface:2
cmux read-screen --surface surface:3

重要なのは、サブエージェントの動きが「別ペインで直接見える」という点です。devtoolsやOTelではログやトレースを介した間接的な確認ですが、cmuxではサブエージェントがリアルタイムで何をしているかをそのまま観察できます。

Claude Codeとの統合

using-cmuxプラグインにより、Claude Codeは以下を自律的に実行します。

ペインの分割と管理
別ペインへのコマンド送信と結果の監視
サブエージェントの起動、監視、結果回収の自動化
ワークスペースを跨いだ横断操作

cmux-team: 自律的な並列タスク管理

cmux-teamを使うと、4層アーキテクチャで複数タスクを自律管理できます。

レイヤー	役割
Master	ユーザーがissueファイルに指示を記述
Manager	issueを検出しConductorを起動
Conductor	git worktreeで独立ブランチを使用
Agent	実作業を実行

各Conductorが独立したgit worktreeを持つため、mainブランチは保護されます。タスク完了時にManagerがマージを実行します（cmuxエコシステム紹介記事より。GitHub READMEには自動マージの明示的な記述はないため、実際の挙動はバージョンにより異なる可能性があります）。

例えば「認証機能の実装」と「テストの追加」と「ドキュメントの更新」を同時にissueとして書くだけで、3つのConductorが独立ブランチで並列作業し、完了後に順次マージされます。

cmux-remoteを使えば、iPhoneからの遠隔監視も可能です。外出中にサブエージェントの進捗を確認し、必要に応じて介入するといった使い方ができます。

4. 比較表と段階的導入パス

機能比較

項目	claude-devtools	OpenTelemetry連携	cmux
主な用途	セッション監視・分析	定量分析・基盤統合	マルチプロジェクト管理
導入難易度	低（brew一発）	低〜中（環境変数設定のみ。独自トレース化は追加実装要）	中（プラグイン + cmux）
リアルタイム性	あり	事後分析が主	あり
サブエージェント可視化	実行ツリー表示	イベントで間接確認（独自トレース化で拡張可）	ペインで直接確認
トークン分析	7カテゴリ分類	メトリクス（input/output/cache別）	なし
既存基盤との統合	単独動作	Prometheus/Grafana/Datadog等	tmux的な操作感
遠隔監視	SSH接続	Webダッシュボード	cmux-remote
セキュリティ	ローカル完結	tool_parametersにコマンド・パス含む（要フィルタ設定）	ローカル完結
複数セッション管理	マルチペイン	セッション別トレース	ワークスペース分割
チーム利用	個人向け	組織規模に対応	小規模チーム向け

段階的導入パス

Claude Codeの利用状況に応じた導入順序の目安です。

ステップ1: まずdevtoolsで現状を把握する

brew install --cask claude-devtools

最初にやるべきことは「自分のClaude Codeが何をしているか知る」ことです。devtoolsでセッションを数回観察するだけで、トークン消費パターンやツール呼び出しの傾向が見えてきます。ここで得た知見をもとに、CLAUDE.mdの最適化やタスク粒度の調整ができます。

ステップ2: コスト意識が高まったらOTelを追加する

devtoolsで日々のトークン消費を意識するようになると、次は「定量的な分析と改善」が欲しくなります。OTelを導入すれば、「先週と今週でトークン効率はどう変わったか」「どのプロジェクトのコストが高いか」を数値で追えます。環境変数を設定するだけで有効化でき、既にGrafanaやDatadogを使っているなら統合も容易です。

ステップ3: 並列開発が増えたらcmuxを導入する

複数プロジェクトを同時に進めるようになったら、cmuxの出番です。ペイン分割による直接的な監視と、cmux-teamによる自律的なタスク管理が、開発の並列度を引き上げます。

3つすべてを一度に導入する必要はありません。devtoolsだけでも十分な価値があります。自分の課題に合わせて段階的に追加してください。

5. 可視化から得られる実践的なインサイト

ツールを導入すること自体が目的ではありません。可視化から得られるインサイトをもとに、Claude Codeの使い方を改善することが本質です。筆者が実際に得た学びをいくつか共有します。

CLAUDE.mdは「短く、構造化する」が正解

トークン消費の内訳を分析したところ、CLAUDE.mdとルールファイルが毎ターンの入力トークンの大きな割合を占めていました。「念のため書いておこう」と追加したルールが、すべてのターンでトークンを消費し続けます。

対策として、CLAUDE.mdを以下のように見直しました。

汎用的なルールは .claude/rules/ に分離する
参照頻度が低い情報はサブディレクトリのCLAUDE.mdに移す
箇条書きを中心にし、散文的な説明を減らす

「サブエージェントの数」は多ければいいわけではない

6つのサブエージェントを並列起動するリサーチ構成を使っていました。OTelのトレースで分析すると、6つのうち2つは他のサブエージェントとほぼ同じ情報を収集していました。サブエージェント数を4つに減らしたところ、全体の完了時間はほぼ変わらず、トークン消費だけが30%減りました。

コンテキスト圧縮の回数でタスク粒度を判断する

devtoolsで圧縮イベントの発生回数を確認する習慣をつけました。1セッションで3回以上の圧縮が発生する場合、タスクの粒度が大きすぎます。タスクを分割して、1セッション1〜2回の圧縮に収まるようにすると、無駄なファイル再読み込みが減り、結果的に早く完了します。

エラー率12%は「許容範囲」ではなかった

トレースで計測したエラー率12.3%は、一見すると低い数値に思えます。しかし、エラーが発生するたびにClaude Codeはリトライし、その分のトークンが余計に消費されます。エラーの内訳を確認すると、大半が「存在しないファイルパスへのアクセス」でした。プロジェクト構造をCLAUDE.mdに明記したところ、エラー率は5%以下に改善しました。

まとめ

Claude Codeの「中で何が起きているか分からない」問題に対して、3つのアプローチが確立されつつあります。

ツール	一言で言うと	最初に試すべき人
claude-devtools	手軽に始められるセッション監視	全員
OpenTelemetry連携	メトリクス・イベントベースの定量分析	コスト管理を重視する人
cmux	マルチプロジェクトの並列管理と可視化	複数プロジェクトを並行する人

どれか1つを選ぶなら、まずclaude-devtoolsから試してください。brew install だけで、自分のClaude Codeが何にトークンを使い、どこで時間を消費しているかが見えるようになります。

可視化の目的は「眺めること」ではなく「改善すること」です。トークン消費パターンからCLAUDE.mdを見直す。ボトルネックからタスク粒度を調整する。エラー率からプロジェクト設定を改善する。こうしたフィードバックループを回すことで、Claude Codeの費用対効果は確実に上がります。

参考リンク

claude-devtools (GitHub)
Claude Code公式: Monitoring（OpenTelemetry連携）
Claude Code × OpenTelemetryで実現するAIエージェントの可観測性 (Zenn) -- 独自トレース化の実装例
cmuxエコシステム (Zenn)
using-cmux (GitHub)