| 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
- 计算父需求目录名（对父需求
name 字段做文件系统安全清洗，跨平台统一规则）：
- a. 取父需求
name 字段原文
- b. 将以下非法字符替换为
_：/、\、:、*、?、"、<、>、|、换行符
- c. trim 首尾空格
- d. 若长度超过 50 字符则截断为前 50 字符
- 确保
docs/reqs/<父需求目录名>/ 目录存在，不存在则创建（目录已存在不报错，同一
父需求的多个子需求写入同一目录）
- 从子需求名称提炼文件名：最少 8 个字，最多 20 个字，扩展名统一
.md
- 如果同目录下文件名已存在，追加需求短 ID 后缀以区分
- 父需求自身文档：若
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 | 子需求文档模板 | 生成子需求文档时 |
