【Claude Code】プロンプトのスキルアップに役立つプロンプト評価カスタムコマンド

Claude Code用のカスタムコマンドを使ったプロンプトの質を点数化して改善ポイントを明確にする方法を紹介します。
プロンプトを「見える化」して改善サイクルを回すことで、生成AIとの協働をより効果的に進められるようになります。

1. はじめに

生成AIを活用する場面が増えるにつれて、プロンプトの書き方が成果を大きく左右するようになってきました。しかし、日々使っている中で次のような課題に直面することがありました。

• 「なんとなく」で依頼してしまい、期待と違う回答が返ってくる
• 完了条件が曖昧で、「できました」と言われても達成度が判断しづらい
• うまくいく時と進まない時の差がどこにあるのか掴めない

こうした問題の背景には、プロンプトの質を客観的に評価する仕組みがないという課題があります。生成AIの能力を効果的に引き出すには、プロンプト作成そのものをスキルとして鍛えていく必要がありますが、自分のプロンプトがどの程度妥当なのか、どこを改善すべきなのかといった 「正解のない問い」 に向き合うのは容易ではありません。

そこで、プロンプトを客観的に評価し、改善のヒントが得られる仕組みが必要だと考えました。その想いから作ったのが、プロンプトの良し悪しを見える化し、改善サイクルを回せるようにするカスタムコマンド「prompt-review」です。

2. 作ったもの：prompt-reviewコマンド

プロンプトの質を客観的に評価するために作成したのが、Claude Code用のカスタムコマンド「prompt-review」です。生成AIとの直近の会話履歴を読み取り、あらかじめ定義した評価フレームワークに基づいてスコアリングを行い、改善のヒントとなるフィードバックを提示します。

このコマンドの特徴は、「ユーザーがどんな指示を出したか」を点数化し、その良し悪しを定量的に把握できることです。評価対象はAIの返答ではなく、あくまで“人間が出したプロンプトそのもの”。そのため、プロンプト改善に直結する学習が可能になります。

【機能概要】

• Claude Codeの最新セッションJSONLから会話履歴を自動検出
• 末尾最大2000行のやり取りを読み込み、評価対象のプロンプトを抽出
• 「プロンプト評価フレームワーク（7観点×10点）」に基づきスコアリング
• 良かった点と改善すべき点を最大5つずつ提示
• Markdown形式で読みやすく出力

プロンプトの改善は「何となく良くする」ではなく、数値と根拠に基づいて振り返ることで、改善サイクルがより回しやすくなります。

【評価に使用する7つの観点】

評価フレームワークはテンプレートとして分離し、プロジェクトごとにカスタマイズできるようにしています。採点項目は、プロンプトの品質に大きく影響する次の7つです。

1. 目的・Done定義
2. 制約の具体性
3. 文脈共有
4. 段階的進行
5. デバッグ／検証
6. リファクタ安全／セキュリティ
7. スコープ管理

それぞれ0〜10点で採点し、合計70点としてスコア化します。

【出力内容】
評価結果は次の形式で生成されます。

• 総評（1〜3行）
• 7観点の点数と根拠の表
• 良い点（最大5つ）
• 改善すべき点と改善案（最大5つ）

ユーザーは、このフィードバックをもとに次のプロンプトを書き直し、改善の効果を確認できます。
このように、prompt-reviewコマンドは「プロンプトの品質を見える化し、継続的に高めていくためのツール」として機能するよう設計しています。

※下記のトグルを展開すると内容が確認できます。

カスタムコマンド

# prompt-review コマンド

## 概要
Claude Codeとの現在のセッションの会話履歴を通じて、ユーザのプロンプト評価を行い、プロンプトのスコア化と適切なフィードバックを提供します。

## 目的
Claude Codeの**現在（最新）のセッションJSONL**から、直近の会話履歴を取得し、  
「プロンプト評価フレームワーク」に沿って**0〜10点×7観点（70点満点）**で採点 & 端的なフィードバックを出力します。

## 対象ファイル（自動検出）
`~/.claude/projects/<project-hash>/*.jsonl` のうち**更新時刻が最新**の1ファイル。  
サイズ制約に合わせ、**末尾N行（既定2000）**のみを読み込みます。

## プロンプト評価フレームワーク
@.claude/templates/prompt_review_framework.md

## 振る舞い
- 最新の会話履歴ファイルの末尾2000行を参照する
```bash
ls -t ~/.claude/projects/<project-hash>/*.jsonl 2>/dev/null | head -1 | xargs tail -2000
```
- 「プロンプト評価フレームワーク」に従ってプロンプトのスコアリングとフィードバックを提供する

## 出力要件
- 「プロンプト評価フレームワーク」に従い、**各観点0〜10点**の配点と**合計点（/70）**を算出すること。
- **良い点は最大5つ、悪い点（改善案付き）も最大5つ**に絞って、簡潔に示すこと。

## 出力例
- 「プロンプト評価フレームワーク」内の出力例に従ってマークダウン形式で出力してください。

<project-hash>について
次の章「3. 実装のポイント」の【会話履歴の自動検出とロード】で解説しています

評価フレームワークテンプレート

あなたは「AIコーディングエージェントとの協働評価」の専門レビュワーです。
以下のチャット履歴に基づき、**ユーザー（人間）がAIコーディングエージェントへ出した指示**の質のみを評価してください。
エージェントの出力品質には引きずられないでください。

# 採点方針（各0〜10点・同配点）
評価観点（7項目）
1) 目的・Done定義の明確さ  
2) 制約の具体性（技術/ビジネス/非機能）  
3) 文脈共有（ファイル/入出力例/ログ等）  
4) 段階的進行（タスク分割・進め方）  
5) デバッグ/検証（ログ活用・テスト方針/コマンド）  
6) リファクタ安全/セキュリティ（保護領域・秘匿情報）  
7) スコープ管理（要求の境界・依頼の膨張防止）

スコア目安：10=具体かつ十分、7=概ね良いが抜けあり、5=半分不足、3=大きく不足、0=未提示。

# 出力仕様（Markdownのみ）
## 総評
（全体の印象と最大の改善ポイントを1〜3行で）

## スコア
- 合計点: **X/70**
| 指標 | 点数(0-10) | 根拠（簡潔に） |
|---|---:|---|
| 目的・Done定義 |  |  |
| 制約の具体性 |  |  |
| 文脈共有 |  |  |
| 段階的進行 |  |  |
| デバッグ/検証 |  |  |
| リファクタ安全/セキュリティ |  |  |
| スコープ管理 |  |  |

## 良い点（最大5）
- 

## 悪い点と改善案（最大5）
- **問題:**  
  **改善案:** 

（重大度の高い順に最大5件まで）

## 出力例
```
# 総評
要求の意図はおおむね明確で、着手順序も示されていますが、Done定義や非機能・制約の具体化が弱く、検証・デバッグ手順が曖昧です。
最大の改善ポイントは「完了条件と検証方法（コマンド/期待出力）の明文化」です。

## スコア
- 合計点: **45/70**
| 指標 | 点数(0-10) | 根拠（簡潔に） |
|---|---:|---|
| 目的・Done定義 | 6 | 目的は述べられるが、受け入れ基準や検証方法が未記載 |
| 制約の具体性 | 7 | 使用技術の指定はあるが、性能/エラーハンドリング/運用制約が不足 |
| 文脈共有 | 6 | 対象ディレクトリや主要ファイルは示されるが、入出力例が足りない |
| 段階的進行 | 6 | 大枠の進め方はあるが、チェックポイントの粒度が粗い |
| デバッグ/検証 | 5 | ログ確認は示唆されるが、再現手順やテストコマンドが不明 |
| リファクタ安全/セキュリティ | 7 | 秘匿情報の扱いは配慮あり、保護領域やロールバック指針は弱い |
| スコープ管理 | 8 | 依頼範囲の境界が明確でスコープの膨張を抑制できている |

## 良い点
- 目的が短文で明快に表現されている  
- 使用技術や構成（例：FW/DB/配備先）が指定されている  
- 作業順序の概略（設計→実装→テスト）が提示されている  
- セキュリティ上の配慮（秘密情報の非共有など）に触れている  
- 対象範囲の線引きが比較的明確で依頼が肥大化しにくい  

## 悪い点と改善案
- **問題:** Done定義が抽象的で完了判定ができない  
  **改善案:** 「成功条件：`/api/login` に対し正しい資格情報で 200 & JSON `{ok:true}`、誤りで 401。ログにWARN以上が出ない」を明記

- **問題:** 非機能要件（性能・可観測性・エラー時挙動）が未整理  
  **改善案:** 「p95 レイテンシ < 300ms、リトライ最大3回、構造化ログ（level,msg,requestId）出力」を追加

- **問題:** 入出力例・再現手順が不足し、誤解が生じやすい  
  **改善案:** リクエスト/レスポンスの最小例、失敗ケース、サンプルログを箇条書きで添付

- **問題:** デバッグ・検証のコマンドが無くレビューが難しい  
  **改善案:** 「検証コマンド：`pnpm test`, `curl ...`, `tail -f logs/app.log`」を明記し期待出力を併記

- **問題:** リファクタ安全策が曖昧（影響範囲の保護が無い）  
  **改善案:** 「`// PROTECTED REGION` 内は変更不可。失敗時は `git restore :/auth/*` でロールバック」を明記

```

## 例外処理
- 対象ファイルの読み込みに失敗したり、対象ファイルの内容が少なすぎてプロンプト評価ができない、または評価対象となるプロンプトが見当たらない場合は、その旨が分かるメッセージを出力し、評価はスキップしてください。

### 例外時の出力例
```
# 総評
評価対象となるプロンプトが存在しません。
```

3. 実装のポイント

prompt-reviewコマンドの実装で重視したのは、評価ロジックをテンプレートとして分離することと、会話履歴（JSONL）の自動検出と読み取りをシンプルに行えるようにすることの2点です。これにより、プロンプト評価の仕組みを柔軟かつ拡張しやすい構成にしています。

【評価フレームワークをテンプレート化して分離】
プロンプト評価のルールはテンプレートファイルに切り出し、コマンド本体から独立させています。
こうすることで、以下のメリットがあります。

• 評価基準だけを簡単に差し替えられる
• プロジェクトごとに異なる採点ルールを利用できる
• コマンドのロジックと評価内容が混ざらず、読みやすい
• 将来、評価項目を追加・変更する際もテンプレート側の編集だけで済む

【会話履歴の自動検出とロード】
Claude Codeは、プロジェクトごとにセッション履歴を次のような構造で保存します。

例: 現在のプロジェクトパスが/home/username/dev/project/の場合
Claude Code内部のセッションディレクトリは~/.claude/projects/-home-username-dev-web-project/のような形で作成されます。
このディレクトリ配下には、セッションごとに.jsonlファイルが生成されます。

prompt-reviewでは、以下のコマンドで 最新版のセッションJSONLを自動的に検出し、その末尾2000行だけを読み込むようにしています。

ls -t ~/.claude/projects/-home-username-dev-web-project/*.jsonl 2>/dev/null | head -1 | xargs tail -2000

採用している理由は次の通りです。

• 最新更新順（ls -t）で並べるだけで最も最近のセッションが特定できる
• tailで必要な範囲だけ読み込むためパフォーマンスが安定
• Claude Codeの内部仕様に依存しつつも、パス加工の手間を最小化できる

これにより、ユーザーは特別な設定をせずに prompt-review を実行するだけで、常に“今作業しているセッション”が評価されるという使い勝手を実現しています。

4. 使ってみた例：ToDoアプリのプロンプトを評価してみる

ここでは実際に「prompt-review」コマンドを使い、バニラJSのToDoアプリを題材にしたプロンプトを評価してみた結果を紹介します。
同じアプリを題材にしていても、プロンプトの書き方によって AIの理解度やアウトプット品質がどれだけ変わるのかを、評価スコアを通じて確認できます。

試したプロンプト

今回評価したのは次の２つの異なるプロンプトです。

• 不十分プロンプト（低スコア例）
  • 最低限の指示のみで、完了条件・制約・検証方法が曖昧

    HTML と CSS と JavaScript で動く ToDo アプリを作ってください。
    タスクを追加して、一覧に出せるようにして、削除もできるようにしたいです。
    簡単なデザインも付けてもらえるとうれしいです。
    

• 改善プロンプト（高スコア例）
  • プロンプト評価フレームワークの7観点に沿って整理

    ToDo アプリを HTML / CSS / JavaScript（バニラJS）で実装してください。
    以下の要件を満たす形で、index.html / style.css / script.js の3ファイルに分割してコードを生成してください。
    ## 目的・Done定義
    - タスクの追加・表示・削除ができること。
    - 画面リロードしてもタスクが保持されること（localStorage 利用）。
    - 削除後にリストが正しく再描画されること。
    
    ## UI仕様
    - 上部にテキスト入力欄と「追加」ボタン。
    - 下部にタスク一覧（ul/li）。
    - タスク横に「削除」ボタン。
    - 最低限のシンプルなデザイン（中央寄せ、幅は最大400px）。
    
    ## 制約
    - フレームワーク不使用（バニラJS のみ）。
    - script.js では querySelector を用いて DOM 操作を行う。
    - 変数名・関数名は役割が分かる名前にする。
    
    ## 段階的進行
    1. index.html の基本構造  
    2. style.css のレイアウト  
    3. script.js（追加・削除・再描画・localStorage）の実装  
    の順で出力すること。
    
    ## 検証方法
    - タスクを入力して「追加」を押す→リストに反映される。
    - 削除ボタンを押す→該当タスクが削除される。
    - ページ再読み込み後もタスクが保持されている。
    
    ## スコープ
    - 今回は「追加・削除・保存」の基本機能のみを対象とし、編集機能は対象外。
    

どちらも「HTML / CSS / JavaScript で実装するToDoアプリ」を依頼する内容ですが、記述の丁寧さと具体性のレベルが大きく異なっています。

生成結果とプロンプト評価

不十分プロンプト：28点

十分プロンプト：60点

わかったこと

2つのプロンプトを比較すると、点数差（28点 → 60点）は「曖昧さの量」の差そのものであることが分かりました。
不十分プロンプトでは、Done定義・デザイン・検証手順・仕様の細部が曖昧なまま残っており、AI が自主判断する領域が広くなっていました。その結果、実装内容にもブレが生まれやすく、評価スコアも低めになります。

一方で十分プロンプトは、UI仕様・制約・実装手順・検証方法・スコープが整理されており、AI が迷わず作業できる状態になっていました。特に、完了条件と検証方法の明記が大きくスコアを押し上げています。

5. まとめ

本記事では、Claude Code用に作成した「prompt-review」コマンドを通じて、プロンプト改善の効果を定量的に確認できることを紹介しました。プロンプトの良し悪しは漠然としがちですが、評価基準をもとに点数化することで、どこを伸ばすべきかが明確になります。

実際に試した不十分プロンプトと十分プロンプトの比較では、Done定義・仕様の具体化・検証方法の明記といった基本的なポイントを押さえることにより、スコアと生成結果が大きく変わることが分かりました。

生成AIとより効果的に協働していくためには、プロンプトを改善し続けるサイクルが欠かせません。prompt-reviewは、その振り返りを支援するツールとして役立ち、学習効率や開発速度を高めてくれます。

今後は、評価項目のカスタマイズやプロジェクトごとのテンプレート化など、用途に応じたアレンジも可能です。プロンプトエンジニアリングの継続的な改善に、ぜひ活用してみてください。

KIYOラーニング株式会社について

当社のビジョンは『世界一「学びやすく、分かりやすく、続けやすい」学習手段を提供する』ことです。革新的な教育サービスを作り成長させていく事で、オンライン教育分野でナンバーワンの存在となり、世界に展開していくことを目指しています。

プロダクト

• スタディング：「学びやすく・わかりやすく・続けやすい」オンライン資格対策講座
• スタディングキャリア：資格取得者の仕事探しやキャリア形成を支援する転職サービス
• AirCourse：受け放題の動画研修がついたeラーニングシステム（LMS）

KIYOラーニング株式会社では一緒に働く仲間を募集しています