jira

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Jira

Natural language interaction with Jira. Supports multiple backends.

与Jira的自然语言交互。支持多种后端。

Backend Detection

后端检测

Run this check first to determine which backend to use:

1. Check if jira CLI is available:
   → Run: which jira
   → If found: USE CLI BACKEND

2. If no CLI, check for Atlassian MCP:
   → Look for mcp__atlassian__* tools
   → If available: USE MCP BACKEND

3. If neither available:
   → GUIDE USER TO SETUP

Backend	When to Use	Reference
CLI	`jira` command available	`references/commands.md`
MCP	Atlassian MCP tools available	`references/mcp.md`
None	Neither available	Guide to install CLI

请先运行此检查以确定要使用的后端：

1. 检查是否有jira CLI可用：
   → 运行：which jira
   → 如果找到：使用CLI后端

2. 如果没有CLI，检查是否有Atlassian MCP：
   → 查找mcp__atlassian__*工具
   → 如果可用：使用MCP后端

3. 如果两者都不可用：
   → 引导用户进行设置

后端	使用场景	参考文档
CLI	存在 `jira` 命令	`references/commands.md`
MCP	有Atlassian MCP工具可用	`references/mcp.md`
无	两者都不可用	引导安装CLI

Quick Reference (CLI)

快速参考（CLI）

Skip this section if using MCP backend.

Intent	Command
View issue	`jira issue view ISSUE-KEY`
List my issues	`jira issue list -a$(jira me)`
My in-progress	`jira issue list -a$(jira me) -s"In Progress"`
Create issue	`jira issue create -tType -s"Summary" -b"Description"`
Move/transition	`jira issue move ISSUE-KEY "State"`
Assign to me	`jira issue assign ISSUE-KEY $(jira me)`
Unassign	`jira issue assign ISSUE-KEY x`
Add comment	`jira issue comment add ISSUE-KEY -b"Comment text"`
Open in browser	`jira open ISSUE-KEY`
Current sprint	`jira sprint list --state active`
Who am I	`jira me`

如果使用MCP后端，请跳过此部分。

意图	命令
查看问题	`jira issue view ISSUE-KEY`
列出我的问题	`jira issue list -a$(jira me)`
我的进行中问题	`jira issue list -a$(jira me) -s"In Progress"`
创建问题	`jira issue create -tType -s"Summary" -b"Description"`
移动/流转	`jira issue move ISSUE-KEY "State"`
分配给我	`jira issue assign ISSUE-KEY $(jira me)`
取消分配	`jira issue assign ISSUE-KEY x`
添加评论	`jira issue comment add ISSUE-KEY -b"Comment text"`
在浏览器中打开	`jira open ISSUE-KEY`
当前sprint	`jira sprint list --state active`
查看当前用户	`jira me`

Quick Reference (MCP)

快速参考（MCP）

Skip this section if using CLI backend.

Intent	MCP Tool
Search issues	`mcp__atlassian__searchJiraIssuesUsingJql`
View issue	`mcp__atlassian__getJiraIssue`
Create issue	`mcp__atlassian__createJiraIssue`
Update issue	`mcp__atlassian__editJiraIssue`
Get transitions	`mcp__atlassian__getTransitionsForJiraIssue`
Transition	`mcp__atlassian__transitionJiraIssue`
Add comment	`mcp__atlassian__addCommentToJiraIssue`
User lookup	`mcp__atlassian__lookupJiraAccountId`
List projects	`mcp__atlassian__getVisibleJiraProjects`

See

references/mcp.md

for full MCP patterns.

如果使用CLI后端，请跳过此部分。

意图	MCP工具
搜索问题	`mcp__atlassian__searchJiraIssuesUsingJql`
查看问题	`mcp__atlassian__getJiraIssue`
创建问题	`mcp__atlassian__createJiraIssue`
更新问题	`mcp__atlassian__editJiraIssue`
获取流转选项	`mcp__atlassian__getTransitionsForJiraIssue`
流转问题	`mcp__atlassian__transitionJiraIssue`
添加评论	`mcp__atlassian__addCommentToJiraIssue`
用户查找	`mcp__atlassian__lookupJiraAccountId`
列出项目	`mcp__atlassian__getVisibleJiraProjects`

有关完整的MCP模式，请参阅

references/mcp.md

。

Triggers

触发场景

"create a jira ticket"
"show me PROJ-123"
"list my tickets"
"move ticket to done"
"what's in the current sprint"

"创建一个Jira工单"
"给我看PROJ-123"
"列出我的工单"
"将工单移至已完成"
"当前sprint中有什么内容"

Issue Key Detection

问题键检测

Issue keys follow the pattern:

[A-Z]+-[0-9]+

(e.g., PROJ-123, ABC-1).

When a user mentions an issue key in conversation:

CLI:
```
jira issue view KEY
```
or
```
jira open KEY
```
MCP:
```
mcp__atlassian__jira_get_issue
```
with the key

问题键遵循以下格式：

[A-Z]+-[0-9]+

（例如PROJ-123、ABC-1）。

当用户在对话中提及问题键时：

CLI：使用
```
jira issue view KEY
```
或
```
jira open KEY
```
MCP：使用带键的
```
mcp__atlassian__jira_get_issue
```

Workflow

工作流

Creating tickets:

Research context if user references code/tickets/PRs
Draft ticket content
Review with user
Create using appropriate backend

Updating tickets:

Fetch issue details first
Check status (careful with in-progress tickets)
Show current vs proposed changes
Get approval before updating
Add comment explaining changes

创建工单：

如果用户提及代码/工单/PR，先研究上下文
草拟工单内容
与用户审核
使用合适的后端创建

更新工单：

先获取问题详情
检查状态（注意进行中的工单）
展示当前状态与拟修改内容
更新前获得用户批准
添加评论说明修改内容

Before Any Operation

操作前检查

Ask yourself:

What's the current state? — Always fetch the issue first. Don't assume status, assignee, or fields are what user thinks they are.
Who else is affected? — Check watchers, linked issues, parent epics. A "simple edit" might notify 10 people.
Is this reversible? — Transitions may have one-way gates. Some workflows require intermediate states. Description edits have no undo.
Do I have the right identifiers? — Issue keys, transition IDs, account IDs. Display names don't work for assignment (MCP).

请自问：

当前状态是什么？ — 始终先获取问题信息。不要假设状态、经办人或字段与用户认为的一致。
还有谁会受影响？ — 查看关注者、关联问题、父级史诗。一个“简单编辑”可能会通知10个人。
操作可逆吗？ — 流转可能有单向限制。某些工作流需要中间状态。描述编辑无法撤销。
我有正确的标识符吗？ — 问题键、流转ID、账户ID。显示名称在分配时无效（MCP）。

NEVER

绝对禁止

NEVER transition without fetching current status — Workflows may require intermediate states. "To Do" → "Done" might fail silently if "In Progress" is required first.
NEVER assign using display name (MCP) — Only account IDs work. Always call
```
lookupJiraAccountId
```
first, or assignment silently fails.
NEVER edit description without showing original — Jira has no undo. User must see what they're replacing.
NEVER use
--no-input
without all required fields (CLI) — Fails silently with cryptic errors. Check project's required fields first.
NEVER assume transition names are universal — "Done", "Closed", "Complete" vary by project. Always get available transitions first.
NEVER bulk-modify without explicit approval — Each ticket change notifies watchers. 10 edits = 10 notification storms.

绝对禁止不获取当前状态就进行流转 — 工作流可能需要中间状态。“待办”→“已完成”如果需要先经过“进行中”可能会静默失败。
绝对禁止使用显示名称分配（MCP） — 只有账户ID有效。必须先调用
```
lookupJiraAccountId
```
，否则分配会静默失败。
绝对禁止不展示原文就编辑描述 — Jira没有撤销功能。用户必须看到他们要替换的内容。
绝对禁止在缺少必填字段时使用
--no-input
（CLI） — 会静默失败并给出模糊错误。请先检查项目的必填字段。
绝对禁止假设流转名称是通用的 — “已完成”、“已关闭”、“完成”因项目而异。必须先获取可用的流转选项。
绝对禁止未获得明确批准就批量修改 — 每个工单修改都会通知关注者。10次编辑会导致10次通知风暴。

Safety

安全规范

Always show the command/tool call before running it
Always get approval before modifying tickets
Preserve original information when editing
Verify updates after applying
Always surface authentication issues clearly so the user can resolve them

运行命令/工具调用前始终展示给用户
修改工单前始终获得用户批准
编辑时保留原始信息
应用修改后验证更新结果
始终清晰地显示认证问题，以便用户解决

No Backend Available

无可用后端

If neither CLI nor MCP is available, guide the user:

To use Jira, you need one of:

1. **jira CLI** (recommended):
   https://github.com/ankitpokhrel/jira-cli

   Install: brew install ankitpokhrel/jira-cli/jira-cli
   Setup:   jira init

2. **Atlassian MCP**:
   Configure in your MCP settings with Atlassian credentials.

如果CLI和MCP都不可用，请引导用户：

要使用Jira，您需要以下其中一项：

1. **jira CLI**（推荐）：
   https://github.com/ankitpokhrel/jira-cli

   安装：brew install ankitpokhrel/jira-cli/jira-cli
   设置：   jira init

2. **Atlassian MCP**：
   在MCP设置中配置Atlassian凭据。

Deep Dive

深入指南

LOAD reference when:

Creating issues with complex fields or multi-line content
Building JQL queries beyond simple filters
Troubleshooting errors or authentication issues
Working with transitions, linking, or sprints

Do NOT load reference for:

Simple view/list operations (Quick Reference above is sufficient)
Basic status checks (
```
jira issue view KEY
```
)
Opening issues in browser

Task	Load Reference?
View single issue	No
List my tickets	No
Create with description	Yes — CLI needs `/tmp` pattern
Transition issue	Yes — need transition ID workflow
JQL search	Yes — for complex queries
Link issues	Yes — MCP limitation, need script

References:

CLI patterns:
```
references/commands.md
```
MCP patterns:
```
references/mcp.md
```

加载参考文档的场景：

创建包含复杂字段或多行内容的问题
构建超出简单筛选的JQL查询
排查错误或认证问题
处理流转、关联或sprint相关操作

无需加载参考文档的场景：

简单的查看/列出操作（上述快速参考已足够）
基本状态检查（
```
jira issue view KEY
```
）
在浏览器中打开问题

任务	是否需要加载参考文档？
查看单个问题	否
列出我的工单	否
创建带描述的问题	是 — CLI需要 `/tmp` 格式
流转问题	是 — 需要流转ID工作流
JQL搜索	是 — 用于复杂查询
关联问题	是 — MCP限制，需要脚本

参考文档：

CLI模式：
```
references/commands.md
```
MCP模式：
```
references/mcp.md
```