jira-integration

name	jira-integration
description	Jira 티켓 조회, 요구 사항 분석, 티켓 상태 업데이트, 댓글 추가 또는 이슈 전환 시 이 스킬을 사용하십시오. MCP 또는 직접적인 REST 호출을 통한 Jira API 패턴을 제공합니다.
origin	ECC

Jira 통합 스킬

AI 코딩 워크플로우에서 Jira 티켓을 직접 조회, 분석 및 업데이트합니다. MCP 기반(권장) 및 직접 REST API 접근 방식을 모두 지원합니다.

활성화 시점

• 요구 사항 파악을 위해 Jira 티켓을 가져올 때
• 티켓에서 테스트 가능한 수락 기준(Acceptance Criteria)을 추출할 때
• Jira 이슈에 진행 상황 댓글을 추가할 때
• 티켓 상태를 전환할 때 (To Do → In Progress → Done)
• 병합 요청(PR/MR) 또는 브랜치를 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": "[e-mail]",
      "JIRA_API_TOKEN": "your-api-token"
    },
    "description": "Jira 이슈 추적 — 검색, 생성, 업데이트, 댓글, 상태 전환"
  }
}

보안: 비밀 정보를 절대 하드코딩하지 마십시오. 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 토큰

이 변수들을 쉘 환경, 비밀 관리자 또는 추적되지 않는 로컬 환경 파일에 저장하십시오. 저장소에 커밋하지 마십시오.

MCP 도구 참조

mcp-atlassian MCP 서버가 구성되면 다음 도구들을 사용할 수 있습니다:

도구명	용도	예시
jira_search	JQL 쿼리 실행	project = PROJ AND status = "In Progress"
jira_get_issue	키로 이슈 상세 정보 조회	PROJ-1234
jira_create_issue	이슈 생성 (Task, Bug, Story, Epic)	새로운 버그 리포트
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 참조

티켓 조회

curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -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
  }'

댓글 조회

curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -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
  }'

댓글 추가

curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -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. 사용 가능한 전환(transitions) 확인
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}'

# 2. 상태 전환 실행 (TRANSITION_ID 교체)
curl -s -X POST -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transition": {"id": "TRANSITION_ID"}}' \
  "$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions"

JQL 검색

curl -s -G -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  --data-urlencode "jql=project = PROJ AND status = 'In Progress'" \
  "$JIRA_URL/rest/api/3/search"

티켓 분석

개발 또는 테스트 자동화를 위해 티켓을 조회할 때 다음 사항을 추출하십시오:

1. 테스트 가능한 요구 사항

• 기능적 요구 사항 — 기능이 수행하는 작업
• 수락 기준 (Acceptance criteria) — 충족해야 하는 조건
• 테스트 가능한 동작 — 구체적인 동작 및 예상 결과
• 사용자 역할 — 기능을 사용하는 사람 및 권한
• 데이터 요구 사항 — 필요한 데이터
• 통합 지점 — 관련된 API, 서비스 또는 시스템

2. 필요한 테스트 유형

• 단위 테스트 — 개별 함수 및 유틸리티
• 통합 테스트 — API 엔드포인트 및 서비스 상호 작용
• E2E 테스트 — 사용자 대면 UI 흐름
• API 테스트 — 엔드포인트 계약 및 오류 처리

3. 예외 사례 및 오류 시나리오

• 유효하지 않은 입력 (비어 있음, 너무 김, 특수 문자)
• 권한 없는 접근
• 네트워크 실패 또는 타임아웃
• 동시 사용자 또는 경합 조건(race conditions)
• 경계 조건 (Boundary conditions)
• 누락되거나 null인 데이터
• 상태 전환 (뒤로 가기, 새로고침 등)

4. 구조화된 분석 출력 예시

티켓: PROJ-1234
요약: [티켓 제목]
상태: [현재 상태]
우선순위: [높음/중간/낮음]
테스트 유형: 단위, 통합, E2E

요구 사항:
1. [요구 사항 1]
2. [요구 사항 2]

수락 기준:
- [ ] [기준 1]
- [ ] [기준 2]

테스트 시나리오:
- 정상 경로 (Happy Path): [설명]
- 오류 케이스: [설명]
- 예외 케이스: [설명]

필요한 테스트 데이터:
- [데이터 항목 1]
- [데이터 항목 2]

의존성:
- [의존성 1]
- [의존성 2]

티켓 업데이트

업데이트 시점

워크플로우 단계	Jira 업데이트
작업 시작	"In Progress"로 상태 변경
테스트 작성 완료	테스트 커버리지 요약 댓글 추가
브랜치 생성	브랜치 이름 댓글 추가
PR/MR 생성	링크 추가 및 이슈 연결
테스트 통과	결과 요약 댓글 추가
PR/MR 병합	"Done" 또는 "In Review"로 상태 변경

댓글 템플릿

작업 시작:

이 티켓의 구현을 시작합니다.
브랜치: feat/PROJ-1234-feature-name

테스트 구현 완료:

자동화된 테스트 구현 완료:

단위 테스트:
- [테스트 파일 1] — [커버 범위]
- [테스트 파일 2] — [커버 범위]

통합 테스트:
- [테스트 파일] — [엔드포인트/흐름 커버 범위]

로컬에서 모든 테스트 통과. 커버리지: XX%

PR 생성:

풀 리퀘스트(PR)가 생성되었습니다:
[PR 제목](https://github.com/org/repo/pull/XXX)

리뷰 준비 완료.

작업 완료:

구현이 완료되었습니다.

PR 병합됨: [링크]
테스트 결과: 모두 통과 (X/Y)
커버리지: XX%

보안 가이드라인

• 소스 코드나 스킬 파일에 Jira API 토큰을 절대 하드코딩하지 마십시오.
• 항상 환경 변수나 비밀 관리자를 사용하십시오.
• 모든 프로젝트의 .gitignore에 .env를 추가하십시오.
• Git 이력에 노출된 경우 즉시 **토큰을 교체(rotate)**하십시오.
• 필요한 프로젝트로 범위가 제한된 최소 권한 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, 테스트 보고서, 대시보드 등).
• 다른 사람의 입력이 필요한 경우 @멘션을 사용하십시오.
• 시작하기 전에 연결된 이슈들을 확인하여 전체 기능 범위를 파악하십시오.
• 수락 기준이 모호한 경우 코드를 작성하기 전에 명확한 설명을 요청하십시오.