# Agent 任务拆解规范（v2）

> 2026-05-31 从红尘提供的拆解框架内化 + 自审迭代
> 本版本修复了 v1 的 6 个已知漏洞

## 核心原则

1. **Agent Package 是可被单个 Agent 独立完成的最小工作单元**
2. **优先考虑上下文容量**，不追求任务少，追求一次能完成
3. **禁止出现 XL 级任务**（耗时 > 120分钟）
4. **最大化并行能力**，多个 Agent 同时启动
5. **每个包必须有明确的风险评估**，不能无脑分工

## 任务拆解流程

```
Step1：构建项目全景图
  ├─ 产品层 / 前端层 / 后端层 / 数据层
  ├─ 中间件层 / 基础设施层 / 运维层 / 测试层
  └─ 形成系统架构地图（8层全覆盖）

Step2：构建模块树
  └─ 按业务域划分模块（用户系统/资源系统/评论系统...）
  └─ 每模块标注：P0/P1/P2/P3 优先级

Step3：构建依赖图
  ├─ 模块依赖（模块A → 模块B）
  ├─ 数据依赖（表A → 表B）
  ├─ API依赖（接口A → 接口B）
  └─ 开发顺序依赖（必须先做什么）

Step4：任务拆解（逐层）
  模块 → Feature → Task → Agent Package
  每步检查：是否拆到可独立交付的最小粒度？
```

## Agent Package 标准格式

```
## Agent-ID: P<优先级>-<序号>

### Objective
任务目标（一句话说清）

### Scope
影响范围（模块/层/文件范围）

### Inputs
需要阅读的文件（列出具体路径，≤15个）

### Outputs
需要产出的内容（代码/配置/文档/脚本）

### Dependencies
依赖哪些 Agent Package（用 ID 引用）

### Deliverables
交付物清单（具体文件路径）

### Acceptance Criteria
验收标准（可测试、可验证的条件）

### Risk Assessment
风险评估（每个包单独评估，见下方 Risk 分类）

### Estimated Complexity
复杂度评估（Small / Medium / Large，XL禁止）

### Efficiency Score
效率评分（1-10，[8,10]为合格，<8 需重构边界）
```

## Task Size 等级

| 等级 | 耗时 | 阅读文件 | 修改文件 | 新增代码 |
|------|------|----------|----------|----------|
| Small | 5-15min | ≤ 3 | ≤ 2 | ≤ 300行 |
| Medium | 15-45min | ≤ 8 | ≤ 5 | ≤ 800行 |
| Large | 45-120min | ≤ 15 | ≤ 10 | ≤ 1500行 |
| XL | > 120min | ❌ 禁止 | ❌ 禁止 | ❌ 禁止 |

## XL → Large 拆分策略

如果发现 XL，按以下策略拆解（不直接说"禁止"了事）：

```
XL 任务
├─ 跨模块拆分 → 每个模块独立为一个 Medium
├─ 跨层拆分   → 前端/后端/数据库各为一个 Medium
├─ 大文件拆分 → 核心逻辑 / 辅助逻辑 / 配置 各为一个 Small
├─ 复杂业务流 → 按步骤拆为链式 Small（A→B→C）
└─ 大代码量   → 按功能切片，每片 ≤ 300 行
```

## 效率评分规则

每个 Agent Package 从 4 个维度评分，加总后 [1, 10]：

```
Complexity（复杂度）：1=单文件修改，3=多文件联动，5=跨模块
Context Usage（上下文使用率）：1=读满15个文件，3=读8个，5=读3个
Dependency Count（依赖数）：1=依赖3+个包，3=依赖1-2个，5=零依赖
Parallelism（可并行度）：1=阻塞链中，3=可部分并行，5=完全独立
```

**公式：** `Score = (Complexity + Context + Dependencies + Parallelism) × 0.5`

**合格线：≥ 8**。低于 8 分继续拆分或重构任务边界。

## 风险分析

每个 Agent Package 必须评估以下风险，写出规避方式：

| 风险类型 | 检查项 |
|----------|--------|
| 架构风险 | 是否引入新依赖？是否改变模块边界？ |
| 数据风险 | 是否改数据库结构？是否有迁移脚本？ |
| 并发风险 | 是否有资源竞争？是否有锁问题？ |
| 安全风险 | 是否涉及鉴权？是否有输入校验？ |
| Agent 协作风险 | 依赖的其他包失败如何自救？ |
| 上下文超限风险 | 是否需要的上下文超出预算？ |

## Large 任务审查

只有 Large 及以上需要此审查：

```
## Large Task Justification

1. 为什么无法继续拆分？
2. 为什么需要多个文件协同？
3. 为什么仍适合单 Agent 完成？

如果解释不成立 → 自动重新拆分。
```

## 开发路线图

| 等级 | 内容 | 特征 |
|------|------|------|
| **P0** | 核心基础设施 | 数据库、认证、基础框架 |
| **P1** | 核心业务功能 | 主要业务逻辑、关键 API |
| **P2** | 增强功能 | 辅助业务、优化功能 |
| **P3** | 优化功能 | 性能、UI 打磨、文档 |

## 依赖图输出格式

```
P0-01: 用户模型（无依赖）
   ↓
P1-01: 注册API（依赖P0-01）
   ↓（可并行）
P1-02: 文章模型（无依赖）
   ↓
P2-01: 文章CRUD（依赖P1-01, P1-02）
```

## 最终自检

输出前逐项检查：

- [ ] 所有 Agent Package 总耗时是否 > 2小时？（每包单独评估，不是总时间）
- [ ] 是否存在 XL 任务？（不直接说"禁止"→ 给出拆分方案）
- [ ] 是否存在上下文超限任务？（阅读 > 15 文件？修改 > 10 文件？新增 > 1500 行？）
- [ ] 是否存在不可并行的阻塞链？（A→B→C→D→E 这种长链要优化）
- [ ] 是否存在跨业务域任务？（→ 必须拆分）
- [ ] 是否存在效率评分 < 8 的包？
- [ ] 是否存在没有风险评估的包？
- [ ] 是否存在循环依赖？

如果任意一项为"是" → 自动重新拆分 → 直到全部通过。