tapd-story-breakdown

name	tapd-story-breakdown
slug	tapd-story-breakdown
version	1.0.0
description	TAPD 需求拆分子技能。对大需求进行拆分，输出各子需求的规范需求文档，严格控制 子需求的内容规模，保障研发交付内容可控、易于测试验证。本技能作为 tapd-story-evaluation 的子技能被调用，不独立触发。
metadata	{"requires":{"mcps":["tapd"]}}

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 继续处理：

## 拆分结果摘要

**父需求**：[父需求名称]（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	子需求文档模板	生成子需求文档时