2026-08-19 時点の公式ドキュメントをもとに書き、2026-11-19 時点の公式ドキュメント(costs / commands)で照合し直しました。照合時点で変わっていた点は本文に明記しています。Claude Code の仕様は今後も更新されることがあります。レポートのレイアウトや文言も、バージョンや実行環境で変わる場合があります。claude --version で自分の環境のバージョンを確認し、最新は公式ドキュメントで確かめてください。
Claude Code の /insights は、トークンの量ではなくどう使っているかをレポートにするコマンドです。公式ドキュメントの言い方では、"how many tokens you've used" ではなく "how you work" についてのレポートです。
この記事では、/insights が何をして、何を出力し、どこに保存し、何が対象外なのかを、公式ドキュメントの記載に沿ってまとめます。
TL;DR
Claude Code の入力欄で:
/insights
- 引数もフラグもない。このマシンに残っている直近のセッション履歴を分析し、HTML のレポートを書き出す
- 見るのは消費量ではなく働き方(プロジェクトの分布・使い方の傾向・うまくいっていない箇所・試すべき機能)
- 1回の実行で、未分析のセッションを最大200件。極端に短いセッションはスキップ
- 出力は
~/.claude/usage-data/report.html。実行ごとのタイムスタンプ付きコピーも残り、cleanupPeriodDays(デフォルト30日)で削除される - 他のデバイス・claude.ai・クラウドセッションは対象外。分析自体がトークンを消費する
何をするコマンドか
- このマシンで実行した Claude Code のセッション履歴を読む
- 通常のセッションと同じプロバイダー・同じアカウントで、Claude が分析する
- HTML のレポートとして書き出す
/usage・/context との違い
「使用量まわり」のコマンドは複数あります。役割はこう分かれます。
| コマンド | 見るもの | 時間軸 |
|---|---|---|
/context |
いまコンテキストウィンドウに何が載っているかをカラーグリッドで可視化。コンテキストを食っているツールやメモリ肥大への最適化提案も出る | 現在 |
/usage |
トークン数・モデル別コスト・支出傾向。Pro/Max/Ultra/Team/Enterprise では、プラン使用量バーに加え、スキル・サブエージェント・プラグイン・MCP サーバー別の内訳と改善の提案も表示(d / w で直近24時間・7日間を切り替え) |
現在のセッション+全セッション |
/cost |
/usage のエイリアス。中身は同じ(/stats もエイリアスで、こちらは Stats タブで開く) |
同上 |
/insights |
どのプロジェクトで作業したか、Claude Code をどう使っているか、どこでうまくいっていないか、試すべき機能 | 直近のセッション群 |
2026-11-19 時点の公式ドキュメントとの差分: 2026-08-19 時点の記載と比べ、/usage の内訳が出るプランに Ultra が加わり、内訳には改善の提案(直近の使用量の10%以上に関わる行)が並ぶようになっています。/stats も /usage のエイリアスとして載っています。出典: Manage costs effectively / Commands
/context と /usage が「いくら使ったか」を答えるのに対し、/insights は「どう使ったか」を答えます。
レポートの中身
公式ドキュメントによると、レポートは次の4点をカバーします。
| 項目 | 内容 |
|---|---|
| どのプロジェクトで作業しているか | 作業対象の分布 |
| Claude Code をどう使っているか | 使い方の傾向 |
| どこでうまくいっていないか | 摩擦点(friction points)。例として「誤解された依頼」「バグを含んだコード」が挙げられている |
| 試すべき機能 | より効果的に使うための提案 |
行動を変える材料になるのは3番目の摩擦点です。依頼が誤解されればやり直しが起き、やり直しは追加のトークンと時間になります。摩擦点を減らせば、その分のやり直しが減ります。
(この因果は公式に明記されているわけではなく、筆者の整理です。)
2026-11-19 時点の公式ドキュメントでは、上の4点に加えて、auto mode が使える環境で直近のセッションの多くが auto mode なしで動いていた場合、auto mode なら処理できた権限確認の数の見積もりがレポートに含まれることがある、と書かれています。出典: Manage costs effectively
分析されるセッションの範囲
- 1回の実行で、まだ分析していないセッションを最大200件まで処理する
- 極端に短いセッションはスキップされる
- セッションが除外された場合、レポートのヘッダーに分析件数と総数が併記される。ドキュメントの表示例は次のとおり
200 sessions (412 total)
履歴が大量にたまった状態で初めて実行すると、1回では消化しきれません。括弧内の総数と分析件数を比べれば、取りこぼしがあるかがわかります。
保存先と保持期間
| 項目 | 仕様 |
|---|---|
| 最新のレポート | ~/.claude/usage-data/report.html |
| 実行ごとの控え | 同じディレクトリに、タイムスタンプ付きのコピーを保存。過去分は上書きされない |
| 削除のタイミング | 他のセッションデータと同じ。起動時に cleanupPeriodDays より古いファイルを削除 |
| デフォルトの保持期間 | 30日 |
コピーが残るので、前回と今回のレポートを並べて、摩擦点が減ったかを比べられます。ただし30日で消えるので、長く追うならレポートを別の場所に退避させておく必要があります。
対象外になるもの
/insights はローカルのセッション履歴を読みます。次のものは分析に含まれません。
| 対象外 | 補足 |
|---|---|
| 他のデバイスのセッション | 会社の Mac と自宅の Mac で使い分けていれば、それぞれ別のレポートになる |
| claude.ai のセッション | ブラウザやアプリ側のチャットは対象外 |
| クラウドセッション | ドキュメントに "Not available in cloud sessions" と明記。Claude Code on the web では実行できない |
レポートはマシンごとです。複数のマシンで作業しているなら、それぞれのマシンで実行して読み比べます。
コストとプラン
- どのプランでも、どのプロバイダーでも実行できる
- 分析は、通常のセッションと同じプロバイダー・同じアカウントを通して走る
- したがって、分析に使われたトークンはプラン枠または API 使用量にカウントされる
対象は「まだ分析していないセッション」なので、2回目以降は処理件数が減ります。それでもトークンは消費するので、思い立つたびではなく節目で回すのが無難です(筆者の整理です)。
運用の手順
仕様から組み立てた運用です(筆者の整理です)。
-
月末やスプリントの区切りで
/insightsを実行する。 毎日叩くものではない。セッションがある程度たまってからの方が、傾向として意味が出る - 「どこでうまくいっていないか」から読む。 行動を変えられるのは摩擦点の指摘
- 指摘を CLAUDE.md や Skill に落とす。 同じ誤解が繰り返されているなら、毎回説明し直している証拠。プロジェクト共通の前提は CLAUDE.md へ、特定の作業手順は Skill へ
- 翌月のレポートで効果を確かめる。 タイムスタンプ付きのコピーと比べ、指摘された摩擦点が減っていれば改善は効いている
CLAUDE.md は毎セッション常時ロードされます。公式ドキュメントは、CLAUDE.md を200行未満に保ち、特定のワークフロー向けの詳細な手順は、呼ばれたときだけ読み込まれる Skill 側に移すことを推奨しています。何でも CLAUDE.md に書き足すと、それ自体が枠を食い始めます。
まとめ
| 知りたいこと | 使うコマンド |
|---|---|
| 何が枠を食っているか |
/usage(/cost) |
| いまのコンテキストに何が載っているか | /context |
| なぜそういう使い方になっているか | /insights |
枠が足りないと感じたら、まず /usage で何が食っているかを見て、そのうえで /insights で使い方を見直す。この2段で見るのが効率的だと考えています(筆者の整理です)。
参考
- Manage costs effectively - Claude Code Docs — https://code.claude.com/docs/en/costs
- Commands - Claude Code Docs — https://code.claude.com/docs/en/commands
- How Claude remembers your project(CLAUDE.md のサイズの目安)- Claude Code Docs — https://code.claude.com/docs/en/memory
※ 公式ドキュメントの記載(2026-08-19 時点)に基づいて構成し、2026-11-19 時点の同ドキュメントで照合し直しました。分析件数(最大200件)・表示例・保存先・cleanupPeriodDays(デフォルト30日)・クラウドセッション非対応・/cost が /usage のエイリアスであること・CLAUDE.md を200行未満に保つ推奨は、照合時点でも同じ記載でした。実際のレポートの出力例は載せていません。



