AI Skills
jira-integration

jira-integration

熱門

當需要擷取 Jira 工單、分析需求、更新工單狀態、新增註解或轉換工單狀態時，使用此技能。提供透過 MCP 或直接 REST API 呼叫的 Jira API 模式。

23萬星標
3.5萬分支
更新於 2026/7/17
獲取技能源代碼

相關技能

cloud11萬image-generation7.8萬zustand8.1萬
SKILL.md
readonlyread-only
name
jira-integration
description

當需要擷取 Jira 工單、分析需求、更新工單狀態、新增註解或轉換工單狀態時，使用此技能。提供透過 MCP 或直接 REST API 呼叫的 Jira API 模式。

Jira 整合技能

直接從 AI 編碼工作流程中擷取、分析和更新 Jira 工單。支援基於 MCP（建議）和直接 REST API 兩種方式。

何時啟用

  • 擷取 Jira 工單以了解需求
  • 從工單中提取可測試的驗收條件
  • 在 Jira 議題上新增進度註解
  • 轉換工單狀態（待辦 → 進行中 → 完成）
  • 將合併請求或分支連結到 Jira 議題
  • 透過 JQL 查詢搜尋議題

先決條件

選項 A：MCP 伺服器（建議）

安裝 mcp-atlassian MCP 伺服器。這會將 Jira 工具直接暴露給您的 AI 代理。

需求：

  • Python 3.10+
  • uvx（來自 uv），透過套件管理器或官方 uv 安裝文件安裝

新增至 MCP 設定檔（例如 ~/.claude.json → mcpServers）：

{
  "jira": {
    "command": "uvx",
    "args": ["mcp-atlassian==0.21.0"],
    "env": {
      "JIRA_URL": "https://YOUR_ORG.atlassian.net",
      "JIRA_EMAIL": "your.email@example.com",
      "JIRA_API_TOKEN": "your-api-token"
    },
    "description": "Jira 議題追蹤 — 搜尋、建立、更新、註解、轉換"
  }
}

安全性： 絕不硬編碼機密。建議將 JIRA_URL、JIRA_EMAIL 和 JIRA_API_TOKEN 設定在系統環境（或機密管理工具）中。僅在本地未提交的設定檔中使用 MCP env 區塊。

取得 Jira API Token：

  1. 前往 https://id.atlassian.com/manage-profile/security/api-tokens
  2. 點擊建立 API Token
  3. 複製 Token — 儲存在環境變數中，切勿放在原始碼中

選項 B：直接 REST API

如果無法使用 MCP，可直接透過 curl 或輔助腳本使用 Jira REST API v3。

必要的環境變數：

變數 說明
JIRA_URL 您的 Jira 實例 URL（例如 https://yourorg.atlassian.net）
JIRA_EMAIL 您的 Atlassian 帳戶電子郵件
JIRA_API_TOKEN 來自 id.atlassian.com 的 API Token

將這些儲存在您的 shell 環境、機密管理工具或未追蹤的本地環境變數檔中。請勿提交到儲存庫。

對於直接 curl 範例，透過將 Jira 使用者設定傳遞到標準輸入，避免將憑證放在命令列參數中：

jira_curl() {
  printf 'user = "%s:%s"\n' "$JIRA_EMAIL" "$JIRA_API_TOKEN" |
    curl -s -K - "$@"
}

MCP 工具參考

當設定 mcp-atlassian MCP 伺服器後，可使用以下工具：

工具 用途 範例
jira_search JQL 查詢 project = PROJ AND status = "In Progress"
jira_get_issue 擷取完整議題詳細資訊（依索引鍵） PROJ-1234
jira_create_issue 建立議題（任務、錯誤、故事、史詩） 新錯誤報告
jira_update_issue 更新欄位（摘要、說明、指派對象） 變更指派對象
jira_transition_issue 變更狀態 移至「審查中」
jira_add_comment 新增註解 進度更新
jira_get_sprint_issues 列出衝刺中的議題 進行中的衝刺審查
jira_create_issue_link 連結議題（阻擋、相關） 相依性追蹤
jira_get_issue_development_info 查看連結的 PR、分支、提交 開發上下文

提示： 在轉換前務必呼叫 jira_get_transitions — 轉換 ID 因專案工作流程而異。

直接 REST API 參考

擷取工單

jira_curl \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234" | jq '{
    key: .key,
    summary: .fields.summary,
    status: .fields.status.name,
    priority: .fields.priority.name,
    type: .fields.issuetype.name,
    assignee: .fields.assignee.displayName,
    labels: .fields.labels,
    description: .fields.description
  }'

擷取註解

jira_curl \
  -H "Content-Type: application/json" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234?fields=comment" | jq '.fields.comment.comments[] | {
    author: .author.displayName,
    created: .created[:10],
    body: .body
  }'

新增註解

jira_curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "version": 1,
      "type": "doc",
      "content": [{
        "type": "paragraph",
        "content": [{"type": "text", "text": "您的註解內容"}]
      }]
    }
  }' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/comment"

轉換工單

# 1. 取得可用的轉換
jira_curl \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}'

# 2. 執行轉換（替換 TRANSITION_ID）
jira_curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"transition": {"id": "TRANSITION_ID"}}' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions"

使用 JQL 搜尋

jira_curl -G \
  --data-urlencode "jql=project = PROJ AND status = 'In Progress'" \
  "$JIRA_URL/rest/api/3/search"

分析工單

當為開發或測試自動化擷取工單時，請提取：

1. 可測試的需求

  • 功能需求 — 功能的作用
  • 驗收條件 — 必須滿足的條件
  • 可測試的行為 — 具體動作和預期結果
  • 使用者角色 — 使用此功能的人及其權限
  • 資料需求 — 需要的資料
  • 整合點 — 涉及的 API、服務或系統

2. 需要的測試類型

  • 單元測試 — 個別函式和工具
  • 整合測試 — API 端點和服務互動
  • 端到端測試 — 使用者面對的 UI 流程
  • API 測試 — 端點合約和錯誤處理

3. 邊界案例與錯誤情境

  • 無效輸入（空白、過長、特殊字元）
  • 未經授權的存取
  • 網路失敗或逾時
  • 並發使用者或競爭條件
  • 邊界條件
  • 遺失或空值資料
  • 狀態轉換（返回導航、重新整理等）

4. 結構化分析輸出

工單：PROJ-1234
摘要：[工單標題]
狀態：[目前狀態]
優先級：[高/中/低]
測試類型：單元測試、整合測試、端到端測試

需求：
1. [需求 1]
2. [需求 2]

驗收條件：
- [ ] [條件 1]
- [ ] [條件 2]

測試情境：
- 快樂路徑：[說明]
- 錯誤案例：[說明]
- 邊界案例：[說明]

需要的測試資料：
- [資料項目 1]
- [資料項目 2]

相依性：
- [相依性 1]
- [相依性 2]

更新工單

何時更新

工作流程步驟 Jira 更新
開始工作 轉換為「進行中」
測試撰寫完成 新增含測試覆蓋率摘要的註解
分支建立 新增含分支名稱的註解
PR/MR 建立 新增含連結的註解，連結議題
測試通過 新增含結果摘要的註解
PR/MR 合併 轉換為「完成」或「審查中」

註解範本

開始工作：

開始實作此工單。
分支：feat/PROJ-1234-feature-name

測試實作完成：

自動化測試已實作：

單元測試：
- [測試檔案 1] — [涵蓋內容]
- [測試檔案 2] — [涵蓋內容]

整合測試：
- [測試檔案] — [涵蓋的端點/流程]

所有測試在本機通過。覆蓋率：XX%

PR 建立：

已建立拉取請求：
[PR 標題](https://github.com/org/repo/pull/XXX)

準備好進行審查。

工作完成：

實作完成。

PR 已合併：[連結]
測試結果：全部通過 (X/Y)
覆蓋率：XX%

安全指南

  • 絕不硬編碼 Jira API Token 在原始碼或技能檔案中
  • 始終使用 環境變數或機密管理工具
  • 將 .env 加入每個專案的 .gitignore
  • 立即輪換 Token 如果暴露在 git 歷史中
  • 使用最小權限 API Token，僅限所需專案
  • 驗證 憑證已在 API 呼叫前設定 — 快速失敗並顯示明確訊息

疑難排解

錯誤 原因 修正
401 Unauthorized API Token 無效或過期 在 id.atlassian.com 重新產生
403 Forbidden Token 缺少專案權限 檢查 Token 範圍和專案存取權
404 Not Found 錯誤的工單索引鍵或基礎 URL 驗證 JIRA_URL 和工單索引鍵
spawn uvx ENOENT IDE 在 PATH 中找不到 uvx 使用完整路徑（例如 ~/.local/bin/uvx）或在 ~/.zprofile 中設定 PATH
連線逾時 網路/VPN 問題 檢查 VPN 連線和防火牆規則

最佳實務

  • 邊進行邊更新 Jira，而非最後一次全部更新
  • 保持註解簡潔但資訊豐富
  • 連結而非複製 — 指向 PR、測試報告和儀表板
  • 如果需要他人意見，使用 @提及
  • 開始前檢查連結的議題以了解完整功能範圍
  • 如果驗收條件模糊，在撰寫程式碼前先要求釐清