researching-jira-issues

调查 Jira 问题

综合信息，不要简单拼接工具输出。以下每个步骤都会收集原始数据——这项技能的价值在于串联不同问题、文档和评论中的信息，形成连贯的理解，让人能够据此采取行动。

工作流

第 1 步：获取主问题

使用 get_issue MCP 工具并提供问题键。该工具默认展开 renderedFields 和 names，以提供 HTML 渲染的字段和易于理解的自定义字段显示名称。

提取并记录：

• 问题类型（Epic、Story、Task、Bug、Sub-task 等）
• 摘要和描述
• 当前状态和优先级
• 经办人和报告人
• 有助于理解工作内容的关键字段（标签、组件、迭代等）
• 能提供重要背景信息的评论（利益相关方的澄清、技术决策、实施指导）
• 自定义字段：从响应的 Additional Fields 部分列出所有非空自定义字段。names 展开会自动将字段 ID 映射为易于理解的显示名称。

第 2 步：识别所有关联问题

检查主问题响应，通过以下方式识别关联问题：

1. 问题链接：在 API 响应中查找 issuelinks 字段（Jira 返回的无类型数组字段），其中包含：

   • 阻塞／被阻塞关系
   • 依赖关系
   • 关联关系
   • 克隆、重复、取代关系
   • 其他任何链接类型

2. 层级链接：查找：

   • 父问题（如果这是子任务）
   • Epic 链接（如果此问题关联了 Epic）
   • 子任务（如果此问题包含子任务）
   • 新一代项目：如果问题类型为 Epic 或 Feature 且 subtasks 为空，请使用 search_issues MCP 工具和 JQL parent = <ISSUE-KEY> 查找子问题。新一代 Jira 项目使用 parent 关系，而不是 subtasks 字段。

3. 远程链接：使用 get_issue_remote_links MCP 工具并提供问题键，以查找：

   • 已链接的 Confluence 页面（输出中归在“Confluence Pages”下）
   • 拉取请求和提交（归在“GitHub”下）
   • 外部文档和其他资源

第 3 步：按深度控制获取关联的问题

获取相关问题以构建上下文，但要在收益递减前停止。每增加一跳都会增加 API 调用次数和上下文窗口占用，同时提供的直接相关信息却越来越少。

1. 优先级顺序：

   • 高优先级：Blocks、Depends on、Parent、Epic Link — 这些关系决定工作能否开始，以及问题在层级结构中的位置
   • 中优先级：子任务、相关问题 — 这些关系界定范围并提供背景信息
   • 低优先级：克隆、重复问题 — 仅当它们提供其他地方没有的独特上下文时才获取

2. 深度控制：

   • 最多遍历主问题之外的 2 个层级（主问题 -> 关联问题 -> 仅对高优先级关联再深入一跳）。超过 2 个层级后，上下文相关性会急剧下降，响应内容也更容易膨胀。
   • 对于通过描述中的内联 URL 引用其他 Jira 项目的问题（例如 VULN-、SEC-），应在上下文中提及该引用，但除非它是正式的问题链接（blocks/depends-on/relates-to），否则不要继续遍历。跨项目的内联引用仅供参考，不代表依赖关系。
   • 跟踪已获取的问题键，以避免循环引用（A 链接到 B，B 链接到 A）
   • 对每个关联问题，使用 get_issue MCP 工具并提取关键信息

3. 选择性获取：

   • 对于子任务：获取所有子任务以了解完整工作范围。如果子任务超过 10 个，则获取前 10 个，并根据搜索结果将其余子任务概括为简明列表（键、状态、摘要）。
   • 对于阻塞问题：获取以了解依赖关系
   • 对于相关问题：如果它们对理解问题至关重要，则获取
   • 跳过重复或克隆的问题，除非它们包含独特信息

4. 速率限制：大量调用 API 时，应适当间隔请求。每连续调用 5 次后，短暂暂停（1 秒），以避免触发 Atlassian 速率限制。如果遇到 429 响应，请等待 10 秒后重试。

第 4 步：获取关联的 Confluence 文档

Confluence 页面通常包含需求、设计文档或规格说明：

1. 从以下位置提取 Confluence 页面链接：

   • 远程链接输出（第 2 步 — 按“Confluence 页面”分组的链接）
   • 符合 */wiki/spaces/*/pages/*/ 格式的问题描述 URL
   • 指向 Confluence 的评论 URL

2. 对于每个 Confluence 链接：

   • 从 URL 中提取 pageId（例如，https://domain.atlassian.net/wiki/spaces/SPACE/pages/123456789/Title -> 123456789）
   • 使用页面 ID 调用 get_confluence_page MCP 工具
   • 记录页面标题和内容中的关键信息

3. 页面的上下文预算：对于超过 2000 个词的 Confluence 页面，应概括与问题相关的部分，而不是复述整页内容。重点关注需求、验收标准、技术约束和设计决策。

第 5 步：妥善处理失败

如果任何获取操作失败，请记录失败情况，并继续使用可用数据。具体失败情况如下：

• 关联问题返回 404：该问题已删除或移走。记录问题键并跳过。
• Confluence 页面返回 403：无权访问。记录远程链接中的页面标题并跳过。
• 远程链接返回 404：该端点可能不可用。跳过，并依赖主响应中的问题链接。

在综合结果末尾，始终报告哪些内容未能获取。

第 6 步：综合并呈现

将收集到的信息整理为全面的理解：

问题概览

• 该问题的核心目的是什么？
• 这是什么类型的工作（新功能、错误修复、技术债务等）？
• 当前状态如何，由谁负责

需求和上下文

• 关键需求或验收标准是什么？
• 要解决什么问题？
• 有哪些文档支持这项工作？
• 将所有非空自定义字段以其显示名称作为标题展示，并以 Markdown 格式呈现其内容

依赖关系

• 哪些问题必须先完成（阻塞依赖）？
• 这会阻塞哪些问题（下游影响）？
• 这与更大的 Epic 或项目有何关联？

工作范围

• 有哪些子任务？
• 工作如何拆分？
• 是否有提供更多背景信息的相关问题？

关键洞察

• 评论或文档中的技术决策或限制
• 提及的风险或顾虑
• 重要的历史背景（为何克隆此问题、它取代了什么，等等）

上下文预算

当完整综合内容超过约 4000 个单词（大致达到读者开始略读而非充分吸收内容的程度）时，将优先级较低的关联问题（相关、克隆、重复）压缩为单行摘要，仅包含关键标识、状态和摘要。除非用户要求查看更多评论，否则最多展示最近的 3 条评论。

示例

examples/deep_read_workflow.md

端到端演示如何深入阅读一个包含子任务、阻塞问题和关联 Confluence 文档的 Story。