agent-harness-construction

name	agent-harness-construction
description	Design and optimize AI agent action spaces, tool definitions, and observation formatting for higher completion rates.
origin	ECC

エージェントハーネス構築

エージェントの計画、ツール呼び出し、エラーリカバリー、完了への収束を改善する際にこのスキルを使用します。

コアモデル

エージェントの出力品質は以下に制約されます：

1. アクション空間の品質
2. 観察の品質
3. リカバリーの品質
4. コンテキストバジェットの品質

アクション空間の設計

1. 安定した明示的なツール名を使用する。
2. 入力はスキーマファーストで狭く保つ。
3. 決定論的な出力形状を返す。
4. 分離が不可能でない限り、キャッチオールツールを避ける。

粒度ルール

• 高リスク操作（デプロイ、マイグレーション、権限）にはマイクロツールを使用する。
• 一般的な edit/read/search ループにはミディアムツールを使用する。
• ラウンドトリップオーバーヘッドが支配的なコストの場合のみマクロツールを使用する。

観察の設計

すべてのツールレスポンスに含めるべき項目：

• status: success|warning|error
• summary: 1 行の結果
• next_actions: 実行可能なフォローアップ
• artifacts: ファイルパス / ID

エラーリカバリーコントラクト

すべてのエラーパスに含める：

• 根本原因のヒント
• 安全なリトライ指示
• 明示的な停止条件

コンテキストバジェッティング

1. システムプロンプトを最小限で不変に保つ。
2. 大きなガイダンスはオンデマンドで読み込むスキルに移動する。
3. 長いドキュメントのインライン化よりファイルへの参照を優先する。
4. 任意のトークン閾値ではなく、フェーズ境界でコンパクトする。

アーキテクチャパターンガイダンス

• ReAct: 不確実なパスを持つ探索的タスクに最適。
• Function-calling: 構造化された決定論的フローに最適。
• ハイブリッド（推奨）: ReAct 計画 + 型付きツール実行。

ベンチマーキング

追跡項目：

• 完了率
• タスクあたりのリトライ数
• pass@1 と pass@3
• 成功タスクあたりのコスト

アンチパターン

• セマンティクスが重複する過多なツール。
• リカバリーヒントのない不透明なツール出力。
• 次のステップのないエラーのみの出力。
• 無関係な参照によるコンテキストの過負荷。