エージェント自己評価
複雑なタスクを完了した後、エージェントは一時停止し、構造化された5軸の評価基準に基づいて自身の出力を評価します。これは合格/不合格のゲートではありません。ユーザーが指摘する前に、見落としを発見し、過信にフラグを立て、改善点を明らかにするための意図的な内省ステップです。
有効化のタイミング
- 3ファイル以上、または50行以上にわたるコードを記述した後
- マルチステップのワークフロー（実装 → テスト → レビュー）を完了した後
- 3回以上の試行を伴うデバッグセッションの後
- 設計ドキュメント、アーキテクチャ上の決定、または文章による分析を作成した後
- ユーザーが「それはどれくらい良かった？」や「自分を評価して」と尋ねたとき
- 任意のセッションのStopフックの終了時（設定されている場合。
references/hook-integration.mdを参照）
コアコンセプト
5つの評価軸
| 軸 | 質問 | 捕捉する内容 |
|---|---|---|
| 正確性 | 事実、主張、出力は正しいか？ | 幻覚、間違ったAPI名、誤った構文、虚偽の記述 |
| 完全性 | ユーザーが依頼したすべてを網羅しているか？ | 見落とされたエッジケース、未処理のエラーパス、忘れられた要件、スキップされたサブタスク |
| 明確性 | 説明は理解しやすく、構造化されているか？ | わかりにくい説明、定義なしの専門用語、不足しているコンテキスト、とりとめのない話 |
| 実行可能性 | ユーザーは出力に基づいてすぐに行動できるか？ | 曖昧な提案、不足している手順、「あなたはXすべき」という方法の提示なし、検証パスがない |
| 簡潔性 | 必要最小限の単語/トークンを使用したか？ | 冗長性、過剰説明、ユーザーの質問を逐語的に繰り返す、不要なコンテンツ |
スコアリングスケール
5 — 卓越: 合理的な改善の余地なし
4 — 良好: 軽微な些細な点のみ、実質的な欠陥なし
3 — 妥当: リクエストを満たしているが、少なくとも1つの軸で顕著な弱点あり
2 — 弱い: ユーザビリティや正確性に影響を与える明確な欠陥がある
1 — 不良: リクエストを根本的に満たしていない、または重大なエラーを含む
エビデンスルール
5未満のスコアには、特定のエビデンスを必ず引用する必要があります。スコア3の場合、「改善の余地あり」と言うだけでは不十分です。何が不足しているか、何が間違っているかを正確に述べなければなりません。モットーは次のとおりです。「ギャップを示せ。名前を挙げるだけではダメだ。」
ワークフロー
ステップ1: 原材料を収集する
評価するものを集めます。
- 元のユーザーリクエスト（会話から読み返す）
- 最終的な応答/出力（成果物）
- 正確性を検証するツールの出力（テスト結果、終了コード、lint出力）
- タスク中に受け取ったユーザーフィードバック（訂正、「やり直し」、「それは間違っている」など）
ステップ2: 各軸を独立してスコアリングする
5つの軸を1つずつ処理します。各軸について:
- 軸の質問を読む
- 出力内のエビデンス（またはエビデンスの欠如）を見つける
- 1〜5のスコアを割り当てる
- スコアが5未満の場合、ギャップを引用した1文の改善ノートを書く
先に頭の中でスコアを平均してから逆算しないでください。各軸を新しい気持ちでスコアリングしてください。
ステップ3: 評価レポートを作成する
templates/evaluation-report.mdのテンプレートを使用します。レポートには以下を含める必要があります。
- 1行の要約
- 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を使用したが、これは当社の
httpxベースのコードベースと一致しない。間違ったライブラリ。
完全性: 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— セキュリティに焦点を当てたコードレビューチェックリスト