エージェント自己評価 は何をしますか？
複雑なタスクを完了した後、エージェントは構造化された5軸ルーブリックに基づいて自身の出力を評価します。これは合格/不合格のゲートではなく、ユーザーが指摘する前に欠落、過信、改善領域を発見するための意図的な振り返りステップです。
いつアクティブにするか
- 3ファイル以上、または50行以上のコードを書いた後
- マルチステップのワークフロー（実装→テスト→レビュー）を完了した後
- デバッグセッションで3回以上の試行を行った後
- 設計文書、アーキテクチャ決定、または文章による分析を生成した後
- ユーザーが「それはどれくらい良かった？」や「自分を評価して」と尋ねたとき
- 任意のセッション終了フック時（設定されている場合 —
references/hook-integration.mdを参照）
中核概念
5つの評価軸
| 軸 | 質問 | 何を捉えるか |
|---|---|---|
| 精度 | 事実、主張、出力は正しいか？ | 幻覚、間違ったAPI名、誤った構文、虚偽の記述 |
| 完全性 | ユーザーが求めたすべてをカバーしているか？ | 見逃したエッジケース、未処理のエラーパス、忘れられた要件、スキップされたサブタスク |
| 明確性 | 説明は理解しやすく、構造化されているか？ | 混乱を招く説明、定義なしの専門用語、文脈の欠落、だらだらした記述 |
| 実行可能性 | ユーザーは出力をすぐに行動に移せるか？ | 曖昧な提案、不足している手順、「〜すべき」と言うだけで方法を示していない、検証方法がない |
| 簡潔性 | 最小限の単語/トークンで済んでいるか？ | 冗長、過剰説明、ユーザーの質問の逐語的反復、余分な内容 |
スコアリング基準
5 — 卓越：合理的な改善の余地なし
4 — 良好：細かい点のみ、実質的な欠落なし
3 — 適切：リクエストを満たしているが、少なくとも1つの軸に顕著な弱点がある
2 — 弱い：ユーザービリティや正確性に影響する明らかな欠落がある
1 — 不十分：リクエストを根本的に満たしていない、または重大なエラーを含む
証拠ルール
4以下のスコアには、必ず具体的な証拠を提示しなければなりません。スコア3に対して「改善できる」と言うだけでは不十分です。何が欠けているか、何が間違っているかを正確に述べる必要があります。モットー：「欠落を示せ、名前を挙げるだけではダメ。」
ワークフロー
ステップ1: 素材の収集
評価に必要なものを集めます：
- 元のユーザーリクエスト（会話から読み返す）
- あなたの最終応答/出力（成果物）
- 正確性を検証するツール出力（テスト結果、終了コード、lint出力）
- タスク中に受けたユーザーフィードバック（修正指示、「もう一度」、「それは違う」など）
ステップ2: 各軸を独立してスコアリング
5つの軸を1つずつ処理します。各軸について：
- 軸の質問を読む
- 出力内で証拠（または証拠の欠如）を見つける
- スコア1〜5を割り当てる
- スコアが5未満の場合、欠落を示す一文の改善メモを書く
最初に頭の中で平均スコアを計算してから逆算してはいけません。各軸を新鮮な状態でスコアリングします。
ステップ3: 評価レポートの作成
templates/evaluation-report.md のテンプレートを使用します。レポートには以下を含める必要があります：
- 一行要約
- 5軸スコアカード（各軸のスコア＋証拠）
- 全体スコア（単純平均、小数点第1位に四捨五入）
- 影響度順にランク付けされた1〜3つの具体的な改善点
- 自己チェック：「ユーザーはこの評価に同意するだろうか？」
ステップ4: 改善の適用
いずれかの軸が3以下だった場合：
- どう異なる対応をするかを記述する
- 欠落が30秒以内に修正可能な場合（リンクの欠落、不明瞭な表現）、今すぐ修正する
- 欠落に手戻りが必要な場合、明示的にフラグを立てる：「この軸は [理由] で [証拠] のため [スコア] でした。[具体的な修正] で再実行すれば、スコアは [スコア] に上がるでしょう。」
コード例
例: 良い評価（スコア4以上）
タスク: HTTPクライアントにリトライロジックを追加
スコアカード:
精度: 5 — すべてのAPI呼び出しが正しい。確認済み: リトライは
指数バックオフを使用。幻覚メソッドなし。
完全性: 4 — ハッピーパス＋3つのエラーケースをカバー。欠落:
ハング接続のタイムアウト処理。
明確性: 5 — コードコメントがバックオフ計算式を説明。
PR説明がこの動機となったインシデントにリンク。
実行可能性:5 — 単一マージ。後続タスクなし。テスト合格。
簡潔性: 4 — 合計47行。リトライループをヘルパーに抽出すれば
約8行削減可能。
全体スコア: 4.6 — 1つの欠落（タイムアウト処理）。マージ前に修正。
例: 弱い評価（スコア2〜3）
タスク: HTTPクライアントにリトライロジックを追加
スコアカード:
精度: 2 — 当コードベースと一致しないurllib3を使用。
間違ったライブラリ。
完全性: 3 — GETで動作。POST/PUT未対応（ユーザーは
「すべてのHTTPリクエスト」と指定）。
明確性: 4 — コードは読みやすい。適切な変数名。
実行可能性:2 — 「テストを追加」と述べたがテストファイル未作成。
ユーザーがマージ前にテストを書く必要あり。
簡潔性: 3 — 120行。リトライ設定が1つの共有RetryConfigオブジェクト
ではなく3箇所で重複。
全体スコア: 2.8 — 間違ったライブラリ。httpxで書き直しが必要。
まず精度を修正（httpxに切り替え）、次にすべてのHTTPメソッドに
拡張、最後に設定を統合。
アンチパターン
「全部5」
失敗: 精度: 5 — すべて良好。
完全性: 5 — すべてカバー済み。
明確性: 5 — 明確。
証拠が提示されていない。これは自己満足であり、評価ではない。本当の5は、改善すべき点がないことを証明する必要があります。
スコープ拡大で過度に減点
失敗: 完全性: 2 — WebSocket接続やgRPCストリーミングを
処理していない（ユーザーはこれらを要求していない）
ユーザーが実際に要求したことに対してのみ評価し、さらに構築できたかもしれないことに対して評価してはいけません。
評価を再議論に使う
失敗: 「前に言った通り、このアプローチは間違っています。スコア: 1」
評価は提供された出力についてであり、すでに決定された設計上の決定を再議論するものではありません。アプローチが間違っていた場合は、成果物の前に指摘されるべきでした。
個人的好みと客観的欠落の混同
失敗: 「スコア: 3。Pythonデコレータが好きではない。」
「好きではない」は証拠ではありません。可読性、テスト容易性、正確性に関する具体的な懸念を挙げるか、スコアを4以上にしてください。
ベストプラクティス
- プロセスではなく出力を評価する。 ユーザーが気にするのは、どれだけの反復を経たかではなく、何を納品したかです。
- 弱い軸ごとに改善点は1つだけ。 1つの軸に5つも挙げず、最も影響の大きい欠落を選びましょう。
- 改善点をユーザーへの影響に結び付ける。 「エラー処理がないとユーザーのAPI呼び出しが静かにクラッシュする」は「エラー処理を追加」よりも優れています。
- 「修正済み」の状態を具体的に示す。 「リトライ用に設定されたhttpxトランスポートで再実行」は「ライブラリの問題を修正」よりも優れています。
- ツール出力を証拠として使う。 テストが通ったならそれを引用し、lintがクリーンならそれを引用しましょう。推測せず、grepで証明を探しましょう。
- 欠落が見つからないなら、もっと努力する。 全5軸で完璧なスコアは稀です。自問しましょう：「自分がユーザーだったら、この出力の何にイライラするだろうか？」
関連スキル
agent-eval— ベンチマークタスクにおける異なるコーディングエージェントの直接比較verification-loop— 期待される結果に対する出力の系統的検証security-review— セキュリティに焦点を当てたコードレビューチェックリスト