agent-estimation

エージェント作業見積もりスキル

問題

AI コーディングエージェントは、トレーニングデータから取り込んだ人間の開発者の所要時間を基準にするため、タスクの所要時間を体系的に過大評価します。エージェントなら30分で完了できるタスクが、人間の開発者向けフォーラムの投稿にそう書かれているため、「2～3日」と見積もられます。

解決策

エージェントに、独自の作業単位であるツール呼び出しラウンドを基準に見積もらせ、人間の実時間への換算は最後にのみ行います。

基本単位

単位	定義	規模
ラウンド	1回のツール呼び出しサイクル：思考 → コード作成 → 実行 → 検証 → 修正	実時間で約2～4分
モジュール	使用可能になるまで複数のラウンドを経て構築する機能単位	2～15ラウンド
ウェーブ	相互依存関係のないモジュールをまとめた、並列実行可能な単位	1～N個のモジュール
プロジェクト	すべてのウェーブを順次実行し、統合とデバッグを行うもの	各ウェーブの合計

ラウンドは最小単位です。次の反復1回に直接対応します。

1. エージェントが実行内容を考える
2. エージェントがコードを作成・編集する
3. エージェントがコードまたはテストを実行する
4. エージェントが出力を確認する
5. エージェントが修正が必要か判断する（必要な場合は次のラウンドへ）

見積もり手順

タスクの見積もりを求められたら、以下の手順を順番に実行します。

ステップ 1：モジュールに分解する

タスクを機能モジュールに分解します。各モジュールは個別に構築・テストできる必要があります。「一つずつ構築する、明確に異なる要素は何か」と考えてください。

ステップ 2：モジュールごとのラウンド数を見積もる

以下の目安を使って、各モジュールのラウンド数を見積もります。

パターン	典型的なラウンド数	例
定型コード／既知のパターン	1～2	CRUD エンドポイント、設定ファイル、標準 API クライアント
中程度の複雑さ	3～5	カスタム UI レイアウト、状態管理、データパイプライン
探索的／ドキュメント不足	5～10	不慣れなフレームワーク、プラットフォーム固有の API、複雑な統合
不確実性が高い	8～15	ドキュメントにない動作、新しいアルゴリズム、複数システムにまたがるデバッグ

主な調整ルール：

• コードを一度で生成でき、問題なく動く可能性が高い場合 → 1ラウンド
• 生成して実行し、エラーを確認して修正する必要がある場合 → 2～3ラウンド
• ライブラリ／フレームワークのドキュメントが乏しく、推測が必要な場合 → 5ラウンド以上
• プラットフォーム権限、OS レベルの API、またはユーザーによる手動確認が必要な環境固有の動作が関わる場合 → 2～3ラウンド追加

ステップ 3：リスク係数を割り当てる

各モジュールにリスク係数を設定し、ラウンド数を増やします。

リスクレベル	係数	適用する状況
低	1.0	成熟したエコシステム、明確なドキュメント、エージェントが既知のパターンに強く一致
中	1.3	小さな不明点があり、デバッグに1～2ラウンド余分にかかる可能性がある
高	1.5	ドキュメント不足、プラットフォーム特有の問題、統合に関する不明点
非常に高い	2.0	行き詰まる可能性があり、アプローチ全体の変更が必要になる場合がある

ステップ 3.5：ウェーブを構成する（任意 — 並列実行／マルチエージェントの場合）

複数のエージェントがタスクを実行する場合、またはユーザーが最速での完了を求めている場合：

1. 依存関係を整理する：各モジュールについて、依存する他のモジュールを列挙する
2. ウェーブにグループ化する：
   • ウェーブ 1：依存関係のないすべてのモジュール
   • ウェーブ 2：依存先がすべてウェーブ 1 に含まれるモジュール
   • ウェーブ N：依存先がすべて前のウェーブに含まれるモジュール
3. エージェント数を記載する：各ウェーブ内で並列実行できるエージェント数

次の場合は、このステップを省略します。

• 単一エージェントによる逐次実行
• モジュール数が3未満のプロジェクト
• 密接に結合しており、並列化の効果がほとんどないモジュール

ステップ 4：合計を計算する

逐次モード（デフォルトの単一エージェント）：

Module effective rounds = base rounds × risk coefficient
Project rounds = Σ(module effective rounds) + integration rounds
Integration rounds = 10-20% of base total (for wiring modules together)

ウェーブモード（マルチエージェント）：

Wave duration = max(effective rounds of modules in wave)
Project rounds = Σ(wave durations) + coordination rounds + integration rounds
Coordination rounds = 2-3 rounds upfront (contract definition between agents)

ステップ 5：実時間に換算する

最後にのみ、人間の時間に換算します。

Wallclock time = project rounds × minutes_per_round

minutes_per_round のデフォルトは 3 分 です（エージェントの生成時間とユーザーのレビュー時間を含みます）。

状況に応じてこのパラメーターを調整します。

• 反復が速く、ユーザーがほとんどレビューしない → 1 ラウンドあたり 2 分
• 複雑な分野で、ユーザーが各ステップを慎重にレビューする → 1 ラウンドあたり 4 分
• ユーザーが手動でテストする必要がある（モバイル、ハードウェア、権限） → 1 ラウンドあたり 5 分

出力形式

推定結果は必ず次の正確な形式で出力します。

### Task: [task name]

#### Module Breakdown

| # | Module | Base Rounds | Risk | Effective Rounds | Notes |
|---|--------|------------|------|-----------------|-------|
| 1 | ...    | N          | 1.x  | M               | why   |
| 2 | ...    | N          | 1.x  | M               | why   |

#### Summary

- **Base rounds**: X
- **Integration**: +Y rounds
- **Risk-adjusted total**: Z rounds
- **Sequential wallclock**: A – B minutes (at N min/round)

**Wave Execution** (if applicable):
- Wave 1: [modules] → max M rounds
- Wave 2: [modules] → max M rounds
- Coordination overhead: +C rounds
- **Parallel wallclock**: A – B minutes (at N min/round, K agents)
- **Speedup vs sequential**: ~X%

#### Biggest Risks
1. [specific risk and what could blow up the estimate]
2. [...]

避けるべきアンチパターン

このスキルで防ぐべき失敗例は次のとおりです。

1. 人間の所要時間を基準にする：「開発者なら約 2 週間かかるでしょう……」→ いいえ。ラウンド数から始めます。
2. 感覚で時間を水増しする：具体的なリスクの根拠なしに「念のため」時間を追加する → いいえ。リスク係数を使います。
3. 複雑さと作業量を混同する：定型コード 500 行 ≠ 難しい。CGEvent API の 1 行 ≠ 簡単。行数ではなく、不確実性に基づいて見積もります。
4. 統合コストを忘れる：各モジュールは単独では動いても、組み合わせると壊れることがあります。必ず統合ラウンドを追加します。
5. ユーザー側のボトルネックを無視する：ユーザーが手動で権限を付与したり、アプリを再起動したり、デバイスでテストしたりする必要がある場合、ラウンドあたりの時間が余分にかかります。架空のラウンドを追加するのではなく、minutes_per_round を調整します。
6. 並列処理にコストがかからないと思い込む：複数エージェントによるウェーブ実行には調整コスト（契約の定義、競合の解決）がかかります。必ず調整ラウンドを追加します。

キャリブレーションの参考資料

既知のラウンド数を持つプロジェクト例を以下に示します。見積もりの調整に役立ててください。

プロジェクトの種類ごとの詳細な例については、references/calibration-examples.md を参照してください。

評価プロンプト

見積もりの精度を検証するテストケースについては、evals/evals.json を参照してください。