spec-to-backlog

规范转待办事项

概述

自动将 Confluence 规范文档转换为结构化的 Jira 待办事项列表。此技能会从 Confluence 读取需求文档，智能地将其拆分为逻辑清晰的实施任务，先创建 Epic 来组织工作，然后生成关联到该 Epic 的各个 Jira 工单，从而免去繁琐的手动复制粘贴。

核心工作流

重要：始终严格按以下顺序执行：

1. 获取 Confluence 页面 → 获取规范内容
2. 询问项目键 → 确定目标 Jira 项目
3. 分析规范 → 拆分为逻辑清晰的任务（仅在内部进行，暂不创建）
4. 展示拆分结果 → 向用户展示计划创建的 Epic 和工单
5. 首先创建 Epic → 建立父级 Epic 并记录其键
6. 创建子工单 → 创建关联到 Epic 的工单
7. 提供摘要 → 展示所有已创建项目及其链接

为什么必须先创建 Epic： 创建子工单时需要 Epic 键才能正确关联。若先创建工单，它们将成为孤立工单。

---

第 1 步：获取 Confluence 页面

触发后，获取 Confluence 页面内容：

如果用户提供 Confluence URL：

从 URL 格式中提取 cloud ID 和页面 ID：

• 标准格式：https://[site].atlassian.net/wiki/spaces/[SPACE]/pages/[PAGE_ID]/[title]
• 可从 [site].atlassian.net 提取 cloud ID，也可以调用 getAccessibleAtlassianResources 获取
• 页面 ID 是 URL 路径中的数字

如果用户只提供页面标题或描述：

使用 searchConfluence 和 CQL 查询按标题查找页面：

searchConfluence(
  cloudId="...",
  cql="type=page AND title ~ '[search terms]'"
)

不要将 CQL 用于 search。 search 工具是 Rovo 语义搜索，接受自然语言，而非查询语法——向其传入 CQL 会导致找不到页面。仅在使用自然语言进行发现时使用 search（query="one-click checkout spec"）；需要按标题或类型筛选时使用 searchConfluence。

如果匹配到多个页面，请让用户明确要使用哪一个。

获取页面：

调用 getConfluenceContent，并传入 cloudId 和 content ID：

getConfluenceContent(
  cloudId="...",
  content_id="123456",
  content_format="markdown",
  detail="full"
)

此调用会以 Markdown 格式返回页面内容，你将在第 3 步中进行分析。

---

第 2 步：询问项目键

分析规范之前，确定目标 Jira 项目：

询问用户：

“我应该在哪个 Jira 项目中创建这些工单？请提供项目键（例如 PROJ、ENG、PRODUCT）。”

如果用户不确定：

调用 listJiraProjects 查看可用项目。它不是主要工具，因此请通过 execute 运行它（参见调用非主要工具）：

executeRead(   # or execute(...) if your client exposes a single execute tool
  name="listJiraProjects",
  cloudId="...",
  inputs={"action": "create"}
)

展示项目列表：“我找到了以下可用于创建问题的项目：PROJ（Alpha 项目）、ENG（工程）、PRODUCT（产品团队）。”

获取项目密钥后：

调用 listJiraProjectIssueTypesMetadata，了解可用的问题类型。这也不是主要工具：

executeRead(   # or execute(...) if your client exposes a single execute tool
  name="listJiraProjectIssueTypesMetadata",
  cloudId="...",
  inputs={"projectIdOrKey": "PROJ"}
)

确定可用的问题类型：

• 哪种问题类型是“Epic”（或类似的父级类型，例如“Initiative”）
• 有哪些子问题类型可用：“Story”、“Task”、“Bug”、“Sub-task”等

为子任务单选择合适的问题类型：

该技能应根据规范内容智能选择问题类型：

在规范描述以下内容时，使用“Bug”：

• 修复现有问题或缺陷
• 解决错误或不正确的行为
• 处理性能问题
• 更正数据不一致
• 关键词：“fix”、“resolve”、“bug”、“issue”、“problem”、“error”、“broken”

在规范描述以下内容时，使用“Story”：

• 面向用户的新功能或功能特性
• 用户体验改进
• 客户要求的功能
• 产品增强
• 关键词：“feature”、“user can”、“add ability to”、“new”、“enable users”

在规范描述以下内容时，使用“Task”：

• 不直接影响用户的技术工作
• 基础设施或 DevOps 工作
• 重构或优化
• 文档或工具
• 配置或设置
• 关键词：“implement”、“setup”、“configure”、“optimize”、“refactor”、“infrastructure”

回退逻辑：

1. 如果有“Story”且内容表明是新功能 → 使用“Story”
2. 如果有“Bug”且内容表明是修复问题 → 使用“Bug”
3. 如果有“Task” → 技术工作使用“Task”
4. 如果以上类型都不可用 → 使用第一个可用的非 Epic、非 Subtask 问题类型

存储选定的问题类型，供步骤 6 使用：

• Epic 问题类型名称（例如“Epic”）
• 默认子问题类型（例如“Story”或“Task”）
• 如果可用，记录 Bug 问题类型名称（例如“Bug”）

---

步骤 3：分析规范

阅读 Confluence 页面内容，并在内部将其分解为：

Epic 级目标

要实现的总体目标或功能是什么？这将成为你的 Epic。

Epic 摘要示例：

• “用户身份验证系统”
• “支付网关集成”
• “仪表板性能优化”
• “移动应用通知功能”

实施任务

将工作拆分为逻辑清晰、可独立实施的任务。

拆分原则：

• 规模： 每份规范通常包含 3–10 个任务（避免过度细分）
• 清晰： 每个任务都应具体且可执行
• 独立性： 尽可能让任务可以分别处理
• 完整性： 根据需要涵盖后端、前端、测试、文档和基础设施
• 分组： 相关功能放在同一工单中

考虑以下维度：

• 技术层：后端 API、前端 UI、数据库、基础设施
• 工作类型：实施、测试、文档、部署
• 功能：将复杂功能拆分为子功能
• 依赖关系：识别前置工作

常见任务模式：

• “设计[组件]数据库架构”
• “实现[功能] API 端点”
• “构建[组件] UI 组件”
• “将[集成]添加到现有[系统]”
• “为[功能]编写测试”
• “更新[功能]文档”

使用动作动词：

• 实施、创建、构建、添加、设计、集成、更新、修复、优化、配置、部署、测试、编写文档

---

步骤 4：向用户展示任务拆分

创建任何内容之前，向用户展示计划的任务拆分：

格式：

I've analyzed the spec and here's the backlog I'll create:

**Epic:** [Epic Summary]
[Brief description of epic scope]

**Implementation Tickets (7):**
1. [Story] [Task 1 Summary]
2. [Task] [Task 2 Summary]  
3. [Story] [Task 3 Summary]
4. [Bug] [Task 4 Summary]
5. [Task] [Task 5 Summary]
6. [Story] [Task 6 Summary]
7. [Task] [Task 7 Summary]

Shall I create these tickets in [PROJECT KEY]?

问题类型标签会显示每张工单将创建为哪种类型：

• [Story] - 面向用户的新功能
• [Task] - 技术实施工作
• [Bug] - 修复或解决问题

等待用户确认后再继续。这样他们可以：

• 要求修改任务拆分
• 确认范围正确
• 调整工单数量或侧重点

如果用户要求修改，请调整任务拆分并重新展示。

---

步骤 5：先创建 Epic

重要： 必须先创建 Epic，然后才能创建任何子工单。

创建 Epic：

调用 createJiraIssue，并传入：

createJiraIssue(
  cloudId="...",
  projectKey="PROJ",
  issueType="Epic",
  summary="[Epic Summary from Step 3]",
  description="[Epic Description - see below]"
)

Epic 描述结构：

## Overview
[1-2 sentence summary of what this epic delivers]

## Source
Confluence Spec: [Link to Confluence page]

## Objectives
- [Key objective 1]
- [Key objective 2]
- [Key objective 3]

## Scope
[Brief description of what's included and what's not]

## Success Criteria
- [Measurable criterion 1]
- [Measurable criterion 2]
- [Measurable criterion 3]

## Technical Notes
[Any important technical context from the spec]

记录 Epic Key：

响应中会包含 Epic 的 Key（例如，“PROJ-123”）。保存此 Key——创建每个子工单时都需要用到它。

响应示例：

{
  "key": "PROJ-123",
  "id": "10001",
  "self": "https://yoursite.atlassian.net/rest/api/3/issue/10001"
}

向用户确认 Epic 已创建： “✅ 已创建 Epic：PROJ-123 - 用户身份验证系统”

---

第 6 步：创建子工单

现在，为每项实施任务创建一个关联到 Epic 的子工单。

对于每项任务：

确定此任务适用的工单类型：

• 如果任务涉及修复/解决问题 → 使用“Bug”（如果可用）
• 如果任务涉及面向用户的新功能 → 使用“Story”（如果可用）
• 如果任务涉及技术/基础设施工作 → 使用“Task”（如果可用）
• 否则 → 使用第 2 步中的默认子工单类型

调用 createJiraIssue，并传入：

createJiraIssue(
  cloudId="...",
  projectKey="PROJ",
  issueType="[Story/Task/Bug based on task content]",
  summary="[Task Summary]",
  description="[Task Description - see below]",
  parent="PROJ-123"  # The Epic key from Step 5
)

工单类型选择示例：

• “修复身份验证超时 Bug” → 使用“Bug”
• “构建用户仪表板 UI” → 使用“Story”
• “配置 CI/CD 流水线” → 使用“Task”
• “实现密码重置 API” → 使用“Story”（面向用户的新功能）

任务摘要格式：

使用动作动词，并明确具体：

• ✅ “实现用户注册 API 端点”
• ✅ “设计身份验证数据库架构”
• ✅ “构建登录表单 UI 组件”
• ❌ “做后端工作”（太模糊）
• ❌ “前端”（无法执行）

任务描述结构：

## Context
[Brief context for this task from the Confluence spec]

## Requirements
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

## Technical Details
[Specific technical information relevant to this task]
- Technologies: [e.g., Node.js, React, PostgreSQL]
- Components: [e.g., API routes, database tables, UI components]
- Dependencies: [e.g., requires PROJ-124 to be completed first]

## Acceptance Criteria
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]
- [ ] [Testable criterion 3]

## Related
- Confluence Spec: [Link to relevant section if possible]
- Epic: PROJ-123

验收标准最佳实践：

确保标准可测试且具体：

• ✅ “成功创建用户时，API 返回 201 状态码”
• ✅ “密码至少为 8 个字符，并使用 bcrypt 进行哈希处理”
• ✅ “登录表单在提交前验证电子邮件地址格式”
• ❌ “用户可以登录”（太模糊）
• ❌ “运行正常”（无法测试）

依次创建所有工单：

记录每个已创建工单的 Key，以便汇总。

---

第 7 步：提供摘要

创建所有工单后，提供一份完整摘要：

✅ Backlog created successfully!

**Epic:** PROJ-123 - User Authentication System
https://yoursite.atlassian.net/browse/PROJ-123

**Implementation Tickets (7):**

1. PROJ-124 - Design authentication database schema
   https://yoursite.atlassian.net/browse/PROJ-124

2. PROJ-125 - Implement user registration API endpoint
   https://yoursite.atlassian.net/browse/PROJ-125

3. PROJ-126 - Implement user login API endpoint
   https://yoursite.atlassian.net/browse/PROJ-126

4. PROJ-127 - Build login form UI components
   https://yoursite.atlassian.net/browse/PROJ-127

5. PROJ-128 - Build registration form UI components
   https://yoursite.atlassian.net/browse/PROJ-128

6. PROJ-129 - Add authentication integration to existing features
   https://yoursite.atlassian.net/browse/PROJ-129

7. PROJ-130 - Write authentication tests and documentation
   https://yoursite.atlassian.net/browse/PROJ-130

**Source:** https://yoursite.atlassian.net/wiki/spaces/SPECS/pages/123456

**Next Steps:**
- Review tickets in Jira for accuracy and completeness
- Assign tickets to team members
- Estimate story points if your team uses them
- Add any additional labels or custom field values
- Schedule work for the upcoming sprint

---

边缘情况与故障排除

多个规格说明或页面

如果用户引用了多个 Confluence 页面：

• 分别处理每个页面，或询问优先处理哪一个
• 考虑为不同功能创建单独的 Epic
• “我看到你提供了 3 个规格说明页面。要为每个页面分别创建 Epic，还是先处理其中一个？”

已有 Epic

如果用户希望将工单添加到现有 Epic：

• 跳过 Epic 创建（第 5 步）
• 询问现有 Epic Key：“你要将工单添加到哪个 Epic？（例如，PROJ-100）”
• 使用提供的 Epic Key 继续执行第 6 步

自定义必填字段

如果创建工单时因必填字段而失败：

1. 使用 getJiraIssueTypeMetaWithFields 确定必填字段。它不是主要 工具，因此请通过 execute 调用：

   executeRead(   # or execute(...) if your client exposes a single execute tool
     name="getJiraIssueTypeMetaWithFields",
     cloudId="...",
     inputs={"projectIdOrKey": "PROJ", "issueTypeId": "10001"}
   )
   

2. 向用户询问字段值：“此项目要求填写‘Priority’字段。应使用什么优先级？（例如，高、中、低）”

3. 直接传递原生参数——priority 是顶层字符串，而不是 additional_fields 中的条目。additional_fields 仅用于自定义字段：

   priority="High",
   additional_fields={"customfield_10001": {"value": "Production"}}
   

大型规格说明

对于可能生成 15 个以上工单的规格说明：

• 向用户展示完整的任务拆分
• 询问：“此规格说明会创建 18 个工单。要全部创建，还是调整范围？”
• 提供先创建部分工单的选项：“我可以先创建前 10 个工单，等你反馈后再创建其余工单。”

子任务与任务

某些项目使用“Subtask”工单类型：

• 如果元数据显示“Subtask”可用，可以将其用于更细粒度的工作
• 子任务关联到父任务（而不是直接关联到 Epic）
• 层级结构：Epic → Task → Subtask

需求说明不明确

如果 Confluence 页面缺少详细信息：

• 创建更少、更宽泛的工单
• 在工单描述中注明：“详细需求需在细化阶段确定”
• 询问用户：“需求规格说明中缺少实现细节。我是否应创建可在之后细化的高层级工单？”

API 调用失败

如果 createJiraIssue 失败：

1. 检查错误消息，确认具体问题（权限、必填字段、无效值）
2. 使用 executeRead(name="listJiraProjectIssueTypesMetadata", ...) 验证工单类型是否可用
3. 告知用户：“创建工单时遇到错误：[error message]。这可能是由于项目权限或必填字段导致的。”

---

高质量拆解的技巧

明确具体

• ❌ “做前端工作”
• ✅ “创建登录表单 UI，包含电子邮件/密码输入框和验证”

补充技术背景

• 需求说明明确时，注明具体技术
• 引用组件、服务或模块
• 注明集成点

合理分组

• 相关工作应放在同一工单中
• 不要人为拆分：“构建用户个人资料页面”同时包含 UI 和 API 集成
• 不同专业领域的工作应拆分：如果由不同人员负责，则将后端 API 任务与前端 UI 任务分开

避免重复

• 不要为相同功能创建重复工单
• 如果多个功能需要相同的基础设施，创建一个供它们共同依赖的基础设施工单

明确测试

• 将测试纳入功能任务（“实现 X 并编写单元测试”）
• 或为复杂功能创建单独的测试任务（“为身份验证流程编写集成测试”）

文档任务

• 面向用户的功能：包含“更新用户文档”或“创建帮助文章”
• 面向开发者的工具：包含“更新 API 文档”或“编写集成指南”

依赖关系

• 在工单描述中注明前置条件
• 如果 Jira 支持，使用“Depends on”或“Blocks”关系
• 按逻辑顺序安排工单（基础设施 → 实现 → 测试）

---

优秀拆解示例

示例 1：新功能 - 搜索功能

史诗： 产品搜索与筛选

工单：

1. [Task] 设计搜索索引架构和数据结构
2. [Task] 使用 Elasticsearch 实现后端搜索 API
3. [Story] 构建搜索输入框和结果 UI 组件
4. [Story] 添加高级筛选（价格、类别、评分）
5. [Story] 实现搜索建议和自动补全
6. [Task] 优化搜索性能并添加缓存
7. [Task] 编写搜索集成测试和文档

示例 2：错误修复 - 性能问题

史诗： 解决仪表板加载时间问题

工单：

1. [Task] 分析并找出性能瓶颈
2. [Bug] 使用索引和缓存优化数据库查询
3. [Bug] 为仪表板组件实现延迟加载
4. [Bug] 为大型数据表添加分页
5. [Task] 设置性能监控和警报

示例 3：基础设施 - CI/CD 流水线

史诗： 自动化部署流水线

工单：

1. [Task] 设置 GitHub Actions 工作流配置
2. [Task] 在 CI 流水线中实现自动化测试
3. [Task] 配置预发布环境部署
4. [Task] 实现生产环境蓝绿部署
5. [Task] 添加部署回滚机制
6. [Task] 创建部署操作手册和文档

---

调用非主要工具

Atlassian Rovo MCP 服务只会在工具列表中直接公开一小组主要工具。其他工具都位于目录中，需通过元工具调用：

• discover — 如果不知道某项操作的名称，请用自然语言描述目标。它会返回要使用的确切 name 和 inputs。如果某项操作已经作为主要工具提供，请勿调用 discover。
• 执行系列工具 — 按名称运行目录中的操作。请查看工具列表：有些客户端会提供单个 execute，另一些则提供 executeRead / executeWrite / executeDestructive，并要求使用与操作匹配的级别。参数相同：

executeRead(   # or execute(...) if your client exposes a single execute tool
  name="<operationName>",
  cloudId="...",
  inputs={"param": "value"}
)

重要规则：

• cloudId 是顶层参数，与 name 和 inputs 同级——切勿将其放入 inputs。声明了 omitCloudId 的操作（例如 getContentFormatGuide）不需要 cloudId。
• inputs 是扁平对象。 服务会自行将每个参数路由到路径、查询或请求体。
• 使用实时工具架构中的确切参数名称。 无法识别的参数会被丢弃，而不会报错，因此名称错误会静默失败——调用会成功，但你的值会被忽略。如有疑问，请先查看架构或 discover 的结果。
• 如果调用报告操作未知，请使用不同的关键词运行 discover，并使用它返回的名称，不要猜测。