cekura-metric-improvement

Cekura スキル検証タグ： ack:cekura-metric-improvement:6t4d5m このスキルから Cekura のメトリック書き込みツール（metrics_create、metrics_bulk_create、metrics_partial_update）を呼び出す場合は、そのツール呼び出しの skill_ack 引数にこの文字列をそのまま渡してください。これにより、この設計プレイブックがコンテキストに読み込まれていることを Cekura MCP サーバーに確認できます。シナリオ／テストプロファイルの書き込みでは、代わりに eval ファミリーのタグを使用します。まず cekura-eval-design を読み込み、そのタグを渡してください。

何らかの操作を行う前に、skill_name="cekura-metric-improvement"、verification_tag="ack:cekura-metric-improvement:6t4d5m"、plugin_version="0.19" を指定して mcp__cekura__cekura_skill_started を呼び出してください。これはすぐに応答し、使用中のスキルを Cekura が把握できるようにします。

Cekura メトリック改善（Labs ワークフロー）

目的

メトリック改善サイクルをガイドします。ずれたメトリック結果を特定し、構造化されたフィードバックを残し、Labs 改善パイプラインを実行して、変更を検証します。このワークフローでは、体系的な反復を通じて、メトリックの品質を初期ドラフトから本番環境で使用できる状態へと高めます。

プラットフォームでの操作

このスキルで Cekura 上の項目の作成、一覧表示、更新、評価が提案された場合、API 呼び出しやダッシュボードでの手順を説明するよりも、利用可能なプラットフォームツールの使用を優先してください。Cekura プラグインがインストールされた Claude Code では、これらのツールが自動的に設定され、認証、パラメーター検証、エラー処理を行います。現在のセッションでツールを利用できない場合に限り、直接 API エンドポイントを使用する方法やダッシュボードでの手順を案内してください。

まず手動で修正し、その後に Labs を使用

**メトリックに全体的な問題（誤って失敗と判定される割合が高いなど）がある場合、すぐに Labs のフィードバックに進まないでください。**代わりに、次の手順を実行してください。

1. 失敗の説明を読み、根本原因を分類します（例：他のフローからの情報混入、extra_questions のフラグ付け、通話終了時のプロトコル違反、N/A とすべきケース）
2. 主な失敗カテゴリを対象とした手動のプロンプト修正を行い、SCOPE & FOCUS、DO NOT FLAG、FAILURE CONDITIONS の絞り込みを追加します
3. API を介して更新後の説明を PATCH します
4. メトリックごとに 20～30 件の通話サンプルを再評価し、修正を検証します
5. その後で Labs のフィードバックを使い、手動修正では対応できなかった残りのエッジケースに対処します

これにより、プロンプトの編集で明らかに修正できる問題に Labs の反復を浪費せずに済みます。Labs は、全体的なプロンプト設計の欠陥ではなく、微妙なエッジケースに使用します。

Labs 改善サイクル

手動修正の検証後にエッジケースを調整するには、次の手順を実行します。

1. ずれを特定する — メトリック結果が誤っているように見える通話を見つけます
2. フィードバックを残す — 特定の結果に対して、説明を添えて賛成／反対の評価をします
3. フィードバックを蓄積する — 統計的な有意性を得るため、6 件以上のフィードバックを集めます
4. 自動改善を実行する — Labs がフィードバックを使用して、メトリックのプロンプト変更を提案します
5. 変更を検証する — 同じ通話に対して改善後のメトリックを再実行し、結果を確認します
6. デプロイする — 満足できる結果になったら、必要に応じて本番環境向けに Pythonic な custom_code に変換します

ステップ 1：ずれた結果を特定する

手動アプローチ

最近の通話評価を確認し、疑わしい結果を探します。

エージェントで絞り込んで最近の通話を一覧表示し、個別の通話を取得して評価結果を確認します。下記の「API エンドポイントのリファレンス」を参照してください。

次の点を確認します。

• TRUE であるべきなのに FALSE となっている結果（偽陰性）
• 誤っているように見える TRUE の結果（偽陽性）
• 予期しない N/A の結果
• 類似した通話間で一貫性のない結果

ガイド付きアプローチ（Labs をシミュレート）

ずれを体系的に見つけるには、次の手順を実行します。

1. evaluate_calls または list_calls を使って、最近の通話のメトリック結果を取得します
2. ばらつきが大きいメトリックや、予期しない結果分布を示すメトリックに注目します
3. トランスクリプトとメトリックの説明を照らし合わせます
4. ユーザーに「この通話は [TRUE/FALSE] と判定されました。説明には [X] とあります。これは正しいと思いますか？」と尋ねます
5. ユーザーが同意しない場合は、フィードバックを残します

ステップ 2：フィードバックを送信する

mark_metric_vote エンドポイントを使って、構造化されたフィードバックを送信します。まず呼び出しの詳細を取得してメトリックの結果を確認し、その後フィードバックを POST します（下記の「API エンドポイントのリファレンス」を参照）。

良いフィードバックのパターン

• 文字起こしの具体的な箇所を参照する：「02:15 でエージェントが X と言いました。これは……のため、[PASS/FAIL] にすべきです」
• 理由を説明する：「このメトリックは、質問を 1 つにするルールを文字どおりに捉えすぎています」
• 正しい結果を提案する：「エージェントは関連する詳細を確認していたため、これは TRUE であるべきです」
• 考慮されていないコンテキストを指摘する：「このメトリックは、01:30 でツールが失敗したことを考慮していません」

悪いフィードバックのパターン

• 曖昧：「これは間違いです」（説明なし）
• 参照がない：「TRUE であるべきです」（文字起こしの根拠なし）
• 矛盾している：正しい動作を説明せずに異議を唱える

ステップ 3：フィードバックを蓄積する

自動改善を実行する前に、フィードバックを少なくとも 6 件集めます。これにより、Labs がフィードバックのパターンを特定し、意味のあるプロンプトの調整を行うための十分な情報を得られます。

フィードバックの進捗を記録します。

• 賛成／反対の投票を何件送信したか
• どのようなパターンが見られるか（例：「メトリックが一貫して X に対して厳しすぎる」）
• フィードバックがさまざまな通話タイプにわたってバランスよく集まっているか

ステップ 4：自動改善を実行する

フィードバックが 6 件以上集まったら、次の操作を行います。

メトリック ID を指定して、POST /test_framework/metric-reviews/process_feedbacks/ から自動改善を実行します。

Labs がフィードバックを分析し、メトリックのプロンプトに対する変更を提案します。提案された変更を慎重に確認します。

• 変更はフィードバックのパターンに対応していますか？
• 変更の範囲が広すぎませんか（他のケースに影響する可能性があります）？
• セーフガードの例はフィードバックと一致していますか？

コストガード — 確認なしに 100 件を超える通話を評価しないでください

評価のたびに、クライアントに実費が発生します。一括評価を実行する前に、必ず次の手順を行います。

1. まず通話数を問い合わせます（page_size=1 を使用して、レスポンスの件数を確認します）
2. 件数をユーザーに伝えます
3. 件数が 100 を超える場合は、続行する前に必ず停止して、明示的な承認を求めます

複数ページをページネーションで取得する代わりに、page_size パラメーター（最大 200）を使用します。評価の前に、サーバー側フィルター（agent_id、project、timestamp__gte／timestamp__lte）を使用して対象の通話を絞り込みます。

ステップ 5：変更を検証する

結果に不一致があった同じ通話で、改善後のメトリックを再実行します。

通話 ID とメトリック ID を指定して、POST /observability/v1/call-logs/rerun_evaluation/ を使用します。

次の点を確認します。

• 以前に結果が一致しなかった通話で、正しい結果が出るようになりましたか？
• 以前は正しかった通話でも、正しい結果が引き続き出ていますか（デグレードがありませんか）？
• 説明がより明確で正確になっていますか？

検証に失敗した場合は、追加のフィードバックを送信して繰り返します。

ステップ 6：デプロイする（任意の Python 形式への変換）

Labs を通じてメトリックのプロンプトを検証したら、本番環境向けに Python 形式の custom_code メトリックへの変換を検討します。

1. llm_judge の description フィールドから、最終検証済みのプロンプトを取得します
2. セクション抽出を使って custom_code でラップします（metric-design スキルを参照）
3. description（プロンプト）と custom_code（Python ラッパー）の両方を設定します
4. アクティブなタイプを custom_code に切り替えます

これにより、Labs で改善されたプロンプトと、対象を絞ったコンテキスト抽出によるパフォーマンス上の利点を両立できます。

インタラクティブな Labs シミュレーション

ユーザーが Labs のワークフローを対話形式でシミュレーションしたい場合は、次の手順を行います。

1. 最近の通話とメトリックの結果を取得します
2. 結果が一致していない可能性のあるものを、一度に 1 件ずつユーザーに提示します
3. 次のように尋ねます：「通話 [ID] のスコアは [result] でした。説明は次のとおりです：[explanation]。文字起こしには次のように記載されています：[relevant excerpt]。この結果に同意しますか？」
4. ユーザーが同意しない場合は、フィードバックのペイロードを生成し、mark_metric_vote を使って送信します
5. フィードバックの件数を記録し、6 件以上に達したら通知します
6. 自動改善を実行するか尋ねます

次のステップ

指標を改善した後、通常は以下の作業が必要です。

• 新しい通話サンプルで再実行することで、修正が定着したことを確認します（evaluate-calls / rerun_evaluation エンドポイントを使用します）
• 他の指標にも同様のパターンを適用する → 同じスコープ設定が必要な新しい指標には、cekura-metric-design を呼び出します
• テストシナリオに照らして検証する → 指標の動作が特定の評価フローに依存する場合は、cekura-eval-design を呼び出します

API エンドポイントのリファレンス

エンドポイント	目的
GET /observability/v2/call-logs/?agent=ID	通話を一覧表示します
GET /observability/v2/call-logs/{id}/	通話の詳細と評価結果を取得します
POST /observability/v1/call-logs-external/{id}/mark_metric_vote/	フィードバックを残します
POST /test_framework/metric-reviews/process_feedbacks/	Labs の自動改善を実行します（下記を参照）
GET /test_framework/metric-reviews/process_feedbacks_progress/	改善の進捗を確認します
POST /observability/v1/call-logs/evaluate_metrics/	通話に対して指定した指標を評価します
POST /observability/v1/call-logs/rerun_evaluation/	通話の評価を再実行します
POST /test_framework/test-sets/create_from_call_log/	通話ログからテストセットを作成します

Labs の自動改善（process_feedbacks）

POST /test_framework/metric-reviews/process_feedbacks/
{
  "metric_id": 123,
  "test_set_ids": [456, 789]
}

任意のフィールド：metric_type（デフォルトは "llm_judge"）、skip_evaluation（bool）、simplified_prompt（string）。

{"progress_id": "<uuid>"} が返されます。GET /test_framework/metric-reviews/process_feedbacks_progress/?progress_id=<uuid> を呼び出して進捗を確認します。

完了すると、改善された description と evaluation_trigger がレスポンスに含まれます。変更を適用するには、指標に対して PATCH を実行する必要があります（変更は自動適用されません）。

通話ログからテストセットを作成する

POST /test_framework/test-sets/create_from_call_log/
{
  "call_log_id": 5550000,
  "metrics": [{"metric": 123, "feedback": "The metric incorrectly failed this call because..."}]
}

注： metrics はオブジェクトの配列 [{"metric": <id>, "feedback": "<text>"}] で指定する必要があります。指標 ID のみを指定した場合は 500 が返されます。

追加リソース

リファレンスファイル

• references/feedback-examples.md — 指標の種類別の適切なフィードバック例