eve-agent-optimisation

Eve エージェントの最適化

目標：エージェントが最少のツール呼び出し、最少のトークン、最短の時間で目的を達成できるようにします。無駄な作業を見つけて取り除きます。

厳守ルール：変更せず、提案する

ユーザーに事前に確認せず、ハーネス、モデル、推論の労力、権限ポリシーを変更してはいけません。 これらは、プロジェクトオーナーが判断すべきコストと機能に関する決定事項です。問題を診断し、トレードオフを説明して提案したら、承認を待ちます。

確認する項目

エージェントの実行ログを分析して、以下を特定します。

1. 誤った方向への試行 — エージェントが実現不可能な方法を試し、後戻りする必要があった。
2. 行き止まり — エージェントが目標に関係のないことを調べるためにトークンを消費した。
3. 不要なツール呼び出し — エージェントが不要なファイルを読んだ、有用な情報が得られないコマンドを実行した、または少しだけ変えた呼び出しを繰り返した。
4. 不足しているコンテキスト — SKILL.md やジョブの説明に記載すべき情報を、エージェントが試行錯誤して見つける必要があった。
5. 用途に合わないツール — より高速なネイティブの代替手段があるのに、遅いツールや不安定なツールを使った（例：LLM は PDF をネイティブに読み取れるのに、pdftotext をシェルから実行した）。
6. 過剰な読み込み — 必要な箇所だけ読めばよいのに大きなファイル全体を読んだ、または対象を絞った検索で見つかる情報を探すために多数のファイルを読んだ。
7. 冗長な出力 — 簡潔な結果だけでよいタスクで、エージェントが推論を長々と説明した。
8. 再試行ループ — 結果が変わることを期待して、エージェントが同じ失敗する操作を繰り返した。

診断ワークフロー

ステップ 1：実行記録を取得する

eve job diagnose <job-id>          # Full timeline, routing, errors
eve job show <job-id> --verbose    # Phase, attempts, harness, agent
eve job receipt <job-id>           # Token usage + cost

主な数値：

• 入力トークン — エージェントが読み込んだ量です。多い場合は、読み込みすぎています。
• 出力トークン — エージェントが書き出した量です。多い場合は、冗長、または推論過多です。
• 試行回数 — 1 回を超える場合、エージェントがクラッシュしたか、タイムアウトしています。
• 所要時間 — 集中して作業するエージェントに必要な時間と比較します。

ステップ 2：ログをストリーミングまたは再生する

eve job follow <job-id>            # Real-time (if still active)
eve job logs <job-id>              # Historical

ログを順番に読みます。ツール呼び出しごとに、次の点を確認します。

• これによって目標に近づいたか？ そうでなければ、無駄です。
• これを避けられたか？ SKILL.md に調べる場所が記載されていれば、エージェントはこの作業を省けたでしょうか？
• 適切なツールだったか？ 別の方法なら、同じ情報をより速く得られたでしょうか？
• 範囲は適切だったか？ 必要なのは 10 行なのに、ファイル全体を読んでいませんでしたか？

ステップ 3：クリティカルパスを特定する

目標を達成するために必要な最小限のツール呼び出しを特定します。

1. 実際に必要だったファイルはどれですか？
2. 実際に有用な出力を得られたコマンドはどれですか？
3. 最初の試みで正しく判断できたことは何ですか？

それ以外はすべて無駄です。数値化しましょう。クリティカルパス上のツール呼び出しは、全体の何件中何件ですか？トークンのうち、生産的な作業に使われた割合はどれくらいですか？

ステップ 4：根本原因を特定する

無駄のカテゴリごとに、根本原因をたどります。

無駄	根本原因	修正方法
エージェントが誤ったファイルを調べた	SKILL.md にどこを確認すべきか記載されていない	SKILL.md に具体的なファイルパスや検索パターンを追加する
エージェントが最初に誤った方法を試した	SKILL.md に推奨する方法が記載されていない	「Y ではなく X を実行する」と明示的な指示を追加する
エージェントが不要なファイルを読んだ	ジョブの説明が曖昧すぎる	説明を絞り込み、対象範囲を正確に指定する
エージェントが失敗したコマンドを再試行した	エラー処理のガイダンスがない	SKILL.md に失敗時の動作に関する指示を追加する
エージェントがファイル形式に合わないツールを使った	SKILL.md にネイティブ機能の記載がない	ファイル形式ごとの使い分けを追加する：「PDF：ネイティブに読み取る。画像：直接表示する。」
エージェントが大きなファイルをすべて読んだ	対象を絞った読み取り方法のガイダンスがない	「1～50 行だけ読む」または「X を検索する」という指示を追加する
エージェントの出力が冗長だった	出力形式が指定されていない	JSON スキーマ、添付ファイル名、簡潔な要約など、形式を正確に指定する
エージェントが判断に必要なコンテキストを欠いている	リソース参照または環境変数が不足している	適切なリソースを添付し、with_apis が設定されていることを確認する
エージェントが既知の事実を再発見している	永続メモリの戦略がない	組織のドキュメント、KV ストア、または添付ファイルを使って知識を引き継ぐ
プロビジョニングのためにエージェントの動作が遅い	リソースが多すぎる、クローンが大きい、不要なツールチェーンがある	リソース参照を減らし、シャロークローンを設定し、未使用のツールチェーンを削除する

修正のほとんどは SKILL.md で解決できます

SKILL.md は、最も効果の高い最適化対象です。正確な SKILL.md を用意すれば、ツール呼び出しの無駄をカテゴリごと取り除けます。

効率を意識して書く

1. 目標を 1 文で示す。 エージェントは、作業を始める前に何を達成するのかを正確に把握できる必要があります。

2. 具体的なファイル名とパスを示す。 「認証設定を確認する」では、検索にツール呼び出しが必要です。「src/config/auth.ts の 1～30 行を読む」なら、ツール呼び出しは 1 回で済みます。

3. 方法を明確に示す。 「Read ツールを使って PDF をネイティブに読み取る。変換ツールをシェルから実行してはならない」と指定すれば、エージェントが誤った方法を試すのを防げます。

4. してはならないことを指定する。 よくある誤った進め方があれば、それを防ぎます。「テストスイート全体を読まず、失敗したテストファイルだけを読む。」

5. 出力形式を定義する。 「findings.json という名前の JSON 添付ファイルを、スキーマ {issues: [{file, line, severity, message}]} で作成する。」こうすれば、形式についての検討が不要になります。

6. エージェントが利用できるコンテキストを伝える。 「.eve/resources/index.json のリソースインデックスには、添付されたすべてのドキュメントが mime_type とともに一覧されています。最初にこれを読み、処理方法を判断してください。」

7. 分岐ごとの判断フローを用意する。 「ファイル形式に応じて適切に処理する」の代わりに、次のようにします。

   Check mime_type in resource index:
   - application/pdf → read natively, use page ranges for >10 pages
   - text/* → read directly
   - image/* → view directly (multimodal)
   - other → describe and note for human review
   

8. 短く保つ。 エージェントが読む言葉はすべて入力トークンを消費します。冗長な部分を削りましょう。文章よりも表やリストを使います。

SKILL.md をテストする

書き直した後、同じジョブをもう一度実行して、次の点を比較します。

• ツール呼び出しは減ったか？
• トークン数は減ったか？
• 完了は速くなったか？
• 最初の試行で正しい結果が得られたか？

eve job compare <old-job-id> <new-job-id>   # Compare receipts

SKILL.md 以外の改善点

SKILL.md の変更だけでは不十分な場合は、次の調整項目を検討します（いずれも変更にはユーザーの承認が必要です）。

ハーネスとモデル

エージェントに次の傾向が一貫して見られる場合：

• タスクに対して遅すぎる → より高速なモデル（例：sonnet から haiku）を推奨します。
• 能力が不足している → より高性能なモデル（例：sonnet から opus）を推奨します。
• 思考トークンを使いすぎている → 推論の労力を下げることを推奨します。
• 十分に考えていない → 推論の労力を上げることを推奨します。

速度、コスト、品質のトレードオフを提示し、ユーザーに判断を委ねます。

権限ポリシー

すべてのファイル編集で承認待ちとなり、エージェントが作業を中断する場合：

• 自動化された一括作業には yolo を推奨します。
• 監督下でのコーディングには auto_edit を推奨します。
• セキュリティ上の影響を説明します。

リソース参照

プロビジョニングに時間がかかる場合：

• エージェントが実際には使用しないリソース参照を削除します。
• 任意のコンテキストには required: false を設定します。
• mime_type を渡して、エージェントがファイルの種類を調べなくて済むようにします。

Git の制御

エージェントが Git 操作に時間をかけすぎる場合：

• commit: auto と push: on_success の組み合わせで、手動の Git 手順をなくせます。
• create_branch: if_missing を設定すると、ブランチ作成時の失敗を防げます。
• ref_policy: auto を設定すると、クローンの範囲を最小限にできます。

ジョブの範囲

エージェントが1つのジョブで多くの作業をしすぎる場合：

• オーケストレーションを使って、範囲を絞った子ジョブに分割します。
• 各子ジョブには、範囲を限定した専用の SKILL.md を用意します。
• 単純な子ジョブにはより低コストのモデルを使い、必要な箇所にのみ高性能なモデルを使います。

チームの連携

子エージェントが作業を重複して行う場合：

• スキルが起動時に .eve/coordination-inbox.md を読み込むようにします。
• 順次実行するステップには depends_on を設定します。
• ジョブ間のデータ共有には文章ではなく添付ファイルを使います。

最適化レポートのテンプレート

エージェントの実行を分析した後、次の形式で調査結果を提示します。

## Agent Optimisation Report: <job-id>

**Goal:** <what the agent was trying to do>
**Result:** <succeeded/failed> in <duration> using <tokens> tokens (<cost>)

### Efficiency Score
- Total tool calls: N
- Productive tool calls: M (X%)
- Wasted tool calls: N-M (Y%)

### Waste Categories
1. <category>: N calls, ~X tokens wasted
   - Example: <specific wasteful action from logs>
   - Fix: <specific SKILL.md or config change>

### Recommended Changes
- [ ] SKILL.md: <specific edit> — eliminates <category> waste
- [ ] SKILL.md: <specific edit> — eliminates <category> waste
- [ ] (Requires approval) Model: <current> → <recommended> — <reason>
- [ ] (Requires approval) Reasoning: <current> → <recommended> — <reason>

### Expected Improvement
- Estimated tool calls: N → M
- Estimated tokens: X → Y
- Estimated time: A → B

クイックリファレンス：よくある無駄なパターン

パターン	ログ上の兆候	対処法
ファイル探し	異なるファイルへの Read 呼び出しが複数ある	SKILL.md に対象ファイルを明記します
grep の連鎖	異なるパターンで複数回検索している	適切な検索語を提示します
試行錯誤	ツール呼び出しが失敗し、エージェントが条件を変えて再試行する	正しい方法を記載します
読みすぎ	5000行以上のファイルに対して Read ツールを使っている	行範囲を指定するか、先に検索するよう指示します
不要な調査	エージェントが README、CHANGELOG などを読む	読まないものを明示します
形式の検討	出力形式を決めるためにアシスタントのターンが長くなる	SKILL.md で出力形式を指定します
冗長な検証	すでに確認済みの内容をエージェントが再確認する	SKILL.md を一連の直線的な手順として構成します
ネイティブ機能の見落とし	LLM が直接処理できるのに CLI ツールを実行する	ネイティブ機能を明示します
コンテキストの再発見	実行のたびにエージェントがプロジェクト構成を再学習する	組織のドキュメントまたは KV ストアを使ってコンテキストを永続化します
承認待ちによる停止	エージェントが許可を待って処理を停止する	ユーザーに yolo または auto_edit を推奨します

関連スキル

• eve-job-debugging — ジョブの監視と診断に使う CLI コマンド。
• eve-orchestration — 作業を並列実行する子ジョブに分割します。
• eve-agent-memory — ジョブをまたいで情報を保持するためのストレージ機能。
• eve-skill-distillation — 学習したパターンを再利用可能なスキルとして記録します。
• eve-read-eve-docs — プラットフォームのリファレンスドキュメント（CLI、マニフェスト、ジョブ、ハーネス）。