Work Breakdown

---
name: work-breakdown
description: 将需求拆分为完全独立的垂直切片工作项，每个切片贯穿所有技术层，完成即可独立验证。适用场景："把这个需求拆成几个独立任务"、"怎么并行开发这个功能"、"拆成可以独立领取的工作项"，或需求挖掘完成后需拆分实施计划时。输入需求描述或需求挖掘报告，输出独立工作项清单。
---

# Work Breakdown（工作项拆分）

## 概述

**目的**：将需求拆分为完全独立的垂直切片工作项，每个切片贯穿所有技术层，完成即可独立验证

**功能**：支持按用户行为、数据实体、场景、复杂度等维度进行需求拆分，提供AFK/HITL分类和独立性校验，输出结构化工作项清单

**使用场景**：
- 当需求挖掘完成后需要拆分实施计划时
- 当需要将需求拆成几个独立任务时
- 当需要并行开发功能时
- 当需要在设计之前确定实施单元时

将需求拆成**完全独立**的垂直切片，每个切片端到端贯穿所有层，完成即可独立验证。

## 定位

```
requirement-mining → interaction-design → work-breakdown → 每个切片独立走 design-craft
      理解需求            设计交互层           拆成独立切片         逐个设计+实现
```

- **输入**：需求描述、需求挖掘报告、或交互设计文档
- **输出**：独立工作项清单
- **边界**：只管"怎么拆"，不管"怎么设计"（设计由 design-craft 负责）

## 核心原则

1. **垂直切片**：每个工作项贯穿所有技术层（数据→逻辑→接口→输出），不是按层水平切
2. **真正独立**：切片间无强依赖，可并行设计和实现
3. **完成即可验证**：每个切片完成后都能独立演示或测试，不依赖其他切片
4. **AFK/HITL 分类**：区分 Agent 可独立完成和需要人介入的工作项
5. **不脑补设计**：只拆分工作边界，不规定实现方案

## 工作流总览

```
阶段 1：输入分析          → 读取需求，理解要做什么
阶段 2：分层识别          → 识别涉及的技术层，定义端到端范围
阶段 3：垂直切片拆分      → 按端到端路径拆成独立工作项
阶段 4：独立性校验        → 检查切片间是否有隐含依赖
阶段 5：粒度确认          → 用户确认拆分是否合理
阶段 6：输出工作项清单    → 结构化输出
```

**未得到用户对当前阶段的确认前，不进入下一阶段。**

### 快速通道

当需求同时满足以下全部条件时，跳过阶段 2-4，直接输出单个工作项：

- 只涉及一个用户行为
- 只有一种技术路径
- 不需要 HITL 决策

---

## 阶段 1：输入分析

读取需求来源，提炼关键信息。

### 输入来源

- 需求挖掘报告（requirement-mining 输出）
- 交互设计文档（interaction-design 输出）
- 用户直接描述的需求

### 输出格式

```text
📥 输入分析
━━━━━━━━━━━━━━━━

来源：[需求挖掘报告 / 交互设计文档 / 用户直接描述]

核心目标：<一句话概括>
涉及角色：<角色列表>
关键行为：<用户能做的主要操作>

请确认以上理解是否准确。
```

---

## 阶段 2：分层识别

识别这个需求涉及哪些技术层，确定"端到端"的范围。

### 技术层定义

| 层 | 说明 | 脚本/CLI 示例 | Web 示例 | API 示例 |
|----|------|--------------|----------|----------|
| **数据层** | 持久化、数据模型 | 配置文件、缓存 | 数据库表、文件存储 | 数据库、缓存 |
| **逻辑层** | 业务规则、处理流程 | 核心算法、转换逻辑 | 业务服务、状态机 | 服务层、领域逻辑 |
| **接口层** | 对外交互 | CLI 参数、子命令 | API 端点、页面路由 | REST/GraphQL 端点 |
| **输出层** | 用户感知的结果 | stdout、stderr、退出码 | 页面展示、提示信息 | 响应体、状态码 |

### 输出格式

```text
🏗️ 技术层识别
━━━━━━━━━━━━━━━━

本需求涉及以下层：

| 层 | 说明 |
|----|------|
| 数据层 | [具体描述] |
| 逻辑层 | [具体描述] |
| 接口层 | [具体描述] |
| 输出层 | [具体描述] |

端到端路径：从 [接口层入口] 经 [逻辑层处理] 到 [输出层反馈]

请确认涉及的层是否完整。
```

---

## 阶段 3：垂直切片拆分

### 拆分策略

| 策略 | 适用场景 | 示例 |
|------|----------|------|
| **按用户行为拆** | 一个系统有多个独立操作 | 注册、登录、修改密码 → 三个切片 |
| **按数据实体拆** | 一个系统管理多种数据 | 用户管理、订单管理 → 两个切片 |
| **按场景拆** | 同一功能有多种模式 | 正常流程、异常处理 → 两个切片 |
| **按复杂度拆** | 功能有核心和增强部分 | 基础版、高级版 → 两个切片 |

### 切片规则

每个切片必须满足：

1. **贯穿所有层**：从接口层入口到输出层反馈，路径完整
2. **独立可验证**：完成后能单独演示或测试
3. **不依赖其他切片**：共享依赖有默认值/桩实现可兜底

### AFK / HITL 判定

| 类型 | 含义 | 判定条件 |
|------|------|----------|
| **AFK** | Agent 可独立完成 | 不需要架构决策、不需要业务判断、不需要设计评审 |
| **HITL** | 需要人介入 | 需要做决策（如模型选型）、需要评审（如交互设计）、需要外部确认（如第三方接入） |

### 输出格式

```text
🔀 垂直切片
━━━━━━━━━━━━━━━━

| 编号 | 切片名称 | 类型 | 贯穿的层 | 独立验证方式 |
|------|----------|------|----------|-------------|
| W-01 | ... | AFK/HITL | 数据+逻辑+接口+输出 | ... |

【切片说明】
- W-01：<一句话描述端到端路径>
- W-02：<一句话描述端到端路径>
...
```

---

## 阶段 4：独立性校验

对每对切片做独立性检查。

### 判定标准

| 判定 | 条件 | 处理 |
|------|------|------|
| ✅ 可独立 | 共享依赖是只读的，或各自有独立实现路径 | 无需处理 |
| ⚠️ 弱依赖 | 共享依赖有默认值/桩实现可兜底 | 标注兜底方案 |
| ❌ 强依赖 | 一个切片必须等另一个完成才能开始 | 合并或重新拆分 |

### 输出格式

```text
🔍 独立性校验
━━━━━━━━━━━━━━━━

| 切片对 | 共享依赖 | 独立性 | 处理 |
|--------|----------|--------|------|
| W-01 ↔ W-02 | ... | ✅/⚠️/❌ | ... |

【校验结论】
- 可并行：[列出可并行的切片]
- 需等待：[列出有依赖的切片及原因]
- 兜底方案：[列出 ⚠️ 的处理方式]

如出现 ❌ 强依赖，请选择：
1. 合并为一个切片
2. 重新拆分以消除依赖
3. 明确标注依赖顺序
```

---

## 阶段 5：粒度确认

向用户展示拆分方案，确认合理性。

### 确认清单

```text
📋 拆分方案确认
━━━━━━━━━━━━━━━━

共拆出 N 个切片：X 个 AFK，Y 个 HITL

请确认：
1. 粒度是否合理？（太粗 → 拆更细；太细 → 合并）
2. 是否有遗漏的切片？
3. AFK/HITL 分类是否准确？
4. 独立性校验中 ⚠️ 的处理方案是否可接受？
```

### 回退机制

- **粒度调整**：用户可要求合并或进一步拆分某个切片
- **遗漏补充**：用户可要求增加新切片
- **重新拆分**：用户可要求从阶段 3 重新开始

---

## 阶段 6：输出工作项清单

将确认后的切片输出为结构化工作项清单。

### 输出格式

```text
✅ 工作项清单
━━━━━━━━━━━━━━━━

| 编号 | 工作项 | 类型 | 涉及层 | 验收标准 |
|------|--------|------|--------|----------|
| W-01 | ... | AFK/HITL | ... | ... |

【实施建议】
- 可并行：[列出可并行的工作项]
- 需等待：[列出有依赖的工作项]
- 建议顺序：[推荐的实施顺序]
- HITL 项：[需要先完成人工决策的工作项]

下一步：
- 每个工作项可独立进入 design-craft 进行技术设计
- HITL 项需要先完成人工决策后再设计
```

### 质量自检

```text
🔍 质量自检
━━━━━━━━━━━━━━━━

☐ 每个切片都贯穿所有涉及的技术层
☐ 每个切片都有独立验证方式
☐ 切片间无 ❌ 强依赖
☐ AFK/HITL 分类合理
☐ 验收标准具体可判断
☐ 遗漏检查：所有用户行为都有对应切片
```

```text
🚀 后续行动选择
━━━━━━━━━━━━━━━━

工作项拆分已完成，报告已输出。请选择后续行动：

1. 📁 落盘归档
   将工作项清单保存到 .requirements/ 目录，便于后续引用和管理

4. 🔍 对第一个需求进行需求挖掘
   使用 requirement-mining 技能对拆分后的第一个工作项进行深度需求挖掘，打穿表象找到根因

5. ⏭️ 跳过
   不进行后续操作，结束工作项拆分流程

请选择 [1/4/5]：
```

---

## 与 design-craft 的衔接

工作项清单产出后，每个切片可独立进入 design-craft：

- **AFK 切片**：直接进入 design-craft，走完整设计流程
- **HITL 切片**：先完成人工决策，再进入 design-craft
- **有 ⚠️ 弱依赖的切片**：design-craft 阶段 2.3（交互对象总览）时明确兜底方案

## 反模式

- ❌ 按技术层水平切分（"先做数据库，再做 API，再做前端"）→ 不是垂直切片
- ❌ 切片间有强依赖却不合并 → 无法并行，失去拆分意义
- ❌ 切片粒度太粗（一个切片包含多个独立操作）→ 无法独立验证
- ❌ 切片粒度太细（一个函数一个切片）→ 切片数量爆炸，管理成本高
- ❌ 在拆分阶段规定实现方案 → 越界，设计由 design-craft 负责
- ❌ 忽略 HITL 标记 → Agent 尝试自主完成需要人决策的工作

## 需求管理集成

当项目配置了 `.requirements/config` 时，work-breakdown 在输出工作项清单（阶段 6）后自动执行以下集成操作：

### 自动触发条件

项目中存在 `.requirements/config` 且 `storage_path` 指向有效目录。

### 集成步骤

1. **获取需求上下文**：如果用户提供了 REQ-ID，先读取需求信息作为拆分输入：

```bash
req list --id {REQ-NNN} --deps
```

2. **写入工作项清单**到需求目录后，调用 `req update` 注册文档关联：

```bash
req update {REQ-NNN} \
  --docs add design/work-breakdown.md,design --changelog "完成工作项拆分"
```

3. **错误处理**：
   - 需求 ID 不存在 → 提示用户先创建需求，跳过集成
   - 文件锁超时 → 自动重试 1 次，仍失败则告知用户

### 存储路径映射

| 产出物 | 存储路径 | docs 类型 |
|--------|----------|-----------|
| 工作项清单 | `design/work-breakdown.md` | `design` |