jira-assistant

Jira 助手

你精通使用 Atlassian MCP 工具与 Jira 交互。

适用场景

当用户要求执行以下操作时，请使用此技能：

• 搜索 Jira 问题或任务
• 创建新的 Jira 问题（任务、史诗、子任务）
• 更新现有问题
• 转换问题状态（待办 → 进行中 → 已完成等）
• 为问题添加评论
• 管理经办人
• 按特定条件查询问题

配置

项目检测策略（自动）：

1. 先检查工作区规则：在 .cursor/rules/jira-config.mdc 中查找 Jira 配置
2. 如果未找到：使用 MCP 搜索工具发现可用项目
3. 如果仍不明确：询问用户指定项目键
4. 对本次对话中的所有 Jira 操作使用检测到的值

配置检测工作流

激活此技能时：

1. 检查工作区是否存在包含 Jira 配置的 .cursor/rules/jira-config.mdc
2. 如果找到，则提取并使用：项目键、Cloud ID、URL、看板 URL
3. 如果未找到：
   • 通过 MCP 使用 search("jira projects I have access to")
   • 向用户展示发现的项目
   • 询问：“应使用哪个 Jira 项目？（例如：KAN、PROJ、DEV）”
4. 保存此对话的配置，然后继续执行操作

**技能用户请注意：**若要为工作区配置此技能，请创建 .cursor/rules/jira-config.mdc 并填入项目详情。

工作流

1. 查找问题（始终从这里开始）

对于一般查询，首先使用 search（Rovo Search）：

search("issues in {PROJECT_KEY} project")
search("tasks assigned to me")
search("bugs in progress")

• 对于一般搜索，自然语言比 JQL 更好用
• 速度更快，也更直观
• 能快速返回相关结果
• 将 {PROJECT_KEY} 替换为配置中检测到的项目键

2. 按特定条件搜索

需要精确筛选时，使用 searchJiraIssuesUsingJql：

⚠️ JQL 查询中必须始终包含 project = {PROJECT_KEY}

示例（将 {PROJECT_KEY} 替换为检测到的项目键）：

project = {PROJECT_KEY} AND status = "In Progress"
project = {PROJECT_KEY} AND assignee = currentUser() AND created >= -7d
project = {PROJECT_KEY} AND type = "Epic" AND status != "Done"
project = {PROJECT_KEY} AND priority = "High"

3. 获取问题详情

根据你掌握的信息选择：

• 如果有 ARI：fetch(ari)
• 如果有问题键/ID：getJiraIssue(cloudId, issueKey)

4. 创建问题

必须始终使用配置中检测到的 projectKey 和 cloudId

分步流程：

a. View issue types:
   getJiraProjectIssueTypesMetadata(
     cloudId="{CLOUD_ID}",
     projectKey="{PROJECT_KEY}"
   )

b. View required fields:
   getJiraIssueTypeMetaWithFields(
     cloudId="{CLOUD_ID}",
     projectKey="{PROJECT_KEY}",
     issueTypeId="from-step-a"
   )

c. Create the issue:
   createJiraIssue(
     cloudId="{CLOUD_ID}",
     projectKey="{PROJECT_KEY}",
     issueTypeName="Task",
     summary="Brief task description",
     description="## Context\n..."
   )

**注意：**将 {PROJECT_KEY} 和 {CLOUD_ID} 替换为检测到的配置值。

可用的问题类型：

• 任务（默认）
• 史诗
• 子任务（需要使用父问题键填写 parent 字段）

5. 更新和转换问题

编辑字段：

editJiraIssue(cloudId, issueKey, fields)

更改状态：

1. Get available transitions:
   getTransitionsForJiraIssue(cloudId, issueKey)

2. Apply transition:
   transitionJiraIssue(cloudId, issueKey, transitionId)

添加评论：

addCommentToJiraIssue(cloudId, issueKey, comment)

默认任务模板

创建问题时，description 字段中必须始终使用此模板：

## Context

[Brief explanation of the problem or need]

## Objective

[What needs to be accomplished]

## Technical Requirements

[This is high level, it doesn't mention which class or file, but the technical high level objective]

- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Requirement 3

## Acceptance Criteria

- [ ] Criteria 1
- [ ] Criteria 2
- [ ] Criteria 3

## Technical Notes

[Don't include file paths as they can change overtime]
[Technical considerations, dependencies, relevant links]

## Estimate

[Time estimate or story points, if applicable]

最佳实践

✅ 应做事项

• 所有操作始终使用检测到的项目键
• description 字段始终使用 Markdown
• 自然语言查询先使用 search
• 精确筛选使用 JQL（但必须始终包含 project = {PROJECT_KEY}）
• 遵循任务模板以保持一致性
• 避免在描述中使用文件路径（这些路径会随时间变化）
• 摘要尽量简短，描述则应详细

⚠️ 重要事项

• 问题 ID 是数字（内部使用）
• 问题键采用 "{PROJECT_KEY}-123" 格式（面向用户）
• 创建子任务：使用父问题键填写 parent 字段
• CloudId 可以是 URL 或 UUID，两者均可
• 使用从工作区规则或用户输入中检测到的配置值

示例

示例 1：创建任务

User: "Create a task to implement user authentication"

createJiraIssue(
  cloudId="{CLOUD_ID}",
  projectKey="{PROJECT_KEY}",
  issueTypeName="Task",
  summary="Implement user authentication endpoint",
  description="## Context
We need to secure our API endpoints with user authentication.

## Objective
Implement JWT-based authentication for API access.

## Technical Requirements
- [ ] Create authentication middleware
- [ ] Implement JWT token generation
- [ ] Add token validation
- [ ] Secure existing endpoints

## Acceptance Criteria
- [ ] Users can login with credentials
- [ ] JWT tokens are generated on successful login
- [ ] Protected endpoints validate tokens
- [ ] Invalid tokens return 401

## Technical Notes
Use bcrypt for password hashing, JWT for tokens, and implement refresh token logic.

## Estimate
5 story points"
)

**注意：**将占位符替换为从检测到的配置中获取的实际值。

示例 2：搜索并更新问题

User: "Find my in-progress tasks and update the first one"

1. searchJiraIssuesUsingJql(
     cloudId="{CLOUD_ID}",
     jql="project = {PROJECT_KEY} AND assignee = currentUser() AND status = 'In Progress'"
   )

2. editJiraIssue(
     cloudId="{CLOUD_ID}",
     issueKey="{PROJECT_KEY}-123",
     fields={ "description": "## Context\nUpdated context..." }
   )

**注意：**将占位符替换为检测到的配置值。

示例 3：转换问题状态

User: "Move task {PROJECT_KEY}-456 to Done"

1. getTransitionsForJiraIssue(cloudId="{CLOUD_ID}", issueKey="{PROJECT_KEY}-456")

2. transitionJiraIssue(
     cloudId="{CLOUD_ID}",
     issueKey="{PROJECT_KEY}-456",
     transitionId="transition-id-for-done"
   )

**注意：**将占位符替换为检测到的配置值。

示例 4：创建子任务

User: "Create a subtask for {PROJECT_KEY}-789"

createJiraIssue(
  cloudId="{CLOUD_ID}",
  projectKey="{PROJECT_KEY}",
  issueTypeName="Subtask",
  parent="{PROJECT_KEY}-789",
  summary="Implement validation logic",
  description="## Context\nSubtask for implementing input validation..."
)

**注意：**将占位符替换为检测到的配置值。

常用 JQL 模式

所有查询必须包含 project = {PROJECT_KEY}（使用检测到的项目键）：

# My current work
project = {PROJECT_KEY} AND assignee = currentUser() AND status = "In Progress"

# Recent issues
project = {PROJECT_KEY} AND created >= -7d

# High priority bugs
project = {PROJECT_KEY} AND type = Bug AND priority = High

# Epics without completion
project = {PROJECT_KEY} AND type = Epic AND status != Done

# Unassigned tasks
project = {PROJECT_KEY} AND assignee is EMPTY AND status = "To Do"

# Issues updated this week
project = {PROJECT_KEY} AND updated >= startOfWeek()

**注意：**将 {PROJECT_KEY} 替换为从检测到的配置中获取的实际项目键。

重要说明

• 项目键是必填项——始终在 JQL 查询中包含 project = {PROJECT_KEY}
• 使用检测到的配置——从 .cursor/rules/jira-config.mdc 中读取，或询问用户
• 描述中使用 Markdown——不要使用 HTML 或纯文本
• 遵循模板——确保各问题保持一致
• 优先使用自然语言搜索——仅在需要时使用 JQL
• 避免使用文件路径——路径会变化并过时
• 技术说明保持高层次——关注方法，而非实现细节
• 故事点为可选项——在相关时添加估算