| 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": "your.email@example.com",
"JIRA_API_TOKEN": "your-api-token"
},
"description": "Jira 이슈 추적 — 검색, 생성, 업데이트, 댓글, 상태 전환"
}
}
보안: 비밀 정보를 절대 하드코딩하지 마십시오. JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN은 시스템 환경 변수(또는 비밀 관리자)에 설정하는 것이 좋습니다. MCP env 블록은 커밋되지 않는 로컬 설정 파일에만 사용하십시오.
Jira API 토큰 발급 방법:
- https://id.atlassian.com/manage-profile/security/api-tokens 접속
- API 토큰 만들기 클릭
- 토큰 복사 — 환경 변수에 저장하고 소스 코드에는 절대 저장하지 마십시오.
옵션 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"
티켓 상태 전환
curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
"$JIRA_URL/rest/api/3/issue/PROJ-1234/transitions" | jq '.transitions[] | {id, name: .name}'
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, 테스트 보고서, 대시보드 등).
- 다른 사람의 입력이 필요한 경우 @멘션을 사용하십시오.
- 시작하기 전에 연결된 이슈들을 확인하여 전체 기능 범위를 파악하십시오.
- 수락 기준이 모호한 경우 코드를 작성하기 전에 명확한 설명을 요청하십시오.
