jira-bug

Jira Bug 代码审查技能

此技能指导 Agent 根据提供的 Jira 工单生成 Bug 代码审查（CR）摘要，并在用户要求时将其作为评论发布。根据当前任务确定仓库和 Jira 站点；此技能可独立安装和使用。

触发方式

由用户调用：/jira-bug — 用户要求为 Jira 工单生成 Bug CR 摘要时，明确使用此技能（例如，“为 PROJ-001 创建 Bug CR”“对 [Ticket ID] 运行 jira-bug”）。

工作流说明

1. 获取 Jira 工单信息：

   • 按功能发现可用的 Jira 工具：站点发现、工单检索、评论列表和评论创建。不同 Agent 的工具名称可能不同；请使用已配置的对应工具，不要假定 MCP 命名空间或 Shell 工具名称固定不变。
   • 根据用户和项目上下文确定目标站点和工单键。如果仍有多个可能的站点，请先询问，不要自行选择。
   • 获取工单和现有评论。继续翻页评论，直到找到相关的先前摘要，或检查完所有可用评论。如果访问不完整，请说明限制，不要声称不存在先前摘要。
   • 从工单中提取 Summary、Description 以及任何 Bug 复现步骤或预期结果。

2. 检测先前的 Bug 摘要：

   • 扫描现有评论，查找先前发布的 Bug CR 摘要——可通过其横幅行（首次摘要为“AI-generated Bug CR summary”，更新摘要为“Updated Bug CR summary”）或任意级别的 Bug 标题识别。评论正文返回时可能采用不同标记格式，因此不要依赖字面上的 # 前缀。仅以“Bug”一词开头的评论不足以作为匹配项。如果有多个匹配项，使用最新的一条。
   • 记录先前摘要的评论 ID、发布日期、语言，以及任何无法从差异中重新生成的内容（例如截图、hotfix Version 列表）。

3. 确定并读取变更范围：

   • 检查仓库说明、Git 状态、分支和远程仓库。优先遵循用户明确指定的暂存、提交、分支、MR 或 PR 范围。
   • 对于已暂存的工作，读取 git diff --cached；对于指定的提交，检查其补丁和父提交；对于提交范围，检查所有指定提交及最终差异；对于分支，验证其基准并比较完整的分支差异；对于 MR/PR，读取已验证的源/目标引用，并在获取相关引用后检查完整差异。
   • 如果未指定范围，则根据当前任务、匹配的工单分支和现有 MR/PR 推断。暂存差异为空，并不能证明实现缺失。如果多个可能的范围会导致摘要不同，请提出一个有针对性的问题。
   • 在适用时记录仓库、范围模式、基准和头部 SHA，以及变更文件数。已暂存的工作没有新的提交 SHA；应标明已暂存快照和当前 HEAD，不要暗示其已提交。
   • 阅读相关上下文代码、调用方和测试，以理解行为。不要仅为生成此摘要而暂存或提交文件。排除无关变更和敏感值。

4. 分析并比较：

   • 将所选代码变更与 Jira 工单中定义的 Bug 详情和预期进行比较。
   • 说明触发条件、预期行为与实际行为、已确认原因或尚待验证的假设，以及变更如何解决问题。将代码检查与复现及回归测试证据分开说明。
   • 指出代码库中受影响的区域（Configurations、Modules、Features / Issues、Components），并像团队模板示例那样用产品术语描述：Modules 是模块名称（例如 Order）；Features / Issues 是屏幕上的功能名称或所见问题；Components 是屏幕或小组件路径（例如 Worklist > Inpatients widget）；Configurations 是配置开关名称及其适用站点。模板中不要写文件名和类名。
   • 报告实际运行的检查及其结果，以及未运行的检查。仅凭代码检查无法证明运行时正确性或完全满足验收要求。
   • 对于 API 工作，在代码支持的范围内描述端点／方法、相关请求字段、授权、处理流程及源数据解析、重复行为、响应状态和适用范围。对于未知的契约，明确标注为未知。

5. 使用模板总结：

   • 保留下方 Bug 模板中的标题和表格，不要添加其他章节。将每行的状态、结果和简要范围写入表格。支撑这些结果的命令和日志应在回复中报告给用户，而不是写在评论中：

   # Bug
   
   **Summary** - [Provide a brief one-line summary of the change or issue fixed.]
   
   **Affected Areas** - [List the specific configurations, modules, features, or components that are impacted by this change or issue.]
   
   | Summary                                                             | Screenshots |
   | :------------------------------------------------------------------ | :---------- |
   | 1. [Provide a brief one-line summary of the change or issue fixed.] | [Image or evidence status] |
   
   | Affected Areas    | Descriptions                                                 |
   | :---------------- | :----------------------------------------------------------- |
   | Configurations    | [Details or N/A]                                             |
   | Modules           | [Details or N/A]                                             |
   | Features / Issues | [Details or N/A]                                             |
   | Components        | [Details or N/A]                                             |
   | Version           | The list of versions must be hotfix after this card is done. |
   

   • 模板中的 Version 行文本是给开发者的指示，不是正文内容。如果工单、用户或先前的摘要提供了需要热修复的版本列表，请将其替换为该列表。如果列表未知，请保留指示文本，在回复中告知用户未提供版本列表，并且不要推断版本。
   • Atlassian 文档格式（ADF）：Markdown 模板定义的是内容和顺序，而非正文的字面语法。当评论工具接受 ADF 时，请发送 JSON 文档，其中包含 version: 1、type: "doc" 和有序的 content 节点。
     • 使用 heading 和 paragraph 节点表示各个部分。两个表格都使用 table、tableRow、tableHeader 和 tableCell 节点。
     • 对一级标题 Bug 同时应用 strong 和 textColor 标记，颜色为 #ff5630。
     • 每个 bug 行的编号都放在其 Summary tableCell 内的一个段落中。随后添加一个 bulletList，其中每条详情对应一个 listItem。请参阅 ADF 文档结构、ADF 表格节点 和 ADF textColor 标记。
   • 评论正文格式：发布前检查实时评论工具的架构。只有当工具接受 ADF 时才发送 ADF 对象。不要假定存在 contentFormat: adf，也不要将 ADF 序列化为字符串。
     • 当前 Atlassian MCP 评论工具接受 Markdown 或 HTML 字符串，不接受原始 ADF 对象。
     • 对于 HTML 表格，请遵循该工具针对 addOrEditJiraIssueComment 提供的 getContentFormatGuide。只有当指南支持所需的表格结构和格式时才使用 HTML。
   • Markdown 备用方案：如果工具不接受 ADF，且其 HTML 指南不支持所需格式，则使用 Markdown。Markdown 表格单元格必须为单行。每个 bug 一行，单元格各部分用 / 连接，不要在单元格内使用嵌套列表或换行。告知用户格式有所损失。如果用户明确要求 ADF，且没有工具接受 ADF，则返回 ADF 草稿，而不是发布 Markdown。
   • Bug 行：每个 Summary 行写成一条带编号的事项，包含四条简短要点：发生了什么、原因、修复了什么 和 修复后的表现。在 ADF 中，单元格内使用嵌套项目符号列表。在 Markdown 备用方案中，将四部分写在同一行，例如 发生了什么：... / 原因：... / 修复了什么：... / 修复后的表现：...。说明已确认的原因。如果原因尚未确认，请标注为 推测，并说明还有哪些内容未检查。除非符合领域约定，否则不要把仅隐藏错误的防护措施说成修复方案。
   • 面向整个团队撰写（开发人员、BA、QA）。读者无需阅读代码，也应能理解每一行：
     • 从用户视角描述每一行：用户执行什么操作、看到什么，并使用屏幕名称。解释无法避免的技术术语。
     • 使用摘要所用语言，以通俗语言描述每种状态。泰语中使用 ทดสอบผ่าน、ทดสอบไม่ผ่าน、ยังไม่ได้ทดสอบ 或 ยังยืนยันไม่ได้。只有实际运行或报告了检查（例如重新运行复现、UAT 结果或测试运行）时，才能使用已测试状态，并且必须说明结果。简要注明测试范围；如果由他人执行，还要注明来源，例如 ทดสอบผ่านบน UAT โดย QA (comment 170406)。绝不要只写 ทดสอบแล้ว。阅读代码不算测试。
     • 如果前后截图都存在，请在 Screenshots 单元格中放入截图对。
     • 在 Features / Issues 单元格中添加一行 应重新测试：，列出通过检查调用方而发现、可能受到修复影响的相邻屏幕或功能。如果未检查调用方，则省略此行。
     • 对 bug 未要求的行为，在 Features / Issues 单元格中标注 (本 bug 之外新增)，以便 BA 和 QA 确认。
     • 发布前重读评论，删去填充内容、重复观点以及听起来像机器生成的措辞。

6. 起草并发布：

   • 工单中的首个 Bug 摘要：在顶部添加一行简短说明，指出这是基于已检查的变更范围生成的 AI Bug CR 摘要。

   • 工单中已有 Bug 摘要：新评论必须引用旧摘要，方便读者追踪更新历史：

     • 以更新横幅开头，而不是使用首次发布时的说明，例如：> 🔄 Updated Bug CR summary — supersedes the previous summary posted on 2026-08-19 (comment 400128). 尽可能链接到之前的评论：https://<site>.atlassian.net/browse/<TICKET>?focusedCommentId=<commentId>#comment-<commentId>。
     • 不要添加变更部分。在原位置更新表格。如果之前的摘要中有内容与当前代码相矛盾，请在表格中更正，并在横幅行中说明更正之处。
     • 保留之前摘要中仍然有效、且无法从 diff 重新生成的信息（例如截图、hotfix Version 列表）——如果仍适用，请明确说明，而不是悄然删去。
     • 除非用户要求使用其他语言，否则保持与之前摘要相同的语言。

   • 语言和截图：首次撰写摘要时，除非用户或仓库说明另有要求，否则使用团队模板示例的语言（泰语，并保留英文产品名和 UI 名称）。如有图片，请添加图片：截图；如果是没有界面的修复，则添加修复前后的测试输出、API 响应或数据库记录。并非每一行都必须有图片，但单元格不能留空。需要图片但尚未附上时，请写 รอแนบภาพ，并注明要附上的内容，例如 รอแนบภาพ: ผลรัน test。不需要图片时，请写 ไม่มีภาพ。沿用图片时，请写 ภาพเดิมใน comment <id>。在 Summary 单元格中保留通过或失败结果，不要给这段文字着色。

   • 先准备完整评论。总结或审查请求应以本地草稿结束，除非用户明确要求发布。如果用户已经要求发布，请直接继续，无需再次询问。若需要发布但尚未获得授权，请仅针对完整且可供审核的草稿请求批准。

   • 发布前，确认工单并重新阅读相关的先前摘要，以避免重复或取代更新的内容。如果所选变更在分析后已发生变化，请先刷新证据并更新草稿。

   • 保留现有评论；此工作流应创建带链接的后续评论，而不是删除或覆盖历史记录。

   • 使用可用的 Jira 评论创建工具及其支持的正文格式，将评论发布到已验证的工单。

7. 验证结果：

   • 发布后，检索创建的评论，并验证其工单、正文和链接。如果写入结果不确定，请先检查现有评论，再重试，以避免重复发布。
   • 返回评论链接和发布状态，或将结果标记为草稿。明确说明检查或测试的限制；没有证据时不得声称发布成功。