xtone__ai_development_tools/docs/session-evaluator-guide.md

Session Evaluator 利用ガイド

作成日: 2026-03-16 開発者: 郡嶋 ドキュメント作成: 石原 目的: Claude Codeセッションの効率を可視化し、チーム全体の生産性を改善する

---

1. 概要

Session Evaluatorとは

郡嶋が開発した、Claude Codeのセッションログ（JSONL）を解析し、7つの観点から100点満点で効率をスコアリングするWebツール。

「コードの品質」ではなく「無駄の有無」に焦点を当てた評価で、セッションの改善ポイントを具体的に提示する。

当初はPython CLI + SKILL.md形式で開発され、その後Web UIに進化。評価軸も6観点60点満点から7観点100点満点に拡張された。

なぜ必要か

• Claude Codeのセッションは長時間化しがちで、無駄な作業が混入しやすい
• 感覚的な「良い/悪いセッション」を定量的に評価できる
• 改善提案がhook/rule/skill/commandの形で出力され、即座にCLAUDE.mdに反映可能

---

2. セットアップ

必要環境

項目	要件	備考
Node.js	18以上	node -v で確認
Claude CLI	PATH上に存在	Analyzeモードのみ必要

起動方法

# リポジトリからの起動
cd common_development/skills/evaluate-session/app
npm install
npm start

起動すると自動でブラウザが開く（デフォルト: http://localhost:5173）。

# ポートを指定する場合
npm start -- --port 8080

---

3. 使い方

3.1 画面構成

起動するとVSCode風のダークテーマUIが表示される。

┌─────────────────────────────────────────────┐
│ ツールバー: [Analyze] [Stats Only] [Model▼] │
├──────────┬──────────────────────────────────┤
│          │                                  │
│ プロジェ │   セッション一覧                  │
│ クト一覧 │   （最新順、プレビュー付き）       │
│          │                                  │
├──────────┴──────────────────────────────────┤
│ History パネル                               │
└─────────────────────────────────────────────┘

3.2 操作手順

1. プロジェクト選択: 左パネルから対象プロジェクトをクリック
2. セッション選択: 中央パネルからセッションをクリック（先頭のユーザーメッセージがプレビュー表示される）
3. 分析モード選択:

モード	所要時間	Claude CLI	内容
Stats Only	数秒	不要	統計データのみ表示（トークン、ツール使用回数、重複読み込み等）
Analyze	1〜3分	必要	Stats + AI評価（7観点スコアリング + 改善提案）

4. モデル選択（Analyze時）: ツールバーのドロップダウンで sonnet / opus / haiku を選択
   • 推奨: sonnet（コストと精度のバランスが良い）
   • opus: より精密だがコスト高
   • haiku: 高速だが評価精度が下がる可能性あり

3.3 結果の見方

Stats Only の結果

セクション	表示内容
Overview	セッション時間、ターン数、トークン数、キャッシュ活用率
Tool Usage	ツール別の実行回数（棒グラフ）
Duplicate Reads	同一ファイルの重複読み込み一覧
Write/Edit Rework	同一ファイルへの複数回書き込み（手戻り指標）
Errors & Retries	エラー発生と即リトライの検出

Analyze の結果

Stats Onlyの内容に加えて、以下が表示される:

セクション	表示内容
スコアリング	7観点の配点・スコア・根拠（テーブル形式）
検出された問題	問題の詳細、影響、改善策（重要度順）
改善提案	hook/rule/skill/commandの具体的提案（最大5件）

---

4. 評価の7観点

スコア一覧

観点	配点	評価内容
A. 重複作業	/15	同一ファイル重複読み込み、複数回書き直し、subagentとの作業重複
B. トークン効率	/15	入力トークン量、キャッシュ活用率、大型ツール結果によるコンテキスト肥大
C. 目的外作業	/20	ユーザー指示と無関係なファイル操作、頼まれていない改善・リファクタリング
D. 初動の的確さ	/15	タスクに適した初手を取れているか、不要な前置き作業がないか
E. エラー回復効率	/10	エラー後に原因分析せず同じことをリトライしていないか
F. 不要な探索	/15	目的に不要なファイル読み込み、過剰なGlob/Grep
G. モデル選定	/10	タスク複雑さに対してモデルが適切か、subagentのモデル選定

スコア目安

スコア帯	評価
80〜100	極めて効率的（稀）
70〜79	無駄のないセッション
50〜65	平均的なセッション
30〜49	改善の余地が大きい
0〜29	重大な浪費あり

---

5. 改善提案の活用

提案カテゴリ

評価結果の改善提案は4カテゴリで出力される（優先度順）:

カテゴリ	用途	例
hook	機械的に検出・防止できる問題	「同一ファイル3回以上Readで警告」
rule	Claudeの判断基準に関わる問題	「100行以上のファイルはoffset/limit指定でRead」
skill	複数ステップの定型パターン	「セッション分析→改善提案の一連の流れ」
command	ユーザーが手動実行する定型処理	「/evaluate-session で評価を実行」

改善サイクル

1. セッション完了
    ↓
2. Session Evaluatorで評価
    ↓
3. 改善提案を確認
    ↓
4. 有効な提案をCLAUDE.mdに反映（rule）
   または hooks.json に設定（hook）
    ↓
5. 次回セッションで効果を確認
    ↓
（繰り返し）

---

6. チームでの活用方法

定期振り返り

• 週次のエンジニアMTGで、各自のセッションスコアを共有
• 低スコアのセッションから学びを抽出し、チーム全体のCLAUDE.mdに反映

ベストプラクティス共有

• 高スコア（70+）のセッションのパターンを分析
• 効率的な初動パターン、ツール選択の判断基準をチームで共有

改善提案の蓄積

• Session Evaluatorの改善提案 → /lessons でCLAUDE.mdに蓄積
• PRレビュー指摘 → /review-learn でCLAUDE.mdに蓄積
• 両方の知見がCLAUDE.mdに集約され、次のセッションの品質が向上

---

7. トラブルシューティング

症状	原因	対処
ポートが使用中	他プロセスが占有	npm start -- --port 8080 で別ポートを指定
Analyzeが動かない	Claude CLIが未インストール	claude --version で確認、未インストールなら公式ドキュメント参照
Analyze がタイムアウト	セッションが巨大	Stats Onlyで概要確認、または短いセッションで試す
プロジェクトが表示されない	セッションログがない	~/.claude/projects/ にJSONLファイルが存在するか確認
スコアが低すぎる	正常動作（厳格な評価基準）	平均50〜65点が正常。改善提案に従って改善

---

8. API リファレンス

開発者向け。外部ツールとの連携に使用可能。

メソッド	パス	説明
GET	/api/projects	プロジェクト一覧を取得
GET	/api/sessions/:project	指定プロジェクトのセッション一覧
GET	/api/latest-session	最新セッションを取得
POST	/api/analyze	統計分析のみ実行
POST	/api/evaluate	統計分析 + AI評価を実行
GET	/api/history	評価履歴の取得
DELETE	/api/history	評価履歴の削除

---

9. 関連ツール

ツール	関係
/lessons (lessons-md-manager)	改善提案をCLAUDE.mdに蓄積
/review-learn (review-feedback-learner)	PRレビュー指摘をCLAUDE.mdに蓄積
/rules-merge (rules-split-manager)	分割ルールファイルをCLAUDE.mdにマージ
OpenTelemetry	セッション横断のメトリクス計測（定量的な補完）