自分の今までのClaude Codeとの対話をレビューしてみた

こんにちは、エンジニアの片田です。

前回の田中さんの記事では、「AIが理解しやすい前処理（パターン化、構造化）が大事」という話がありました。非エンジニアの視点からAIエージェントの実業務活用について解説されており、とても興味深い内容でした。

AIエージェントを有効活用するにあたって、その成果物はプロンプトの内容によって大きく左右されます。しかし、恐らく多くのエンジニアが以下のようなプロンプトに関する問題に直面していると思います。

プロンプトの品質を客観的に評価する手段がない
過去の対話から学習・改善する仕組みが整っていない
チーム内でのプロンプト作成ノウハウが属人化している

日々Claude Codeを使っている身としても、田中さんが指摘された前処理の重要性と同様に、「どう指示を出すか」で結果が劇的に変わることを痛感しています。

そこで、プロンプトの改善をするためにも、自分のプロンプトの内容をレビューしてもらいたいと思い、Claude Codeとの対話ログの出力〜分析をしてみることにしました！

Claude Codeの対話記録はどこに保存されている？

まず、対話記録がどこに保存されているかを調査しました。 Claude Codeの対話記録は ~/.claude/projects/ 配下に各プロジェクトごとにJSONL（JSON Lines）形式で保存されています。

JSONLは1行に1つのJSONオブジェクトを格納する形式で、各行が個別の対話メッセージを表現しています。対話セッションごとに分かれて保存されているため、過去の会話を時系列で振り返ることが可能です。

# 実際のファイル構造例
  ~/.claude/projects/
  ├── [USER]-dev-[PROJECT1]-app/
  │   ├── conversation_001.jsonl
  │   ├── conversation_002.jsonl
  │   └── conversation_003.jsonl
  ├── [USER]-dev-[PROJECT2]-web-backend/
  │   ├── session_2024-01-15.jsonl
  │   ├── session_2024-01-16.jsonl
  │   └── session_2024-01-17.jsonl
  ├── [USER]-dev-[PROJECT2]-web-frontend/
  │   ├── chat_history_001.jsonl
  │   └── chat_history_002.jsonl
  └── [USER]-doc-[PROJECT2]/
      ├── claude_chat_001.jsonl
      └── laude_chat_002.jsonl

ただし、JSONLファイルを見ていただければわかりますが、人間が読むには少し辛い形式です。エンジニアがコードレビューするように、対話内容を構造的に分析するには、より読みやすい形式への変換が必要でした。

cclogツールをフォークして分析用ツールを作成

このファイルを人間にも読みやすい形に出力するため、Markdown形式への変換を検討しました。

調査の結果、choplinさんが作成されたcclogというClaude Code専用のログビューアーを発見しました。cclogはCLI上でインタラクティブに対話履歴を閲覧できるツールです。

こちらのcclogをフォークして分析用の出力機能を拡張することにしました。（cclogの詳細な機能、使い方についてはリポジトリのREADMEやZennの解説記事を参照してください）

github.com

私が作成したのがcclog_outputです。元のcclogの履歴閲覧機能に加えて、分析用の出力機能を追加したフォーク版です。

github.com

今回の記事の本題ではありませんが、簡単に機能紹介させてもらいます。

cclog_outputの機能

cclog_outputの機能は以下の通りです

基本的な履歴確認機能

プロジェクトディレクトリで cclog を実行すると履歴画面が開く（フォーク元と同じ）
新機能: 選択した会話履歴をMarkdown形式で出力
出力されたファイルは分析用途に最適化された構造で保存

一括出力機能

cclog export-all-filtered コマンドで、プロジェクトの履歴を一括出力（上限30件）
出力は更新日時の新しい順でソート
バッチ処理での分析ワークフローに対応

# 使用例
cd /path/to/your/project
cclog export-all-filtered
# → claude_chat/ ディレクトリに複数のMarkdownファイルが生成される

サマリー情報付きの出力

出力結果には以下のような情報が含まれます

# Claude Code Session 116929a5-7d54-42de-bb12-9c4464ef4680 (Filtered)

**Date**: 2025-08-28
**Duration**: 8m
**Messages**: 68
**Total Messages**: 46
**User Messages**: 13
**Assistant Messages**: 33

---

日付、セッション時間、やり取りの回数などもサマリ出力できるようにしています。これにより、どの程度の時間をかけてどんなやり取りをしていたかが一目で分かります。

実際の出力例

先程のサマリ出力の後には、会話ログが表示されます。 cclog_output の作成時にやり取りした結果を出力してみました。

User (13:19:22)

cclog export-all-filteredを実行すると過去どのくらいの会話履歴を出力できますか？ @cclog_helper.py や @cclog.sh を参照して回答してください

Assistant (13:19:37)

・・・

cclog export-all-filteredを実行すると、デフォルトで最新30個の会話セッションが出力されます。

コードを確認したところ：

cclog.sh:274行目で：
local project_dir=$(echo "$target_dir" | sed 's/\//-/g; s/\./-/g; s/_/-/g')
cclog.sh:286行目で：
if "$CCLOG_PYTHON" "$CCLOG_HELPER_SCRIPT" export-all-filtered "$claude_projects_dir" "claude_chat"; then
cclog_helper.py:1107行目で：
limit = int(sys.argv[4]) if len(sys.argv) >= 5 else 30
cclog_helper.py:952行目のexport_all_sessions_filtered関数で：
def export_all_sessions_filtered(claude_projects_dir, output_dir="claude_chat", limit=30):
また、cclog_helper.py:980-984行目で：
# Sort files by modification time (newest first) and limit to specified number
jsonl_files.sort(key=lambda f: f.stat().st_mtime, reverse=True)

if len(jsonl_files) > limit:
    print(f"Found {len(jsonl_files)} session files, processing latest {limit}...")
    jsonl_files = jsonl_files[:limit]
つまり：

デフォルト制限：30セッション

ソート順：更新日時の新しい順

出力先：claude_chatディレクトリ

形式：フィルタリング済みMarkdown（空メッセージを除外）

全セッションを出力したい場合は、limitパラメータを大きな値に変更する必要があります。

・・・

プロンプトの特徴や、どんな情報を参照しているか、AIがどう応答しているかなど、後から振り返ると結構面白い発見があります。

プロンプトの分析

さて、準備が整ったので出力したmdファイルをもとにプロンプトの分析を行っていきたいと思います。今回はそれぞれのプロンプトをレビューするような形で分析を行います。具体的にはこのような形のスラッシュコマンドを作成しました

---
allowed-tools: Read(*.md), Fetch(*)
description: "AIエージェントとの対話ログの概要説明と品質評価をチェックリストを用いてレビューします"
---

# AIコーディング対話品質チェックリスト

@claude_chat/$ARGUMENTS の会話ログについて、以下のチェックリストを用いて評価してください。
結果では `✅ 実施済み項目（チェックあり） ` と `❌ 未実施項目（チェックなし）` をそれぞれ分類して記載してください。

## 対話サマリー
**プロジェクト名**: _______________
**実装内容**: _______________
**使用AI**: _______________
**対話日時**: _______________

## 品質チェック項目

### 🎯 コミュニケーション品質
- [ ] 質問は5W1H（What/Why/When/Where/Who/How）が明確
- [ ] 技術的コンテキスト（言語、フレームワーク、バージョン）を最初に提供
- [ ] エラーメッセージは省略せず完全に共有
- [ ] 期待する出力形式を具体例付きで説明
- [ ] AIの回答を正しく理解し、適切にフォローアップ

### 📋 開発プロセス
- [ ] 要件定義（またはゴール設定）から開始
- [ ] 機能を適切な粒度でタスク分解
- [ ] 仕様書（または設計意図）を文書化
- [ ] インターフェース設計を先に確定

### 🧪 テスト戦略
- [ ] 仕様書からテストケースを導出
- [ ] エッジケースを含む網羅的なテスト設計
- [ ] テストコードを実装前に作成依頼
- [ ] テスト実行結果を確認

### 🔧 品質保証
- [ ] コードスタイルの統一（リンター/フォーマッター）
- [ ] 不要コードの特定と削除
- [ ] 複雑度の評価とリファクタリング
- [ ] パフォーマンス考慮事項の確認
- [ ] セキュリティ観点でのレビュー

### 📊 効率性指標
| 指標 | 値 | 目標値 | 評価 |
|------|-----|--------|------|
| 問題解決までのターン数 | ___ | <10 | ⭕/❌ |
| 初回指示での成功 | ___% | >70% | ⭕/❌ |
| コード修正回数 | ___ | <3 | ⭕/❌ |
| 要件の手戻り回数 | ___ | 0 | ⭕/❌ |

### 💡 改善提案
1. 最も改善が必要な領域：
2. 次回から実践すべきこと：
3. 特に良かった点：

代表的な観点は以下のとおりです。

対話内容の概要
質問の適切さ
必要なコンテキストを十分に提供できているのか
正しい言葉で表現ができているか
テストケースを網羅的に書かせているのか
効率的に対話できているのか、ターン数や修正回数は過剰ではないか

他にも構造的、成熟度モデル的な形式でのレビュープロンプトも作ってみました。それぞれ cclog_outputの.claude/command に配置してみました。

分析結果

結果はこんな感じでした。

  対話サマリー

  プロジェクト名: cclog_output (Claude Code Log Browser)
  実装内容: cclog.shのディレクトリエンコーディングバグ修正とテストケース作成
  使用AI: Claude (セッション032d535c-9cfd-4cf5-b034-3ac3b5785401)
  対話日時: 2025-08-28 07:41-07:50 (約8分)

  品質チェック項目

  🎯 コミュニケーション品質

  ✅ 実施済み項目（5/5）
  - ✅ 質問は5W1H（What/Why/When/Where/Who/How）が明確
  - ✅ 技術的コンテキスト（言語、フレームワーク、バージョン）を最初に提供
  - ✅ エラーメッセージは省略せず完全に共有
  - ✅ 期待する出力形式を具体例付きで説明
  - ✅ AIの回答を正しく理解し、適切にフォローアップ

  📋 開発プロセス

  ✅ 実施済み項目（4/4）
  - ✅ 要件定義（またはゴール設定）から開始
  - ✅ 機能を適切な粒度でタスク分解
  - ✅ 仕様書（または設計意図）を文書化
  - ✅ インターフェース設計を先に確定

  🧪 テスト戦略

  ✅ 実施済み項目（4/4）
  - ✅ 仕様書からテストケースを導出
  - ✅ エッジケースを含む網羅的なテスト設計
  - ✅ テストコードを実装前に作成依頼
  - ✅ テスト実行結果を確認

  🔧 品質保証

  ✅ 実施済み項目（4/5）
  - ✅ コードスタイルの統一（リンター/フォーマッター）
  - ✅ 不要コードの特定と削除
  - ✅ 複雑度の評価とリファクタリング
  - ✅ パフォーマンス考慮事項の確認
  - ❌ セキュリティ観点でのレビュー

  📊 効率性指標

  | 指標          | 値    | 目標値  | 評価  |
  |-------------|------|------|-----|
  | 問題解決までのターン数 | 8    | <10  | ⭕   |
  | 初回指示での成功    | 100% | >70% | ⭕   |
  | コード修正回数     | 1    | <3   | ⭕   |
  | 要件の手戻り回数    | 0    | 0    | ⭕   |

  💡 改善提案

  1. 最も改善が必要な領域:
  セキュリティレビュー（今回は該当しないが、今後shellスクリプトやファイル操作時は要考慮）
  2. 次回から実践すべきこと:
    - shellスクリプト修正時は入力値検証の確認
    - より複雑な修正の場合は段階的なリリース計画
  3. 特に良かった点:
    - 問題の根本原因特定が迅速かつ正確
    - 修正後の包括的テストケース作成
    - ユーザー確認を適切に取る運用プロセス
    - 効率的な開発フロー（8分で完了）

  総合評価: 17/18項目達成（94.4%）- 非常に高品質な対話

このレビュー結果から、成功した対話の特徴が定量的に把握できました。一方で、評価が高すぎる可能性もあるため、うまくいかなかった対話のレビューも実施しました。

  対話サマリー

  プロジェクト名: ***EVアプリ
  実装内容: GitHub Actionでの firebase_cli_token を ADC に変更する設定調査・提案
  使用AI: Claude Code
  対話日時: 2025-08-06 01:27-01:35 (7分)

  品質チェック項目

  ✅ 実施済み項目（チェックあり）

  - ✅ 技術的コンテキスト（GitHub Actions、Firebase、fastlane）を最初に提供
  - ✅ 要件定義（firebase_cli_tokenをADCに変更可能か調査）から開始
  - ✅ 機能を適切な粒度でタスク分解（3段階の作業計画）
  - ✅ AIの回答を正しく理解し、適切にフォローアップ

  ❌ 未実施項目（チェックなし）

  - ❌ エラーメッセージは省略せず完全に共有（エラーが発生していない）
  - ❌ 期待する出力形式を具体例付きで説明
  - ❌ 仕様書（または設計意図）を文書化
  - ❌ インターフェース設計を先に確定
  - ❌ 仕様書からテストケースを導出
  - ❌ エッジケースを含む網羅的なテスト設計
  - ❌ テストコードを実装前に作成依頼
  - ❌ テスト実行結果を確認
  - ❌ コードスタイルの統一（リンター/フォーマッター）
  - ❌ 不要コードの特定と削除
  - ❌ 複雑度の評価とリファクタリング
  - ❌ パフォーマンス考慮事項の確認
  - ❌ セキュリティ観点でのレビュー

  📊 効率性指標

  | 指標          | 値    | 目標値  | 評価  |
  |-------------|------|------|-----|
  | 問題解決までのターン数 | 3    | <10  | ⭕   |
  | 初回指示での成功    | 100% | >70% | ⭕   |
  | コード修正回数     | 0    | <3   | ⭕   |
  | 要件の手戻り回数    | 0    | 0    | ⭕   |

  💡 改善提案

  1. 最も改善が必要な領域: テスト戦略・品質保証プロセスが完全に欠如
  2. 次回から実践すべきこと:
    - 設定変更の影響範囲分析とテスト計画策定
    - 複数環境での動作確認手順の明確化
    - セキュリティ観点でのADC設定レビュー
  3. 特に良かった点:
    - 明確な作業計画の提示と承認フロー
    - 適切なツール選択（Grep、WebSearch、WebFetch）
    - 調査結果の整理と提案内容の構造化

  総評: 調査・提案フェーズとしては効率的だが、実装・テスト・品質保証プロセスが不十分。本格実装時にはより包括的なアプローチが必要。

このレビューでは、テスト戦略や品質保証の不足が明確に指摘されていますね。

分析の効果

対話品質の客観的な評価が可能
改善すべき領域の特定（テスト戦略、セキュリティレビューなど）
継続的改善のためのアクションアイテムの自動生成

この程度の精度があれば、個人のセルフチェックからチームでのコードレビューまで、実用的な改善サイクルを回すことができると判断しました。

今後の活用計画

今回作成したcclog_outputとプロンプト分析の仕組みを活用して、以下のような取り組みを個人・チーム双方で継続的に行っていきたいと考えています。

個人レベルでの改善活動

まずは自分自身のプロンプト品質向上に向けた継続的な改善サイクルを確立したいです。

失敗パターンの蓄積: うまくいかなかった対話を体系的に分析し、再発防止策を策定
成功パターンのテンプレート化: 効果的だったプロンプトをテンプレート化して再利用
メタ認知の強化: なぜそのプロンプトを書いたのか、期待した結果と実際の結果の差分分析

チーム・組織レベルでの横展開

個人での学びを組織全体で共有し、チーム全体のAI活用による成果物のレベル底上げを狙います。

ナレッジ共有: 効果的なプロンプトパターンのチーム内共有
標準化: 分析結果をベストプラクティスとしてガイドライン化

より深い分析への発展

定量的なアプローチを取り入れていきたいと考えています。

定量分析: プロンプトの語彙・文体・構造の数値化
相関調査: プロンプト特徴とコード品質の関係性分析
タスク別最適化: 開発タスク種別ごとの効果的パターン抽出

まとめ

今回、Claude Codeとの対話ログを分析するツールチェーンとプロセスを構築することで、AIエージェント活用における「メタ認知」を技術的に実現できました。

1 対話品質の定量的評価システム

18項目のチェックリストによる客観的評価
94.4%の品質スコアという具体的な指標化
効率性指標（ターン数、修正回数等）の数値的管理

2 継続的改善のためのツール

cclog_outputによる対話ログの構造化出力（JSONL → Markdown変換）
Claude Codeスラッシュコマンドによる自動レビュー分析
セッション時間、メッセージ数等のメタデータ自動抽出

これまで自分でプロンプトを入力してきたり、分析をしてきた結果を通して、個人的にAIエージェントとの対話は「技術スキル」として体系的に向上させることができると思います。コードの品質を継続的に改善するように、プロンプトの品質も定量的に管理・改善していく文化を築いていきましょう！

次回は同じチームのエンジニアの山口さんが書いてくださる予定です。お楽しみに！

ENECHANGE Developer Blog

ENECHANGE開発者ブログ