agent-orchestration-improve-agent

エージェントのパフォーマンス最適化ワークフロー

パフォーマンス分析、プロンプトエンジニアリング、継続的な反復を通じて、既存のエージェントを体系的に改善します。

[Extended thinking: エージェントの最適化には、パフォーマンス指標、ユーザーフィードバック分析、高度なプロンプトエンジニアリング手法を組み合わせた、データに基づくアプローチが必要です。成功の鍵は、体系的な評価、的を絞った改善、本番環境の安全性を確保するためのロールバック機能を備えた厳格なテストです。]

このスキルを使用する場面

• 既存のエージェントのパフォーマンスや信頼性を改善する場合
• 失敗モード、プロンプトの品質、ツールの使用状況を分析する場合
• 構造化された A/B テストや評価スイートを実施する場合
• エージェントの反復的な最適化ワークフローを設計する場合

このスキルを使用しない場面

• ゼロから新しいエージェントを構築する場合
• 指標、フィードバック、テストケースがない場合
• エージェントのパフォーマンスやプロンプトの品質と無関係なタスクの場合

手順

1. ベースライン指標を確立し、代表的な事例を収集します。
2. 失敗モードを特定し、影響の大きい修正を優先します。
3. 測定可能な目標を設定して、プロンプトとワークフローを改善します。
4. テストで検証し、管理された段階を踏んで変更を展開します。

実行上の境界

フェーズで名前が挙がっているというだけで、ホスト型評価の実行、委任、チームへのメッセージ送信、定期レポートの設定、デプロイを行わないでください。ユーザーがすでに与えている権限と、実際のホストワークフローに従ってください。トレースは非公開にして、機密情報を削除またはマスキングし、コストと手順に上限を設け、候補となる変更を分離し、サポートされている正確なバージョンの確認を必須にしてください。parallel-test-runner と名前付きのエージェントロールは同梱されていません。実際に利用できるハーネスを使うか、その不足を報告してください。

安全性

• 回帰テストを実施せずにプロンプトの変更をデプロイしないでください。
• 品質または安全性の指標が悪化した場合は、速やかにロールバックしてください。

フェーズ 1：パフォーマンス分析とベースライン指標

提供されたトレースと利用可能な指標を分析します。以下の名前付きロールは任意の役割であり、インストール済みの実行ファイルでも委任の許可でもありません。

1.1 パフォーマンスデータの収集

Use: context-manager
Task: analyze the authorized trace window using actual available tools
No analyze-agent-performance command is bundled.

以下の指標を収集します。

• タスク完了率（成功したタスクと失敗したタスク）
• 応答の正確性と事実の正しさ
• ツールの使用効率（適切なツール、呼び出し頻度）
• 平均応答時間とトークン消費量
• ユーザー満足度の指標（修正、再試行）
• ハルシネーションの発生とエラーパターン

1.2 ユーザーフィードバックのパターン分析

ユーザーとのやり取りで繰り返し見られるパターンを特定します。

• 修正パターン：ユーザーが一貫して出力を変更する箇所
• 明確化の依頼：曖昧さがよく見られる領域
• タスクの放棄：ユーザーが諦める箇所
• 追加の質問：応答が不完全であることを示す兆候
• 肯定的なフィードバック：維持すべき成功パターン

1.3 失敗モードの分類

根本原因に基づいて失敗を分類します。

• 指示の誤解：役割またはタスクの混同
• 出力形式の誤り：構造または書式の問題
• コンテキストの喪失：長い会話による品質の低下
• ツールの誤用：不適切または非効率なツールの選択
• 制約違反：安全規則または業務規則への違反
• エッジケースへの対応：まれな入力シナリオ

1.4 ベースラインパフォーマンスレポート

定量的なベースライン指標を作成します。

Performance Baseline:
- Task Success Rate: [X%]
- Average Corrections per Task: [Y]
- Tool Call Efficiency: [Z%]
- User Satisfaction Score: [1-10]
- Average Response Latency: [Xms]
- Token Efficiency Ratio: [X:Y]

フェーズ 2：プロンプトエンジニアリングの改善

prompt-engineer エージェントを使って、高度なプロンプト最適化手法を適用します。

2.1 思考の連鎖の強化

構造化された推論パターンを実装します。

Use: prompt-engineer
Technique: chain-of-thought-optimization

• 明示的な推論手順を追加します：「これを段階的に進めてみましょう……」
• 自己検証のチェックポイントを含めます：「先に進む前に、……であることを確認してください」
• 複雑なタスクに対して、再帰的な分解を実装します
• 非公開の思考の連鎖ではなく、簡潔な判断理由と観察可能なツールのトレースを収集します

2.2 Few-Shot の例の最適化

成功したやり取りから質の高い例を厳選します。

• 多様な例を選択し、一般的なユースケースを網羅します
• 以前に失敗したエッジケースを含めます
• 説明付きで肯定例と否定例の両方を示します
• 単純なものから複雑なものへ例を並べます
• 重要な判断ポイントを例に注釈します

例の構成：

Good Example:
Input: [User request]
Evidence: [Concise rationale and observable checks]
Output: [Successful response]
Why this works: [Key success factors]

Bad Example:
Input: [Similar request]
Output: [Failed response]
Why this fails: [Specific issues]
Correct approach: [Fixed version]

2.3 ロール定義の改善

エージェントのアイデンティティと能力を強化します。

• 中核となる目的：明確な一文で示す使命
• 専門分野：具体的な知識領域
• 行動特性：性格と対話スタイル
• ツールの習熟度：利用可能なツールとその使用タイミング
• 制約：エージェントがすべきでないこと
• 成功基準：タスクの完了を測定する方法

2.4 Constitutional AI の統合

自己修正の仕組みを実装します。

Constitutional Principles:
1. Verify factual accuracy before responding
2. Self-check for potential biases or harmful content
3. Validate output format matches requirements
4. Ensure response completeness
5. Maintain consistency with previous responses

批評と修正のループを追加します。

• 初期応答の生成
• 原則に照らした自己批評
• 問題が検出された場合の自動修正
• 出力前の最終検証

2.5 出力形式の調整

応答の構成を最適化します。

• 一般的なタスク向けの構造化テンプレート
• 複雑さに応じた動的な書式設定
• 詳細情報の段階的な提示
• 読みやすさのためのMarkdown の最適化
• シンタックスハイライト付きのコードブロックの書式設定
• データ提示のための表とリストの生成

Phase 3: テストと検証

A/B 比較を含む包括的なテストフレームワークです。

3.1 テストスイートの開発

代表的なテストシナリオを作成します。

Test Categories:
1. Golden path scenarios (common successful cases)
2. Previously failed tasks (regression testing)
3. Edge cases and corner scenarios
4. Stress tests (complex, multi-step tasks)
5. Adversarial inputs (potential breaking points)
6. Cross-domain tasks (combining capabilities)

3.2 A/B テストフレームワーク

元のエージェントと改善後のエージェントを比較します。

Use: parallel-test-runner
Config:
  - Agent A: Original version
  - Agent B: Improved version
  - Test set: 100 representative tasks
  - Metrics: Success rate, speed, token usage
  - Evaluation: Blind human review + automated scoring

統計的有意性の検定：

• ベースラインの分散／率、最小検出効果、希望する検出力からサンプルサイズを決定します。100 件のタスクは、例示的なデータセットサイズにすぎません
• 有意水準、信頼区間、対応あり／ランダム化デザイン、多重比較の方針を事前に定義します。p < 0.05 は、ある主張が真である確率が 95％であることを意味しません
• 効果量の算出（Cohen の d）
• 今後のテストに向けた検出力分析

3.3 評価指標

包括的なスコアリングフレームワーク：

タスクレベルの指標：

• 完了率（二値の成功／失敗）
• 正確性スコア（精度 0～100％）
• 効率スコア（実行したステップ数と最適なステップ数の比較）
• ツール使用の適切さ
• 応答の関連性と完全性

品質指標：

• ハルシネーション率（応答ごとの事実誤認数）
• 一貫性スコア（以前の応答との整合性）
• 形式への準拠（指定された構造との一致）
• 安全性スコア（制約の遵守）
• ユーザー満足度の予測

パフォーマンス指標：

• 応答レイテンシ（最初のトークンが出るまでの時間）
• 生成時間の合計
• トークン消費量（入力＋出力）
• タスクあたりのコスト（API 利用料金）
• メモリ／コンテキストの効率

3.4 人による評価プロトコル

体系化された人によるレビューのプロセス：

• ブラインド評価（評価者はバージョンを知らない）
• 明確な基準を定めた標準化ルーブリック
• サンプルごとに複数の評価者を設定（評価者間信頼性）
• 定性的なフィードバックの収集
• 優先順位付け（A 対 B の比較）

Phase 4: バージョン管理とデプロイ

監視とロールバック機能を備えた安全な段階的展開です。

4.1 バージョン管理

体系的なバージョン管理戦略：

Version Format: agent-name-v[MAJOR].[MINOR].[PATCH]
Example: customer-support-v2.3.1

MAJOR: Significant capability changes
MINOR: Prompt improvements, new examples
PATCH: Bug fixes, minor adjustments

バージョン履歴を維持します。

• Git ベースのプロンプト保存
• 改善内容を記載した変更履歴
• バージョンごとのパフォーマンス指標
• 文書化されたロールバック手順

4.2 段階的な展開

段階的なデプロイ戦略：

1. アルファテスト：社内チームによる検証（トラフィックの 5％）
2. ベータテスト：選定したユーザー（トラフィックの 20％）
3. カナリアリリース：段階的な増加（20％ → 50％ → 100％）
4. 全面デプロイ：成功基準を満たした後
5. 監視期間：7 日間の観察期間

4.3 ロールバック手順

迅速な復旧の仕組み：

Rollback Triggers:
- Success rate drops >10% from baseline
- Critical errors increase >5%
- User complaints spike
- Cost per task increases >20%
- Safety violations detected

Rollback Process:
1. Detect issue via monitoring
2. Alert team immediately
3. Switch to previous stable version
4. Analyze root cause
5. Fix and re-test before retry

4.4 継続的なモニタリング

リアルタイムのパフォーマンス追跡：

• 主要指標を表示するダッシュボード
• 異常検知アラート
• ユーザーフィードバックの収集
• 自動化された回帰テスト
• 週次のパフォーマンスレポート

成功基準

以下は参考となる目標であり、普遍的な成功条件ではありません。テスト前に実際の基準を選択し、相対的な変化とパーセンテージポイントを区別して、不確実性を報告してください：

• タスク成功率が15%以上向上する
• ユーザーによる修正が25%以上減少する
• 安全性違反が増加しない
• 応答時間がベースラインの10%以内に収まる
• タスクあたりのコストが5%を超えて増加しない
• 肯定的なユーザーフィードバックが増加する

デプロイ後のレビュー

本番環境で30日間使用した後：

1. 蓄積されたパフォーマンスデータを分析する
2. ベースラインおよび目標と比較する
3. 新たな改善機会を特定する
4. 得られた教訓を記録する
5. 次の最適化サイクルを計画する

継続的な改善サイクル

定期的な改善のペースを確立します：

• 週次：指標をモニタリングし、フィードバックを収集する
• 月次：傾向を分析し、改善を計画する
• 四半期ごと：新機能を追加したメジャーバージョンアップデートを実施する
• 年次：戦略レビューとアーキテクチャのアップデートを行う

エージェントの最適化は反復的なプロセスであることを忘れないでください。各サイクルは前回の学びを基盤とし、安定性と安全性を維持しながら、パフォーマンスを段階的に向上させます。

制限事項

• タスクが上記の説明された範囲に明確に合致する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を止めて確認してください。