AI agent skill · by @TencentBlueKing

Tapd Story Breakdown

TAPD 需求拆分子技能。对大需求进行拆分，输出各子需求的规范需求文档，严格控制 子需求的内容规模，保障研发交付内容可控、易于测试验证。本技能作为 tapd-story-evaluation 的子技能被调用，不独立触发。

Archived 2026-10-23 · Source updated 2026-10-10. Check the original repository for the latest version.

SKILL.md instructions

# TAPD 需求拆分

## 概述

对大需求进行拆分，输出各子需求的规范需求文档。拆分的核心目标是严格控制子需求的
内容规模，保障研发交付内容可控，保障研发交付内容易于测试、验证。

> 本 skill 可被主 skill `tapd-story-evaluation` **反复调用**：当某子需求评分后工时
> 超过 24 人时上限时，主 skill 会将该子需求作为新的输入再次调用本 skill 做二次/N 次
> 拆分（见 `../SKILL.md` §2.5）。本 skill 自身不感知"首次/二次"，对任意输入需求执行
> 相同拆分逻辑。

## 输入

| 参数 | 来源 | 说明 |
|------|------|------|
| 需求详情 | 主 skill 传入 | 包含需求 ID、名称、描述（规范需求文档）、优先级等 |
| workspace_id | 主 skill 传入 | TAPD 工作空间 ID |
| 背景知识 | 主 skill 传入 | 架构文档、模块文档、安全规范等 |

## 执行流程

### 1. 评估是否需要拆分（综合判定）

拆分判据须综合"用户故事数"与"规模档位"两个维度，
参照 `../references/requirement-splitting-guide.md` §5、§6 执行：

#### 1.1 统计用户故事数

通读需求描述，统计用户故事数量。判断依据：每个独立的"作为[角色]，我想要[功能]，
以便于[价值]"对应一个用户故事；无明确用户故事格式时，按独立核心功能模块数量统计。

#### 1.2 规模定性快判

按 `../references/requirement-splitting-guide.md` §5 的五维表（实现范围 / 技术复杂度 /
依赖 / 风险 / 验证成本）对需求做**定性快判**（高/中/低），得出综合规模档位。
维度名称与 `size-difficulty-standard.md` 完全一致，仅粒度不同（定性 vs 定量）。

#### 1.3 综合判定动作

按 `../references/requirement-splitting-guide.md` §6 综合判定矩阵决策：

| 用户故事数 | 综合规模 | 动作 |
|-----------|-----------|------|
| ≤2 | 低 / 中 | 不拆 → 输出无需拆分结果，流程结束 |
| ≤2 | 高（预判 >24 人时） | 拆（按功能点 / 技术层次细拆）→ 进入步骤 2 |
| >2 | 低（合计 <8 人时碎故事）| 合并为 1–2 个子需求 → 进入步骤 2 |
| >2 | 中 / 高 | 拆（常规逻辑）→ 进入步骤 2 |

**合并场景说明**：当判定为"合并"时，步骤 3 不再细分，而是将碎故事整合为 1–2 个
内聚的子需求文档；仍须通过步骤 4 的追溯矩阵与一致性检查。

### 2. 获取需求长 ID

使用 TAPD MCP `tapd_id_get` 获取需求的 19 位长 ID（如果输入的是短 ID）：

```
调用参数:
  workspace_id: <workspace_id>
  id: <需求短ID>
  type: "story"
```

记录长 ID，后续子需求文档中需引用。

### 3. 执行需求拆分

参照 `../references/requirement-splitting-guide.md` 中的原则与方法进行拆分。

#### 3.1 分析拆分维度

结合背景知识，从以下维度分析需求的拆分方式：

- **按功能模块拆分**：基于接口定义、公共功能库、前端模块、后端模块逻辑划分
- **按业务流程拆分**：按用户操作流程分段，识别关键节点和决策点
- **按技术层次拆分**：前端交互层、业务逻辑层、数据访问层、外部集成层

选择最合适的拆分维度（或组合使用），确保拆分结果符合 MECE 原则。

> **接口契约先行触发判断**：完成维度拆分后，结合 §3.2 依赖分析结果判断——
> 若子需求之间形成跨子需求强依赖链，则按
> `../references/requirement-splitting-guide.md` §5 启用"接口契约先行"，
> 抽取单个"接口契约构建"子需求作为前置依赖基线；若子需求本就相互独立/仅弱依赖，
> 则不启用，直接标注可并行。契约先行是解依赖手段，按需触发，避免过度设计。

#### 3.2 分析子需求依赖关系

明确各子需求之间的依赖关系：
- **强依赖**：必须按顺序实现（如 B 依赖 A 的接口）
- **弱依赖**：可并行开发（如共用同一数据库表但功能独立）
- **可选依赖**：根据配置决定是否实现

**契约先行下的依赖降级与分波**（当 §3.1 判定启用契约先行时）：

- **依赖降级**：把其余子需求原本"依赖某子需求实现"的强依赖，改写为"依赖接口契约构建子需求"的弱依赖，使其可照契约并行开发。
- **并发波次**：接口契约构建子需求为 **Wave 1**（串行前置）；其余子需求编入 **Wave 2 及以后**，同波次内可并行。仅当某子需求还依赖另一子需求的运行时产物（而非契约）时才顺延波次。
- 详见 `../references/requirement-splitting-guide.md` §5。

#### 3.3 生成子需求文档

参照 `../references/requirement-doc-template.md` 为每个子需求输出规范需求文档，
每个子需求文档必须包含：

- **基本信息**：子需求名称、父需求短 ID 及 19 位长 ID、优先级
- **依赖信息**：依赖的其他子需求 ID 和名称
- **用户故事**：不超过 2 个
- **核心功能点**：清晰定义输入/输出/处理逻辑
- **验收标准**：使用 Given-When-Then 格式
- **边界范围**：本子需求包含和不包含的内容

#### 3.4 保存子需求文档（父需求名子目录隔离）

子需求文档统一保存到**以父需求名命名的子目录**下，使父子关系在文件树中可见：

**保存路径**：`docs/reqs/<父需求目录名>/<子需求文件名>.md`

1. **计算父需求目录名**（对父需求 `name` 字段做文件系统安全清洗，跨平台统一规则）：
   - a. 取父需求 `name` 字段原文
   - b. 将以下非法字符替换为 `_`：`/`、`\`、`:`、`*`、`?`、`"`、`<`、`>`、`|`、换行符
   - c. trim 首尾空格
   - d. 若长度超过 **50 字符**则截断为前 50 字符
2. 确保 `docs/reqs/<父需求目录名>/` 目录存在，不存在则创建（目录已存在不报错，同一
   父需求的多个子需求写入同一目录）
3. 从子需求名称提炼文件名：**最少 8 个字，最多 20 个字**，扩展名统一 `.md`
4. 如果同目录下文件名已存在，追加需求短 ID 后缀以区分
5. **父需求自身文档**：若 `docs/reqs/<父需求目录名>.md`（与子目录同名的平铺文件）已存在，
   **保持原路径不动**，仅子需求进子目录，避免破坏既有引用

**命名示例**（父需求名为 `用户权限管理系统`）：

| 子需求名称 | 保存路径 |
|-----------|---------|
| 用户权限管理模块开发 | `docs/reqs/用户权限管理系统/用户权限管理模块开发.md` |
| 支付接口对接与状态跟踪 | `docs/reqs/用户权限管理系统/支付接口对接与状态跟踪.md` |

**父需求名清洗示例**：

| 父需求原名 | 清洗后目录名 |
|-----------|------------|
| `订单/支付:系统?` | `订单_支付_系统_` |
| `  报表中心  ` | `报表中心` |

> **跨平台提示**：创建目录和写入文件时，使用 Agent 内置的文件操作工具（如
> `write_to_file`），避免依赖特定操作系统的 Shell 命令。路径分隔符统一使用 `/`，
> Agent 工具会自动适配操作系统。

### 4. 拆分后完整性与一致性校验

拆分产出子需求文档后**强制执行**本步，作为拆分完成的准出门禁。方法论详见
`../references/requirement-splitting-guide.md` §七。

#### 4.1 追溯矩阵生成

按 `../references/requirement-splitting-guide.md` §7.1 从父需求文档抽取 8 类信息元素（功能点 / 业务规则 / NFR / 数据实体 / AC / 术语 / 异常流 / 共享约束），按 §7.2 构建 Element-centric 追溯矩阵，计算覆盖率。

**通过条件**：覆盖率 ≥ 95% **且** 无 ❌ 元素。异常边界（父需求元素数 = 0）按 §7.1 处理，视为通过。

#### 4.2 一致性检查

按 §7.3 逐项判定 6 项二值检查：契约自洽 / 依赖无环 / 共享约束归属 / AC 承接 / 术语一致 / Wave 编排。任一项不通过须输出定位信息（如成环路径、断链的 AC 编号）。

**通过条件**：6 项全部通过。

#### 4.3 校验不通过时的处理

按 §7.4 走"先补丁后重拆"策略，回拨预算总计 2 次（补丁 1 + 整体重拆 1）：

- 第 1 次不通过 → 按 §7.4.1 分类判定表决定「补丁」或「直接整体重拆」，按 §7.4.2 执行动作后重跑 §4.1 + §4.2
- 第 2 次仍不通过 → 整体重拆（丢弃当前拆分产物，重新执行本 SKILL §3），完成后重跑校验
- 第 3 次仍不通过 → 保留当前产物，输出未通过项摘要（含追溯矩阵 Gap 元素、一致性检查失败项及定位信息），交主 SKILL 在汇总输出中标注"待用户手动处理"，不阻塞后续流程

**产出**：追溯矩阵表格 + 覆盖率数值 + 一致性检查结果（含定位信息），由步骤 5 汇总输出到拆分结果摘要。

### 5. 输出拆分结果

输出结构化的拆分结果，供主 skill 继续处理：

```markdown
## 拆分结果摘要

**父需求**：[父需求名称]（ID: [短ID] / [19位长ID]）
**子需求数量**：N

| 序号 | 子需求名称 | 用户故事数 | 依赖关系 | 波次 | 本地文件 |
|------|-----------|-----------|---------|------|---------|
| 1 | 接口契约构建 | 1 | 无 | Wave 1 | docs/reqs/<父需求目录名>/接口契约构建.md |
| 2 | xxx | 2 | 弱依赖 #1（契约）| Wave 2（可并行）| docs/reqs/<父需求目录名>/xxx.md |
| 3 | yyy | 1 | 弱依赖 #1（契约）| Wave 2（可并行）| docs/reqs/<父需求目录名>/yyy.md |

> "波次"列表达开发编排顺序：Wave 1 为契约前置，同波次子需求可并行。
> 未启用契约先行时，无契约子需求，各独立子需求同列 Wave 1（可并行）。

**追溯覆盖率**：18/18（100%）
**一致性检查**：6/6 通过
```

## 错误处理

| 错误场景 | 处理方式 |
|---------|---------|
| TAPD MCP `tapd_id_get` 调用失败 | 使用已有的短 ID 继续，在文档中标注"长 ID 待补充" |
| 追溯矩阵或一致性检查不通过 | 按 §4.3 走"补丁 → 整体重拆 → 交用户"三步（回拨预算 2 次），仍不通过则标注问题并输出，不阻塞后续流程 |
| 文件保存失败 | 将文档内容输出到控制台，提示用户手动保存 |

## 参考文件

| 文件 | 用途 | 何时读取 |
|------|------|---------|
| `../references/requirement-splitting-guide.md` | 拆分原则与方法 | 执行拆分前 |
| `../references/requirement-doc-template.md` | 子需求文档模板 | 生成子需求文档时 |