Jira 集成技能¶

直接从 AI 编码工作流中获取、分析和更新 Jira 工单。支持 基于 MCP（推荐）和 直接 REST API 两种方法。

激活时机¶

获取 Jira 工单以理解需求
从工单中提取可测试的验收标准
向 Jira 问题添加进度评论
转换工单状态（To Do → In Progress → Done）
将合并请求或分支链接到 Jira 问题
使用 JQL 查询搜索问题

前提条件¶

选项 A：MCP 服务器（推荐）¶

安装 mcp-atlassian MCP 服务器。这将直接向 AI 代理公开 Jira 工具。

要求： - 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 issue tracking — search, create, update, comment, transition"
  }
}

安全： 不要硬编码密钥。建议将 JIRA_URL、JIRA_EMAIL、JIRA_API_TOKEN 设置为系统环境变量或密钥管理器。MCP 的 env 块仅用于本地未提交的配置文件。

获取 Jira API 令牌的方法： 1. 访问 https://id.atlassian.com/manage-profile/security/api-tokens 2. 点击 创建 API 令牌 3. 复制令牌并保存到环境变量（绝对不要保存到源代码中）

选项 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 令牌

请将其保存在 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`	更改状态	移动到 "In Review"
`jira_add_comment`	添加评论	进度更新
`jira_get_sprint_issues`	列出冲刺中的问题	活动冲刺评审
`jira_create_issue_link`	链接问题（Blocks、Relates to）	跟踪依赖关系
`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": "Your comment here"}]
      }]
    }
  }' \
  "$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 端点和服务交互
E2E 测试 — 面向用户的 UI 流程
API 测试 — 端点契约和错误处理

3. 边界情况和错误场景¶

无效输入（空值、过长、特殊字符）
未授权访问
网络故障或超时
并发用户或竞态条件
边界条件
数据缺失或 null 值
状态转换（返回导航、刷新等）

4. 结构化分析输出¶

Ticket: PROJ-1234
Summary: [チケットタイトル]
Status: [現在のステータス]
Priority: [High/Medium/Low]
Test Types: Unit, Integration, E2E

Requirements:
1. [要件 1]
2. [要件 2]

Acceptance Criteria:
- [ ] [基準 1]
- [ ] [基準 2]

Test Scenarios:
- Happy Path: [説明]
- Error Case: [説明]
- Edge Case: [説明]

Test Data Needed:
- [データ項目 1]
- [データ項目 2]

Dependencies:
- [依存関係 1]
- [依存関係 2]

更新工单¶

更新时机¶

工作流步骤	Jira 更新
开始工作	转换到 "In Progress"
完成测试编写	评论测试覆盖率摘要
创建分支	评论分支名称
创建 PR/MR	带链接的评论，链接问题
测试通过	评论结果摘要
合并 PR/MR	转换到 "Done" 或 "In Review"

评论模板¶

开始工作：

Starting implementation for this ticket.
Branch: feat/PROJ-1234-feature-name

完成测试实现：

Automated tests implemented:

Unit Tests:
- [テストファイル 1] — [カバー内容]
- [テストファイル 2] — [カバー内容]

Integration Tests:
- [テストファイル] — [カバーするエンドポイント/フロー]

All tests passing locally. Coverage: XX%

创建 PR：

Pull request created:
[PR Title](https://github.com/org/repo/pull/XXX)

Ready for review.

完成工作：

Implementation complete.

PR merged: [link]
Test results: All passing (X/Y)
Coverage: XX%

安全指南¶

绝对不要将 Jira API 令牌硬编码到源代码或技能文件中
务必使用环境变量或密钥管理器
在所有项目中将 .env 添加到 .gitignore
如果令牌暴露在 git 历史中，立即轮换令牌
使用仅限所需项目的最小权限 API 令牌
在 API 调用前验证凭据是否已设置 — 伴随明确消息尽早失败

故障排除¶

错误	原因	处理方法
`401 Unauthorized`	API 令牌无效或已过期	在 id.atlassian.com 重新生成
`403 Forbidden`	令牌缺少项目权限	检查令牌的作用域和项目访问权限
`404 Not Found`	工单键或基础 URL 错误	检查 `JIRA_URL` 和工单键
`spawn uvx ENOENT`	IDE 无法在 PATH 中找到 `uvx`	使用完整路径（例如：`~/.local/bin/uvx`），或在 `~/.zprofile` 中设置 PATH
连接超时	网络/VPN 问题	检查 VPN 连接和防火墙规则

最佳实践¶

边工作边更新 Jira，而不是最后统一更新
保持评论简洁且信息充分
使用链接而非复制 — 粘贴 PR、测试报告和仪表板的链接
需要他人意见时使用 @提及
开始工作前，查看关联的 Issue，以理解功能的整体范围
如果验收标准不明确，在编写代码前先请求澄清

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC