| name | tapd-story-clarification |
| slug | tapd-story-clarification |
| version | 1.0.0 |
| description | TAPD 需求澄清技能。从 TAPD 提取"规划中"状态的需求，按照研发最佳实践对需求进行
多维度澄清（业务逻辑、外部系统交互、上下文），整合项目背景知识，输出符合需求文档
规范的标准化 Markdown 需求文档，并回写 TAPD。
Use this skill whenever the user mentions 需求澄清, 澄清需求, clarify story,
clarify requirement, 需求细化, 需求整理, 需求规范化, 补充需求, 完善需求描述,
story clarification, requirement clarification, 需求文档整理,
or any workflow involving TAPD story description refinement and standardization.
|
| metadata | {"requires":{"mcps":["tapd"]}} |
TAPD 需求澄清
概述
本技能从 TAPD 提取处于"规划中"状态的需求，采用研发最佳实践（5W1H 结构化提问、
BDD 验收标准、流程可视化）对需求进行多维度澄清，结合项目背景知识生成标准化需求
文档，最终回写到 TAPD 需求描述字段并推进状态。
前置条件
- TAPD MCP 服务可用
- 用户提供至少一个需求 ID
- workspace_id 可由用户提供，或从项目根目录
project.json 读取
- 支持 macOS / Linux / Windows 系统（所有文件操作和命令均使用跨平台方式）
输入
| 参数 | 来源 | 必需 | 说明 |
|---|
| 需求 ID | 用户输入 | 是 | 一个或多个 TAPD 需求短 ID |
| workspace_id | 用户输入 > project.json | 是 | TAPD 工作空间 ID |
| 背景知识 | 用户指定 > AGENTS.md 自动查找 | 否 | 架构文档、模块文档、安全规范等路径 |
执行流程
1. 参数收集与环境准备
1.1 确定 workspace_id
按以下优先级确定：
- 用户消息中显式指定 → 直接使用
project.json 中的 workspace_id → 使用 read_file 读取并解析- 以上均无 → 询问用户
1.2 收集背景知识
按以下优先级确定：
- 用户显式指定背景文档路径 → 读取指定文档
- 用户未指定 → 读取项目根目录
AGENTS.md，从中识别项目的架构文档、模块文档、
规范文档、API 文档等（具体路径因项目而异，按 AGENTS.md 中的描述定位）
只读取实际存在的文档，不存在的跳过。将收集到的背景知识作为后续澄清的参考上下文。
1.3 解析需求 ID 列表
从用户输入中提取所有需求 ID，构建待处理列表。如果 ID 长度小于 19 位，后续调用
TAPD MCP 时会自动转换。
2. 逐一处理需求
对每个需求 ID 执行以下流程（顺序执行，完成一个再处理下一个）：
2.1 提取需求详情
使用 TAPD MCP stories_get 提取需求信息：
调用参数:
workspace_id: <workspace_id>
id: <需求ID>
with_v_status: "1"
v_status: backlog
如果查询结果为空：
- 提示用户该需求不存在或状态不是"backlog"
- 跳过该需求，继续处理下一个
提取成功后记录需求的关键信息：
id（完整 19 位 ID）name（需求名称）description（原始需求描述）priority_label（优先级）owner（处理人）parent_id（父需求 ID，用于判断是否子需求）detail_link（TAPD 详情链接）
2.2 需求澄清
整合背景知识与需求原始描述，按照 references/clarification-guide.md 中的最佳
实践进行多维度澄清。
执行前必读 references/clarification-guide.md，其中定义了完整的澄清维度
（业务价值、用户故事、验收标准、外部系统交互、数据模型、非功能需求、边界条件）
和各维度的具体检查项。按需求复杂度选择需要覆盖的维度子集。
澄清流程
- 通读需求描述，结合背景知识，按上述七个维度逐一排查信息缺失
- 整理问题清单，所有问题统一编号，一次性向用户提出（避免碎片式逐条追问）：
- 问题需要可行的选择项A、B、C等（便于用户选择）
- 🔴 阻塞性问题放前面（缺少这些信息无法开始实现）
- 🟡 非阻塞性问题放后面（可以先假设后确认）
- 等待用户回复，可能需要多轮对话：
- 用户提供接口文档路径时，直接读取文档提取关键信息
- 用户提供设计稿链接时，记录链接地址
- 对于用户无法即时回答的问题，记录为"待确认"
- 确认理解：将澄清结论复述给用户确认，避免理解偏差
跳过澄清的条件
以下情况可以简化或跳过交互式澄清：
- 用户明确表示"需求我很清楚，不需要澄清"
- 用户主动提供了完善的设计文档和接口文档
- 需求非常简单（如纯文案修改、配置变更）
- 原始需求描述已经非常完善，覆盖了全部澄清维度
即使跳过，也要在文档中标注"用户确认需求描述充分，无需额外澄清"。
2.3 生成规范化需求文档
整合原始需求信息和澄清内容，按照 references/requirement-doc-template.md 中的
文档模板生成标准化 Markdown 需求文档。
文档生成规则
- 原始需求描述必须完整保留在"原需求描述"章节
- 澄清过程中的问答必须记录在"澄清记录"章节
- 信息充分的章节详细填写，信息不足的标注"待确认"
- 所有验收标准必须使用 Given-When-Then 格式
- 性能指标必须使用可量化的数字
- 避免使用"较快""较好"等模糊词汇
- 脱敏要求（强制）：写入仓库的文档严禁包含个人敏感信息——
- 不写入
owner/处理人/负责人 等真实人名（基本信息、未解决问题等处一律省略人名）；
- 不写入 TAPD 内网域名链接（
detail_link），引用 TAPD 单据时仅保留数字 ID（完整 19 位 ID 与短 ID）；
owner/detail_link 仅用于 TAPD 接口交互与本会话提示，不落入文档正文。
文档保存
生成需求文档后，将文档保存为本地 Markdown 文件，存放在项目根目录的 docs/reqs/
下。
文件命名规则：
从需求名称中提炼核心关键词作为文件名，要求：
- 长度：最少 4 个字，最多 10 个字
- 去除需求名称中的修饰词、量词、连接词等冗余成分，保留最能概括需求本质的关键词
- 使用中文
- 文件扩展名统一为
.md
- 如果文件名已存在，追加需求短 ID 后缀以区分（如
用户权限管理_12345.md）
命名示例：
| 需求名称 | 提炼后文件名 |
|---|
| 新增用户权限管理模块 | 用户权限管理.md |
| 优化首页加载性能提升用户体验 | 首页性能优化.md |
| 对接第三方支付系统完成订单结算 | 三方支付对接.md |
| Add OAuth2 login support | OAuth2登录.md |
保存流程：
- 确保
docs/reqs/ 目录存在，不存在则创建
- 从需求名称提炼 4-10 字文件名
- 检查同名文件是否已存在，若存在则追加需求短 ID 后缀
- 将完整需求文档写入该文件
- 告知用户文件保存路径
2.4 用户确认
将生成的需求文档展示给用户，请求确认：
- 文档内容是否准确完整
- 是否有需要调整的部分
- 确认后进入回写步骤
如果用户提出修改意见，修改文档后再次确认，直到用户满意。
2.5 回写 TAPD
⚠️ 前置操作：调用 stories_update 前，必须先通过读取 §2.3 保存的本地文件（docs/reqs/<文件名>.md）获取完整文档内容，将读取结果作为 description 参数值传入，禁止将上下文中的文档内容直接 inline 到调用参数。
使用 TAPD MCP stories_update 将最终需求文档以markdown格式全量更新至TAPD（无需精简信息）：
调用参数:
workspace_id: <workspace_id>
id: <需求完整19位ID>
description: <读取本地文件 docs/reqs/<文件名>.md 所得的完整内容>
v_status: approved
回写成功后记录：
回写失败时：
- 重试一次
- 仍失败则告知用户，输出文档内容供用户手动更新
3. 汇总输出
所有需求处理完毕后，简短总结输出处理内容：
## 需求澄清完成
| 需求 ID | 需求名称 | 处理结果 | 状态 | 本地文件 |
|---------|---------|---------|------|---------|
| xxx | xxx | ✅ 已澄清并回写 | approved | docs/reqs/xxx.md |
| yyy | yyy | ⚠️ 回写失败，文档已输出 | backlog | docs/reqs/yyy.md |
共处理 N 个需求，成功 M 个，失败 K 个。
错误处理
| 错误场景 | 处理方式 |
|---|
| TAPD MCP 不可用 | 终止执行，提示用户检查 MCP 配置 |
| 需求 ID 不存在 | 跳过该需求，继续处理下一个 |
| 需求状态不是"backlog" | 提示用户，询问是否仍要澄清（可能已被处理过） |
| 回写 TAPD 失败 | 重试一次，仍失败则输出文档供手动更新 |
| 用户中断澄清 | 保存当前内容，标注"澄清未完成" |
参考文件
| 文件 | 用途 | 何时读取 |
|---|
references/clarification-guide.md | 需求澄清最佳实践指南 | 执行澄清时 |
references/requirement-doc-template.md | 标准化需求文档模板 | 生成文档时 |
产出
- 规范化需求文档保存至
docs/reqs/<提炼文件名>.md（4-10 字精简文件名）
- TAPD 需求
description 字段更新为规范化需求文档
- TAPD 需求状态更新为"backlog"
- 控制台输出处理汇总（含本地文件保存路径）
