Claude Code /insightsで自分の使い方を可視化する — フリクション特定→CLAUDE.md改善→再計測の実践サイクル

CLAUDE.mdに何を書けばいいか分からない。書いてはみたが効果があるのか不明——そんな悩みを解決するのが /insights コマンドだ。過去30日分のセッションログをAIが分析し、摩擦パターンの特定からCLAUDE.mdルールの自動提案まで行ってくれる。本記事では、レポートの読み方だけでなく「分析→改善→再計測」のサイクルを回して、Claude Codeの応答品質を継続的に引き上げる方法を解説する。

/insightsとは何か — 30日分のセッションを分析するビルトインコマンド

何が分析されるのか

/insights は2026年2月、Claude Code v2.1系のマイナーリリースでAnthropicのThariq氏が公式発表した機能だ。~/.claude/projects/ 配下のセッションログを読み取り、インタラクティブなHTMLレポートを生成する。

# Claude Code内で実行するだけ
/insights

# レポートは以下に出力され、ブラウザで自動表示される
# ~/.claude/usage-data/report.html

対象は過去30日間のセッションで、1回の実行につき最大50セッションを分析する。以下の条件に該当するセッションは除外される。

• 継続時間が1分未満
• ユーザーメッセージが2件未満
• agent- プレフィックスのサブセッション

内部では6段階のパイプラインが走る。セッションのフィルタリング→トランスクリプト要約（30,000文字超は25,000文字チャンクに分割）→Haikuモデルによるファセット抽出（最大4,096トークン/セッション）→集約分析（各最大8,192トークン）→サマリー生成→HTML描画という流れだ。

プライバシーとコスト

処理にはHaikuモデルのAPI呼び出しが発生するが、送信内容はインタラクションパターン（タスクタイプ、満足度シグナル、摩擦発生箇所）にフォーカスされている。生成されたレポートやサマリーデータが外部送信されることはない。

Pro/Maxプランのサブスクリプション内で利用可能だが、セッション数に応じて一定のレートリミットを消費する点は頭に入れておきたい。なお、ファセット抽出結果は ~/.claude/usage-data/facets/ にキャッシュされるため、2回目以降は新規セッションのみの処理で済む。

レポートの読み解き方 — 提案カテゴリを理解する

レポートには統計ダッシュボード（セッション数、ツール使用分布、言語別内訳など）に加え、以下のナラティブセクションが含まれる。

• Project Areas — プロジェクト領域ごとのセッション分布
• What's Working — うまくいっているワークフロー
• Friction Analysis — 摩擦パターンの詳細（Claude側の問題かユーザー側の問題かを分類）
• CLAUDE.md Additions — 追加すべきルールの提案（コピーボタン付き）
• Features to Explore — 未活用のClaude Code機能

改善の第一歩はFriction Analysisセクションだ。ツール実行の拒否、繰り返し修正、コンテキスト不足といった摩擦パターンのうち、自分のプロジェクトで何が頻出しているかを把握する。各提案には「どのセッションで摩擦が発生したか」の根拠が付くので、なぜその提案が出たかを逆引きできる。正直、初めてレポートを見たとき、自分の癖がここまで可視化されるのかと驚いた。

提案は頻度×影響度で暗黙的にソートされている。全部に対応しようとせず、上位3つに集中するのが効率的だ。

実践: /insightsの提案をCLAUDE.mdルールに変換する

Before/After — 曖昧な指示を具体的ルールに変換する

insightsが出す提案にはそのままコピペできるものと、プロジェクト固有の調整が必要なものがある。判断基準はシンプルで、「誰のプロジェクトでも当てはまるか」どうかだ。以下に変換例を3パターン示す。

コーディング規約系

# Bad: 曖昧
TypeScriptを使ってください

# Good: 具体的
新規ファイルは .ts で作成。既存 .js ファイルの変更時に型注釈を追加しない。

ワークフロー系

# Bad: 範囲が広すぎる
テストを書いてからコードを書いてください

# Good: 手順が明確
機能追加時は以下の順序で作業する:
1. 失敗するテストケースを vitest で作成
2. テストが通る最小実装を行う
3. npm test で全テスト通過を確認してからコミット

ツール使用系

# Bad: 制約なし
ファイルを編集してください

# Good: 安全策付き
src/ 配下のファイルを編集する前に、必ず該当ファイルを Read で確認する。
node_modules/ や dist/ は絶対に編集しない。

.claude/rules/ への分割配置で保守性を上げる

CLAUDE.mdが肥大化したら .claude/rules/ ディレクトリに分割する。ファイル名でスコープを明示するのがコツだ。

.claude/
├── CLAUDE.md              # プロジェクト概要 + 最重要ルールのみ
└── rules/
    ├── code-style.md      # コーディング規約
    ├── testing.md         # テスト方針
    ├── git.md             # コミット・ブランチ規約
    └── api/
        └── validation.md  # API固有ルール（パス条件付き）

パス条件付きルールにはフロントマターで対象を指定できる。

---
paths:
  - "src/api/**/*.ts"
---

APIエンドポイントには必ず入力バリデーションを含める。

CLAUDE.mdは200行以下に抑えるのが推奨されている。超えるとコンテキスト消費が増え、遵守率が下がる。Progressive Disclosureの考え方で、CLAUDE.mdはプロジェクト概要と重要ルールに絞り、詳細は rules/ に委譲する構成が効果的だ。

Skills・Hooksへの反映 — 繰り返し作業を自動化する

「毎回同じ手順を指示している」→ Skillファイルに切り出す

insightsのFriction Analysisで「同じ指示を繰り返している」パターンが見つかったら、.claude/skills/ にMarkdownで定義して /skill-name で呼び出せるようにする。

<!-- .claude/skills/deploy/SKILL.md -->
---
name: deploy
description: ステージング環境へのデプロイ手順
---

以下の手順でデプロイを実行する:
1. npm run build でビルド成功を確認
2. npm test で全テスト通過を確認
3. git push origin main
4. vercel deploy --prod を実行
5. デプロイURLにアクセスしてHTTP 200を確認

「ツール実行前に毎回確認している」→ Hooksで自動化する

.claude/settings.json の hooks セクションに設定を追加する。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null; exit 0"
          }
        ]
      }
    ]
  }
}

この例では、ファイル編集後に自動でPrettierを実行する。「毎回 npm test を手動で指示している」なら、同様にPostToolUseフックでテスト自動実行を設定できる。

過度な自動化は逆効果になる。個人的には、insightsで頻度が5回以上出現しているパターンだけをSkill/Hook化する、という基準で運用するのがちょうどいいと感じている。

改善サイクルを回す — 月次 /insights で効果を計測する

改善前後の比較方法

CLAUDE.mdルールを追加したら、2〜4週間普段通りに使い込んでから再度 /insights を実行する。同じ摩擦パターンが減少していれば改善が効いている証拠だ。

HTMLレポートは ~/.claude/usage-data/report.html にローカル保存されるが、上書きされるため、改善前のレポートを残したい場合は手動でコピーしておく。

# 改善前のレポートを保存
cp ~/.claude/usage-data/report.html ~/insights-before-$(date +%Y%m%d).html

定着させるための運用Tips

• 月1回の実行を習慣化する。 カレンダーリマインダーやcronで通知するのが確実だ
• チーム開発では、各メンバーの結果から共通パターンを抽出し、 プロジェクトルートのCLAUDE.mdに反映するのが効率的
• 改善が頭打ちになったら、 レポートの「Features to Explore」セクションに注目して新しいワークフローを試す
• 2回目以降の実行はキャッシュが効くため、 コスト面を気にせず気軽に回せる

/insights は「Claude Codeを使うほど賢くなる」ための唯一のフィードバックループを提供する。感覚的だったCLAUDE.mdの改善を、データに基づく継続的プロセスに変えてくれる。まずは今すぐ /insights を実行して、自分の摩擦パターンを確認するところから始めてほしい。