update-jira-ticket

Name: update-jira-ticket
Author: morphet81

github.com/morphet81开发098 次安装24 周前更新

代码仓库

关于 update-jira-ticket

此技能对照当前分支与关联的 JIRA 工单，并提出描述或评论更新建议。它引导开发者审阅并确认变更，再通过 Atlassian CLI 应用更新。

主要功能

01从分支名提取 JIRA ID
02对照工单与分支变更
03建议修改描述或添加评论
04通过 Atlassian CLI 应用已确认的更新

适用场景

01补充工单中缺少的实现需求
02以评论记录范围外变更
03在实现决策后更新工单

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/morphet81/cheat-sheets --skill update-jira-ticket

安装后在 Claude Code 中输入/update-jira-ticket确认已加载。

详细介绍

比较当前分支关联的 JIRA 工单与实际所做的更改，并提出更新建议，确保工单内容准确。对于缺少的信息，编辑工单描述；对于无关更改或实现决策，添加评论；也可以两者兼做。

用法：

/update-jira-ticket - 分析分支更改并提出 JIRA 工单更新建议

说明：

检查前置条件：

Atlassian CLI（acli）： 运行 acli auth status，检查 CLI 是否已安装并完成身份验证。

如果找不到该命令，显示以下消息并停止：

## 缺少前置条件：Atlassian CLI

尚未安装 `acli` 命令。此技能需要 Atlassian CLI 来获取和更新 JIRA 工单详情。

使用以下命令安装：brew tap atlassian/acli && brew install acli

如果命令因身份验证错误而失败，显示以下消息并停止：

## 缺少前置条件：Atlassian CLI 身份验证

Atlassian CLI 尚未完成身份验证。使用此技能前，请运行 `acli auth login` 完成身份验证。

从当前分支名称中提取 JIRA ID：
- 运行 git branch --show-current 获取当前分支名称
- 通过匹配 [A-Z][A-Z0-9]+-[0-9]+ 模式提取 JIRA ID（例如 PROJ-123、AB-1、MYAPP-4567）
- JIRA ID 可出现在分支名称的任意位置（例如 fix/PROJ-123、feat/PROJ-123、PROJ-123-some-description）
- 匹配时不区分大小写——将提取的 ID 规范化为大写，以便通过 JIRA API 查询
- 如果未找到 JIRA ID，显示以下消息并停止：
```
分支名称中未找到 JIRA ID："<current-branch>"
分支名称应包含 JIRA ID（例如 fix/proj-123、feat/MYAPP-456）。
```
获取 JIRA 工单：
- 使用 Atlassian CLI，根据 JIRA ID 获取工单：
```
acli jira workitem view <JIRA-ID> --fields '*all' --json
```
- 解析所有可用字段：摘要、描述、问题类型、优先级、评论、验收标准、自定义字段等
- 保存原始描述以供比较——这是基准
- 如果获取失败，显示错误并停止
确定基准分支：
- 检查当前目录中是否存在 .agent 文件
- 如果存在，读取该文件并查找 baseBranch=<value> 行，以提取基准分支
- 如果不存在 .agent 文件或没有 baseBranch 键，则默认使用 main
分析分支更改：
- 运行 git log <base-branch>..HEAD --oneline，获取此分支上的提交历史
- 运行 git diff <base-branch>...HEAD --stat，获取更改文件摘要
- 运行 git diff <base-branch>...HEAD，获取完整差异
- 阅读关键的已修改文件，了解更改性质
- 全面了解以下内容：
  - 实现了什么——新功能、错误修复、重构等
  - 如何实现——技术方案、使用的模式、关键决策
  - 超出原始范围的更改——对工单描述的任何新增、调整或偏离
将更改与工单描述进行比较：

对于每项重要更改或实现内容，将其归入以下三种类型之一：

a) 描述中缺失——编辑描述：
- 工单中本应包含但未写明的信息（例如，已实现但缺失的验收标准、实施过程中发现但未记录的要求、隐含但应明确说明的范围）
- 应编辑描述以加入这些信息，便于文档记录和跟踪 b) 与工单无关 — 添加评论：
- 与工单工作同时进行，但不属于工单范围的更改（例如，顺手进行的重构、相邻代码中的小修复、依赖项更新）
- 应将这些内容记录为评论，以便工单历史记录能反映实际发生的情况，同时避免污染描述
c) 实施决策 — 编辑描述并添加评论：
- 对工单有影响的、有意作出的技术或产品决策所涉及的更改（例如，选择方案 A 而非方案 B、根据技术限制调整验收标准、实施期间商定的范围调整）
- 应更新描述以反映最终状态，并添加评论说明作出该决策的原因
静默跳过以下更改：
- 当前描述已准确反映的更改
- 不影响工单文档价值的琐碎实现细节（例如，变量名、轻微格式调整）

准备拟议编辑列表：

按操作类型分组，以编号列表的形式列出所有拟议更改：

## Proposed JIRA Ticket Updates for <JIRA-ID>

### Description Edits
These changes update the ticket description to reflect the actual implementation.

**#1** — <Brief title of the edit>
- **Reason:** <Why this edit is needed>
- **Change:** <What will be added/modified in the description>

**#2** — <Brief title>
- **Reason:** <Why>
- **Change:** <What>

### Comments to Add
These document changes that don't belong in the description.

**#3** — <Brief title of the comment>
- **Reason:** <Why a comment is appropriate here>
- **Content:** <The comment text to be added>

### Description Edits + Comments
These require both a description update and a comment explaining the decision.

**#4** — <Brief title>
- **Reason:** <Why both are needed>
- **Description change:** <What will be updated>
- **Comment:** <The comment explaining the reasoning>

### Summary
- **Description edits:** <N>
- **Comments:** <N>
- **Description edits + comments:** <N>
- **Total updates:** <N>

如果没有拟议更改（工单内容已准确），请显示：

✅ The JIRA ticket description for <JIRA-ID> is already in sync with the branch changes. No updates needed.

然后停止。

获取开发者确认：

使用 AskUserQuestion 询问开发者是否审核并批准拟议更新：
- “全部应用” — 应用所有拟议编辑和评论
- “让我选择” — 开发者指定要应用的项目（按编号）
- “跳过” — 取消，不更新工单
如果选择“让我选择”：
- 使用 AskUserQuestion 询问要应用哪些项目编号（例如，“1, 3, 4”）
- 仅应用选中的项目
应用已批准的更新：

a) 描述编辑：
- 读取当前工单描述
- 将所有已批准的描述编辑自然地整合到现有描述结构中
- 保留原描述的语气、格式和结构——不要改写未更新的部分
- 将描述编写为 ADF（Atlassian Document Format）JSON 负载，并使用 --from-json 进行更新：
```
acli jira workitem edit --from-json <temp-file.json> --yes
```
  JSON 文件必须包含完整的编辑负载，并将描述作为 ADF 对象（请参见下方的 ADF 格式参考）。
- 如果更新失败，显示错误，并提供可复制的拟议描述文本
b) 评论：
- 对于每条已批准的评论，使用 Atlassian CLI：
```
acli jira workitem comment create --key <JIRA-ID> --body "<comment text>"
```
- 每条评论都应自成一体，并清楚说明背景
- 为便于识别，在实施决策评论前加上 “Implementation note:”
- 如果评论发布失败，显示错误，并提供可复制的评论文本

显示结果：

显示已应用内容的摘要：

## JIRA 工单已更新：<JIRA-ID>

### ✅ 描述已更新
- #1 — <标题>
- #4 — <标题>

### ✅ 已添加评论
- #2 — <标题>
- #3 — <标题>
- #4 — <标题>（实施说明）

### ❌ 已跳过
- #5 — <标题>（开发者选择跳过）

工单：https://<site>.atlassian.net/browse/<JIRA-ID>

处理边缘情况：
- 如果工单描述为空，则所有实现细节都视为“描述中缺失”——根据更改提出完整的描述
- 如果分支上还没有提交，则显示“No changes found on this branch compared to .”并停止
- 如果差异过大，无法完整分析，则重点关注最重要的更改（新文件、大幅修改），并说明未审查部分次要更改
- 如果 JIRA 更新部分失败（例如，描述已更新，但评论失败），则报告成功和失败的部分
- 如果分支包含多个工单的更改（例如，cherry-pick），则仅为与分支名称匹配的工单提出更新

ADF 格式参考

JIRA 不会渲染 Markdown。描述必须使用 Atlassian Document Format（ADF）——一种基于 JSON 的文档格式。--description-file 标志会将文件内容视为纯文本字符串，因此不能用于富文本描述。请改用 --from-json。

重要：--from-json 需要包含完整编辑载荷的结构化 JSON 文件。description 字段必须是 ADF 对象，而不是字符串。你可以运行 acli jira workitem edit --generate-json 查看预期的架构。

编辑载荷格式（--from-json）：

{
  "issues": ["<JIRA-ID>"],
  "description": {
    "version": 1,
    "type": "doc",
    "content": [
      {
        "type": "heading",
        "attrs": { "level": 2 },
        "content": [{ "type": "text", "text": "Description" }]
      },
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Regular text. " },
          { "type": "text", "text": "Bold text", "marks": [{ "type": "strong" }] }
        ]
      },
      {
        "type": "bulletList",
        "content": [
          {
            "type": "listItem",
            "content": [
              { "type": "paragraph", "content": [{ "type": "text", "text": "List item" }] }
            ]
          }
        ]
      },
      {
        "type": "orderedList",
        "content": [
          {
            "type": "listItem",
            "content": [
              { "type": "paragraph", "content": [{ "type": "text", "text": "Numbered item" }] }
            ]
          }
        ]
      },
      {
        "type": "taskList",
        "attrs": { "localId": "unique-id" },
        "content": [
          {
            "type": "taskItem",
            "attrs": { "localId": "task-1", "state": "TODO" },
            "content": [{ "type": "text", "text": "Acceptance criterion" }]
          }
        ]
      },
      {
        "type": "codeBlock",
        "attrs": { "language": "typescript" },
        "content": [{ "type": "text", "text": "const x = 1;" }]
      }
    ]
  }
}

常见 ADF 节点类型：

Markdown	ADF `type`	说明
`## Heading`	`heading`，带有 `attrs.level`	级别 1–6
纯文本	`paragraph`，带有 `text` 子节点
`bold`	`text`，带有 `marks: [{"type": "strong"}]`
`italic`	`text`，带有 `marks: [{"type": "em"}]`
`- item`	`bulletList` > `listItem` > `paragraph`
`1. item`	`orderedList` > `listItem` > `paragraph`
`- [ ] task`	`taskList` > `taskItem`（状态：`TODO`/`DONE`）
`code`	`text`，带有 `marks: [{"type": "code"}]`	行内代码
代码块	`codeBlock`，带有 `attrs.language`
`---`	`rule`	水平分隔线
`[link](url)`	`text`，带有 `marks: [{"type": "link", "attrs": {"href": "url"}}]`

支持 Markdown

登录后评论

基本信息

作者: morphet81
仓库: morphet81/cheat-sheets
分类: 开发
安装次数: 98
GitHub Stars: 0

报告问题