agent-estimation

Agent 工作量估算技能

问题

AI 编码 Agent 系统性地高估任务耗时，因为它们会以训练数据中吸收的人类开发者时间线为基准。Agent 可以在 30 分钟内完成的任务，却会被估算为“2-3 天”，因为人类开发者论坛帖子通常会这么说。

解决方案

强制 Agent 根据自身的操作单位——工具调用轮次——进行估算，并且只在最后才换算成人类的实际耗时。

核心单位

单位	定义	规模
轮次	一个工具调用周期：思考 → 编写代码 → 执行 → 验证 → 修复	约 2-4 分钟实际耗时
模块	由多个轮次构建而成的功能单元，直至可用	2-15 轮
波次	一批没有相互依赖关系、可并行执行的模块	1-N 个模块
项目	所有波次依次执行，再加上集成和调试	各波次之和

轮次是最小单位。它直接对应以下迭代过程：

1. Agent 分析要做什么
2. Agent 编写／编辑代码
3. Agent 运行代码或测试
4. Agent 阅读输出
5. Agent 判断是否需要修复（如果需要 → 进入下一轮）

估算流程

收到任务估算请求时，请按以下步骤依次执行：

步骤 1：拆分为模块

将任务拆分为功能模块。每个模块都应能独立构建和测试。问问自己：“有哪些不同的部分需要我逐一构建？”

步骤 2：估算每个模块所需轮次

使用以下基准估算每个模块所需的轮次：

模式	典型轮次	示例
样板代码／已知模式	1-2	CRUD 端点、配置文件、标准 API 客户端
中等复杂度	3-5	自定义 UI 布局、状态管理、数据管道
探索性／文档不完善	5-10	不熟悉的框架、特定平台 API、复杂集成
高度不确定	8-15	未记录的行为、新颖算法、多系统调试

关键校准规则：

• 如果可以一次性生成代码，且代码很可能能够运行 → 1 轮
• 如果需要生成代码、运行、查看错误并修复 → 2-3 轮
• 如果库／框架的文档稀少，需要边猜边做 → 5 轮以上
• 如果涉及平台权限、操作系统级 API，或需要用户手动验证的环境特定行为 → 增加 2-3 轮

步骤 3：分配风险系数

为每个模块分配一个风险系数，以增加其轮次数：

风险等级	系数	适用情况
低	1.0	生态成熟、文档清晰、Agent 对相关模式有较强匹配能力
中	1.3	存在少量未知因素，可能需要额外 1-2 轮调试
高	1.5	文档稀少、存在平台差异、集成情况未知
很高	2.0	可能走入死胡同，或需要彻底改变方案

步骤 3.5：构建波次（可选——适用于并行／多 Agent 场景）

如果任务将由多个 Agent 执行，或用户要求尽快完成：

1. 梳理依赖关系：为每个模块列出它依赖的其他模块
2. 分组为波次：
   • 波次 1：所有没有依赖关系的模块
   • 波次 2：依赖项全部位于波次 1 的模块
   • 波次 N：依赖项全部位于之前波次的模块
3. 注明 Agent 数量：每个波次中可以并行运行的 Agent 数量

以下情况跳过此步骤：

• 单 Agent 顺序执行
• 少于 3 个模块的项目
• 模块之间耦合紧密，并行执行收益微乎其微

步骤 4：计算总量

顺序模式（默认，单 Agent）：

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)

波次模式（多 Agent）：

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 分钟（包括 Agent 生成时间和用户审核时间）。

根据具体情况调整此参数：

• 快速迭代，用户几乎不审核 → 每轮 2 分钟
• 领域复杂，用户仔细审核每个步骤 → 每轮 4 分钟
• 用户需要手动测试（移动设备、硬件、权限）→ 每轮 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 行样板代码 ≠ 难。1 行 CGEvent API ≠ 简单。应根据不确定性而非行数估算。
4. 忘记集成成本：模块单独运行正常，组合起来却出问题。始终增加集成轮次。
5. 忽视用户侧瓶颈：如果用户必须手动授予权限、重启应用或在设备上测试，就需要增加每轮耗时。调整 minutes_per_round，不要凭空增加轮次。
6. 假设并行不需要成本：多 Agent 波次执行存在协调成本（定义契约、解决冲突）。始终增加协调轮次。

校准参考

以下是一些已知轮次数的项目示例，可用于校准：

请参阅 references/calibration-examples.md，了解不同项目类型的详细示例。

评估提示词

请参阅 evals/evals.json，查看用于验证估算准确性的测试用例。