변경 전 승인을 받고 Jira 티켓을 안전하게 확인하고 업데이트합니다. — Claude Skill

명령 참고

jira CLI 전체 참고입니다.

---

이슈 보기

# 단일 이슈 보기
jira issue view ISSUE-KEY

# 더 많은 댓글과 함께 보기
jira issue view ISSUE-KEY --comments 5

# 원시 JSON 가져오기
jira issue view ISSUE-KEY --raw

---

이슈 목록

# 프로젝트의 모든 이슈 나열
jira issue list

# 내 이슈 나열
jira issue list -a$(jira me)

# 상태로 필터링(여러 단어 상태는 따옴표 사용)
jira issue list -s"In Progress"
jira issue list -s"To Do"
jira issue list -sDone

# 유형으로 필터링
jira issue list -tBug
jira issue list -tStory
jira issue list -tTask
jira issue list -tEpic

# 우선순위로 필터링
jira issue list -yHigh
jira issue list -yCritical

# 라벨로 필터링
jira issue list -lurgent -lbug

# 필터 결합
jira issue list -a$(jira me) -s"In Progress" -yHigh

# 텍스트로 검색
jira issue list "로그인 오류"

# 최근 접근한 항목
jira issue list --history

# 내가 감시 중인 이슈
jira issue list -w

# 생성/수정 필터
jira issue list --created today
jira issue list --created week
jira issue list --updated -2d

# 스크립트용 일반 출력
jira issue list --plain --no-headers

# 특정 열
jira issue list --plain --columns key,summary,status,assignee

# 원시 JQL 쿼리
jira issue list -q"status = 'In Progress' AND assignee = currentUser()"

# 결과 페이지 처리
jira issue list --paginate 20
jira issue list --paginate 10:50 # 시작:개수

---

이슈 생성

# 대화형 생성
jira issue create

# 모든 필드를 넣은 비대화형 생성
jira issue create \
    -tBug \
    -s"로그인 버튼이 작동하지 않음" \
    -b"사용자가 Safari에서 로그인 버튼을 클릭할 수 없음" \
    -yHigh \
    -lbug -lurgent

# 생성 후 나에게 할당
jira issue create -tTask -s"요약" -a$(jira me)

# 하위 작업 생성(상위 이슈 필요)
jira issue create -tSub-task -P"PROJ-123" -s"하위 작업 요약"

# 맞춤 필드와 함께 생성
jira issue create -tStory -s"요약" --custom story-points=3

# 선택 필드 프롬프트 건너뛰기
jira issue create -tTask -s"빠른 작업" --no-input

# 생성 후 브라우저에서 열기
jira issue create -tBug -s"버그 제목" --web

# 파일에서 설명 읽기
jira issue create -tStory -s"요약" --template /path/to/template.md

# stdin에서 설명 읽기
echo "여기에 설명" | jira issue create -tTask -s"요약"

여러 줄 내용: CLI는 여러 줄 문자열에서 문제가 생길 수 있습니다. 먼저 /tmp에 작성하세요:

cat > /tmp/jira_body.md <<'EOF'
## 설명
사용자가 데이터를 내보낼 수 있어야 합니다...

## 수락 기준
- CSV 내보내기가 작동함
- JSON 내보내기가 작동함
EOF

jira issue create --no-input \
  -tStory \
  -pPROJ \
  -s"내보내기 기능 추가" \
  -b"$(cat /tmp/jira_body.md)"

---

이슈 전환

# 상태로 이동
jira issue move ISSUE-KEY "In Progress"
jira issue move ISSUE-KEY "Done"
jira issue move ISSUE-KEY "To Do"

# 댓글과 함께 이동
jira issue move ISSUE-KEY "Done" --comment "구현 완료"

# 이동하고 해결 상태 설정
jira issue move ISSUE-KEY "Done" -R"수정됨"

# 이동하고 재할당
jira issue move ISSUE-KEY "In Review" -a"[email protected]"

# 전환 후 브라우저에서 열기
jira issue move ISSUE-KEY "Done" --web

---

이슈 할당

# 특정 사용자에게 할당
jira issue assign ISSUE-KEY "[email protected]"
jira issue assign ISSUE-KEY "John Doe"

# 나에게 할당
jira issue assign ISSUE-KEY $(jira me)

# 기본 담당자에게 할당
jira issue assign ISSUE-KEY default

# 할당 해제
jira issue assign ISSUE-KEY x

---

댓글

# 댓글 추가
jira issue comment add ISSUE-KEY -b"내 댓글입니다"

# 파일에서 댓글 추가
jira issue comment add ISSUE-KEY --template /path/to/comment.md

---

스프린트

# 스프린트 목록
jira sprint list

# 활성 스프린트만
jira sprint list --state active

# 이슈를 스프린트에 추가
jira sprint add SPRINT-ID ISSUE-KEY

# 스프린트 닫기
jira sprint close SPRINT-ID

---

이슈 연결

# 기본 연결
jira issue link PROJ-123 PROJ-456 "Relates"

# 차단 관계(차단자가 먼저 옴)
jira issue link PROJ-100 PROJ-200 "Blocks"
# 의미: PROJ-100이 PROJ-200을 차단

# 에픽에 연결
jira issue link PROJ-EPIC PROJ-STORY "Epic-Story"

---

기타 명령

# 브라우저에서 이슈 열기
jira open ISSUE-KEY

# 현재 사용자 표시
jira me

# 서버 정보
jira serverinfo

# 프로젝트 목록
jira project list

# 보드 목록
jira board list

MCP 참고

MCP를 통한 Atlassian Jira 작업 전체 참고입니다.

MCP 도구 참고

검색 작업

mcp__atlassian__searchJiraIssuesUsingJql

JQL(Jira Query Language)로 Jira를 검색합니다.

매개변수:

• jql(필수): JQL 쿼리 문자열
• maxResults: 최대 결과 수(기본값: 50)
• startAt: 페이지 오프셋
• fields: 반환할 필드를 쉼표로 구분

예시:

mcp__atlassian__searchJiraIssuesUsingJql(jql: "project = PROJ AND status = 'In Progress'")

이슈 작업

mcp__atlassian__getJiraIssue

키로 전체 이슈 세부 정보를 가져옵니다.

매개변수:

• issueKey(필수): 이슈 키(예: "PROJ-123")
• expand: 추가 데이터(changelog, transitions, renderedFields)

예시:

mcp__atlassian__getJiraIssue(issueKey: "PROJ-123")

mcp__atlassian__createJiraIssue

새 이슈를 생성합니다.

매개변수:

• projectKey(필수): 대상 프로젝트
• issueType(필수): 이슈 유형(Story, Bug, Task, Epic 등)
• summary(필수): 이슈 제목
• description: 상세 설명
• assignee: 계정 ID(먼저 lookupJiraAccountId 사용)
• priority: 우선순위 이름(Highest, High, Medium, Low, Lowest)
• labels: 라벨 배열
• components: 컴포넌트 이름 배열
• 필요에 따라 맞춤 필드

예시:

mcp__atlassian__createJiraIssue(
  projectKey: "PROJ",
  issueType: "Story",
  summary: "사용자 인증 구현",
  description: "OAuth2 인증 흐름 추가...",
  labels: ["백엔드", "보안"]
)

mcp__atlassian__editJiraIssue

기존 이슈를 수정합니다.

매개변수:

• issueKey(필수): 수정할 이슈
• 수정할 모든 필드(summary, description, assignee 등)

예시:

mcp__atlassian__editJiraIssue(
  issueKey: "PROJ-123",
  description: "더 자세한 설명으로 업데이트..."
)

전환 작업

mcp__atlassian__getTransitionsForJiraIssue

이슈에서 사용할 수 있는 상태 전환을 가져옵니다.

매개변수:

• issueKey(필수): 이슈 키

반환: 사용 가능한 전환의 ID와 이름 목록.

mcp__atlassian__transitionJiraIssue

이슈 상태를 변경합니다.

매개변수:

• issueKey(필수): 이슈 키
• transitionId(필수): getTransitions에서 받은 전환 ID
• comment: 전환에 붙일 선택 댓글

워크플로:

1. 전환 가져오기: getTransitionsForJiraIssue("PROJ-123")
2. 결과에서 원하는 전환 ID 찾기
3. 실행: transitionJiraIssue(issueKey: "PROJ-123", transitionId: "31")

댓글 작업

mcp__atlassian__addCommentToJiraIssue

이슈에 댓글을 추가합니다.

매개변수:

• issueKey(필수): 이슈 키
• body(필수): 댓글 텍스트(Jira markdown 지원)

사용자 작업

mcp__atlassian__lookupJiraAccountId

할당에 사용할 사용자 계정 ID를 찾습니다.

매개변수:

• query(필수): 표시 이름, 이메일, 사용자 이름으로 검색

예시:

mcp__atlassian__lookupJiraAccountId(query: "[email protected]")

사용법: 이슈를 할당하기 전에 항상 계정 ID를 조회하세요.

프로젝트 작업

mcp__atlassian__getVisibleJiraProjects

사용 가능한 Jira 프로젝트를 나열합니다.

매개변수:

• maxResults: 최대 결과 수

mcp__atlassian__getJiraProjectIssueTypesMetadata

프로젝트의 이슈 유형과 필수 필드를 가져옵니다.

매개변수:

• projectKey(필수): 프로젝트 키

사용법: 필수 필드를 이해하려면 이슈 생성 전에 호출하세요.

mcp__atlassian__getJiraIssueTypeMetaWithFields

이슈 유형의 상세 필드 메타데이터를 가져옵니다.

매개변수:

• projectKey(필수): 프로젝트 키
• issueTypeId(필수): 이슈 유형 ID

---

JQL(Jira Query Language) 참고

기본 문법

field operator value [AND|OR field operator value]

일반 필드

연산자

함수

상대 날짜

# 일
created >= -7d    # 최근 7일
updated >= -30d   # 최근 30일

# 주
created >= -2w    # 최근 2주

# 월
created >= -1M    # 지난달

# 특정 날짜
created >= "2024-01-01"

정렬

# 우선순위 기준 정렬, 가장 높은 것부터
project = PROJ ORDER BY priority DESC

# 여러 정렬 필드
project = PROJ ORDER BY status ASC, created DESC

복잡한 쿼리 예시

# 내 열린 이슈, 높은 우선순위
assignee = currentUser() AND status NOT IN (Done, Closed) AND priority >= High

# 이번 주 생성된 버그
issuetype = Bug AND created >= startOfWeek() ORDER BY priority DESC

# 진행 중인 에픽과 스토리
issuetype = Epic AND status = "In Progress" AND issueFunction in hasLinks("is parent of")

# 최근 내가 업데이트한 이슈
updatedBy = currentUser() AND updated >= -7d ORDER BY updated DESC

# 차단된 이슈
status = Blocked OR "Flagged" = "Impediment"

# 특정 에픽에 연결된 이슈
"Epic Link" = PROJ-100 AND status != Done

# 스프린트 백로그 항목
sprint in openSprints() AND status = "To Do" ORDER BY rank ASC

# 할당되지 않은 높은 우선순위 버그
issuetype = Bug AND assignee IS EMPTY AND priority >= High

# 내가 감시 중인 이슈
watcher = currentUser()

# 팀이 최근 해결한 이슈
resolved >= -7d AND project = PROJ ORDER BY resolved DESC

---

이슈 연결

제한 사항

Atlassian MCP는 현재 이슈 연결 생성을 지원하지 않습니다. 대신 포함된 jira-link-issues 스크립트를 사용하세요.

연결 유형

스크립트 사용법

# PROJ-123이 PROJ-456에 의존하도록 연결
~/.claude/skills/jira/jira-link-issues PROJ-123 PROJ-456 "Depends On"

# PROJ-100이 PROJ-200을 차단
~/.claude/skills/jira/jira-link-issues PROJ-100 PROJ-200 "Blocks"

# 일반 관계
~/.claude/skills/jira/jira-link-issues PROJ-50 PROJ-75 "Relates To"

연결 유형 찾기

사용 가능한 연결 유형을 가져오려면 Jira API를 조회합니다:

curl -s -u "$JIRA_USER:$JIRA_API_TOKEN" \
  "$JIRA_BASE_URL/rest/api/3/issueLinkType" | jq '.issueLinkTypes[].name'

필수 환경 변수:

• JIRA_BASE_URL: Atlassian 인스턴스(예: https://yourcompany.atlassian.net)
• JIRA_USER: 이메일 주소
• JIRA_API_TOKEN: Atlassian 계정 설정의 API 토큰

---

설명 형식

Jira 마크업(Wiki 스타일)

h1. 제목 1
h2. 제목 2
h3. 제목 3

*굵은 텍스트*
_기울임 텍스트_
-strikethrough-
+underline+

{code:java}
public class Example {
    // code here
}
{code}

{quote}
인용문 텍스트
{quote}

* 글머리 기호 목록
** 중첩 글머리 기호
# Numbered list
## Nested number

[링크 텍스트|https://example.com]
[이슈 링크|PROJ-123]

||헤더 1||헤더 2||
|셀 1|셀 2|

{panel:title=패널 제목}
패널 내용
{panel}

Atlassian Document Format(ADF)

createJiraIssue에서는 설명에 ADF 형식을 사용할 수 있습니다:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "설명 텍스트"}
      ]
    }
  ]
}

---

오류 처리

흔한 오류

인증 문제

MCP 도구가 인증 오류를 반환하면:

1. /mcp를 실행해 연결 상태를 확인합니다
2. 연결이 끊겼으면 Atlassian MCP 서비스를 다시 연결합니다
3. Atlassian 설정에서 API 토큰 권한을 확인합니다

필드 검증

이슈 생성 전:

1. 프로젝트 메타데이터 가져오기: getJiraProjectIssueTypesMetadata
2. 이슈 유형의 필수 필드 확인
3. 담당자 필드용 사용자 계정 ID 조회
4. 맞춤 필드 ID와 유효한 값 확인

---

일반 워크플로

티켓을 Done으로 이동

1. 사용 가능한 전환 가져오기:
   mcp__atlassian__getTransitionsForJiraIssue(issueKey: "PROJ-123")
   → 전환 ID가 포함된 목록 반환

2. 응답에서 "Done" 전환 ID 찾기

3. 전환 실행:
   mcp__atlassian__transitionJiraIssue(
     issueKey: "PROJ-123",
     transitionId: "done_id"
   )

4. 댓글 추가:
   mcp__atlassian__addCommentToJiraIssue(
     issueKey: "PROJ-123",
     body: "완료 및 배포됨"
   )

이슈 생성 및 할당

1. 사용자 계정 ID 조회:
   mcp__atlassian__lookupJiraAccountId(query: "[email protected]")
   → 계정 ID 반환

2. 할당과 함께 이슈 생성:
   mcp__atlassian__createJiraIssue(
     projectKey: "PROJ",
     issueType: "Task",
     summary: "기능 X 구현",
     description: "상세 내용...",
     assignee: "account_id_from_step_1"
   )

내 진행 중 이슈 나열

mcp__atlassian__searchJiraIssuesUsingJql(
  jql: "assignee = currentUser() AND status = 'In Progress' ORDER BY updated DESC"
)

생성 전 프로젝트 정보 가져오기

1. 사용 가능한 프로젝트 나열:
   mcp__atlassian__getVisibleJiraProjects()

2. 프로젝트의 이슈 유형 가져오기:
   mcp__atlassian__getJiraProjectIssueTypesMetadata(projectKey: "PROJ")

3. 올바른 유형으로 이슈 생성:
   mcp__atlassian__createJiraIssue(
     projectKey: "PROJ",
     issueType: "Story",
     summary: "...",
     description: "..."
   )

Jira 스킬

이슈, 스프린트, 워크플로를 관리하기 위한 Jira 자연어 인터페이스입니다. 이 스킬은 Claude가 대화형 명령으로 Jira 티켓을 조회, 생성, 수정, 전환할 수 있게 합니다.

목적

Jira 스킬은 자연어 요청과 Jira 작업 사이의 간극을 연결합니다. 특정 CLI 명령이나 API 호출을 외우는 대신, Jira 티켓으로 무엇을 하고 싶은지 Claude에게 말하면 스킬이 기술적 세부 사항을 처리합니다.

핵심 이점:

• 대화형 인터페이스: "내 열린 티켓은 무엇인가요?" 또는 "PROJ-123을 Done으로 옮겨"처럼 질문합니다
• 이중 백엔드 지원: jira CLI 또는 Atlassian MCP 중 하나로 작동합니다
• 안전 우선 접근: 수정 전 항상 현재 상태를 가져오고 변경에는 승인을 요구합니다
• 맥락 인식: 대화에서 이슈 키(예: PROJ-123)를 감지하고 관련 작업을 제안합니다

사용 시점

이 스킬은 다음 상황에서 활성화됩니다:

• Jira 이슈 키를 언급할 때(예: "PROJ-123 보여줘", "ABC-456 상태가 뭐야?")
• 티켓을 물을 때("내 열린 티켓 목록", "내게 할당된 것은?")
• 이슈를 만들고 싶을 때("로그인 문제에 대한 버그 티켓 생성")
• 티켓을 수정해야 할 때("이걸 In Progress로 옮겨", "PROJ-123을 나에게 할당")
• 스프린트 상태를 확인할 때("현재 스프린트에 뭐가 있어?", "스프린트 백로그 보여줘")
• 워크플로를 관리할 때("이 티켓 닫아", "PROJ-123에 댓글 추가")

트리거 문구 예시:

• "Jira 티켓 생성해 줘"
• "PROJ-123 보여줘"
• "내 티켓 목록 보여줘"
• "티켓을 완료로 이동해 줘"
• "현재 스프린트에 뭐가 있어?"
• "jira", "issue", "ticket", "sprint", "backlog" 언급

작동 방식

1. 백엔드 감지

활성화되면 스킬은 먼저 어떤 백엔드를 사용할 수 있는지 판단합니다:

1. CLI 백엔드: jira 명령이 설치되어 있는지 확인
2. MCP 백엔드: Atlassian MCP 도구(mcp__atlassian__*)를 찾음
3. 백엔드 없음: 위 둘 중 하나를 설치하도록 안내

2. 작업 실행

백엔드가 감지되면:

1. 읽기 작업(조회, 목록): 즉시 실행하고 결과를 표시합니다
2. 쓰기 작업(생성, 수정, 전환):
   • 먼저 현재 이슈 상태를 가져옵니다
   • 제안 변경 사항을 보여줍니다
   • 사용자 승인을 요청합니다
   • 작업을 실행합니다
   • 결과를 검증합니다

3. 안전 점검

수정 전 스킬은 다음을 수행합니다:

• 현재 이슈 상태를 가져옵니다(상태나 담당자를 절대 가정하지 않음)
• 영향을 받을 수 있는 사람을 확인합니다(감시자, 연결된 이슈)
• 작업을 되돌릴 수 있는지 검증하거나, 그렇지 않으면 경고합니다
• 올바른 식별자를 확인합니다(전환 ID, 계정 ID)

핵심 기능

이슈 관리

• 이슈 보기: 설명, 상태, 담당자, 댓글을 포함한 전체 세부 정보 확인
• 이슈 목록: 담당자, 상태, 유형, 우선순위, 라벨, 맞춤 JQL로 필터링
• 이슈 생성: 여러 줄 설명을 포함해 전체 필드 지원으로 티켓 생성
• 이슈 수정: 요약, 설명, 우선순위, 라벨, 맞춤 필드 수정
• 이슈 할당: 자신, 다른 사람에게 할당하거나 할당 해제

워크플로 작업

• 이슈 전환: 워크플로 상태(To Do, In Progress, Done) 사이로 티켓 이동
• 댓글 추가: 티켓에 진행 상황이나 결정을 문서화
• 이슈 연결: 티켓 간 관계 생성(blocks, relates to, duplicates)

스프린트 관리

• 스프린트 목록: 활성, 미래, 종료된 스프린트 보기
• 스프린트 이슈: 현재 스프린트에 무엇이 있는지 확인
• 스프린트에 추가: 이슈를 스프린트로 이동

검색과 쿼리

• 자연어 검색: 텍스트 쿼리와 일치하는 이슈 찾기
• JQL 지원: 복잡한 검색에 Jira Query Language 전체 사용
• 필터 조합: 담당자, 상태, 유형, 날짜 필터 결합

사용 예시

이슈 보기

"PROJ-123 보여줘"
"ABC-456 상태가 뭐야?"
"그 버그 티켓 상세 정보 보여줘"

이슈 목록

"내 열린 티켓 목록 보여줘"
"진행 중인 이슈가 뭐야?"
"우선순위 높은 버그 보여줘"
"이번 주 업데이트된 티켓 모두 찾아줘"
"[email protected]에게 할당된 것은 뭐야?"

이슈 생성

"로그인 시간 초과 이슈에 대한 버그 티켓 생성해 줘"
"문서 업데이트를 위한 새 작업 만들어줘"
"수락 기준을 포함해 내보내기 기능 구현 스토리 생성해 줘"

이슈 수정

"PROJ-123을 진행 중으로 이동해 줘"
"이 티켓을 나에게 할당해 줘"
"버그를 완료로 표시해 줘"
"수정 사항이 배포됐다는 댓글 추가해 줘"
"우선순위를 높음으로 바꿔줘"

스프린트 작업

"현재 스프린트에 뭐가 있어?"
"활성 스프린트 보여줘"
"스프린트 백로그 항목 목록 보여줘"

고급 JQL 쿼리

"이번 주 생성된 모든 버그 찾아줘"
"할당되지 않은 높은 우선순위 이슈 보여줘"
"내가 최근 업데이트한 티켓 목록 보여줘"
"PROJ-100에 의해 차단된 이슈 찾아줘"

사전 요구 사항

다음 백엔드 중 하나가 구성되어 있어야 합니다:

옵션 1: jira CLI(권장)

jira CLI는 Jira에 빠른 로컬 접근을 제공합니다.

설치:

# macOS
brew install ankitpokhrel/jira-cli/jira-cli

# Linux
# https://github.com/ankitpokhrel/jira-cli/releases 에서 다운로드

설정:

jira init

프롬프트에 따라 Jira 서버 URL과 인증을 구성합니다.

옵션 2: Atlassian MCP

Atlassian MCP는 Model Context Protocol을 통해 Jira 접근을 제공합니다.

Claude 설정에서 Atlassian 자격 증명으로 Atlassian MCP를 구성합니다. 그러면 mcp__atlassian__* 도구에 접근할 수 있습니다.

출력

이슈 보기

이슈를 볼 때 다음을 확인합니다:

• 이슈 키와 요약
• 상태, 우선순위, 유형
• 담당자와 보고자
• 설명
• 최근 댓글
• 연결된 이슈

이슈 목록

목록은 다음을 보여주는 표 형식으로 표시됩니다:

• 이슈 키
• 요약
• 상태
• 담당자
• 우선순위

작업 결과

수정 후 스킬은 다음을 수행합니다:

• 작업 성공을 확인합니다
• 업데이트된 상태를 보여줍니다
• 오류가 있으면 해결 안내와 함께 보고합니다

모범 사례

이슈 생성 전

1. 비슷한 이슈가 이미 있는지 확인합니다
2. 프로젝트의 필수 필드를 이해합니다
3. 명확하고 설명적인 요약을 사용합니다
4. 스토리에는 수락 기준을 포함합니다

전환 전

1. 스킬이 사용 가능한 전환을 가져오게 합니다(프로젝트마다 다릅니다)
2. 일부 워크플로는 중간 상태를 요구합니다
3. 전환 이유를 설명하는 댓글을 추가합니다

할당

1. MCP에서는 항상 계정 ID를 사용합니다(표시 이름이 아님)
2. 사용자가 프로젝트에 존재하는지 확인합니다
3. 담당자에게 별도로 알릴지 고려합니다

일괄 작업

1. 일괄 변경 전에 명시적 승인을 요청합니다
2. 각 변경은 감시자에게 알림을 보냅니다
3. 알림 폭주를 피하도록 타이밍을 고려합니다

일반 팁

• 수정 전에 항상 스킬이 현재 상태를 가져오게 합니다
• 설명을 수정할 때 원본 정보를 보존합니다
• 복잡한 편집에는 "브라우저에서 열기" 기능을 사용합니다
• 큰 변경 전 연결된 이슈를 확인합니다

안전 지침

스킬은 엄격한 안전 프로토콜을 따릅니다:

항상:

• 실행 전에 명령/도구 호출을 보여줍니다
• 수정 전 승인을 요청합니다
• 수정 시 원본 내용을 보존합니다
• 적용 후 업데이트를 검증합니다
• 인증 문제를 명확히 드러냅니다

절대:

• 현재 상태를 먼저 가져오지 않고 전환하지 않습니다
• MCP에서 표시 이름으로 할당하지 않습니다(계정 ID만 작동)
• 원본을 보여주지 않고 설명을 수정하지 않습니다
• 모든 필수 필드 없이 --no-input을 사용하지 않습니다
• 전환 이름이 모든 프로젝트에서 같다고 가정하지 않습니다
• 명시적 승인 없이 일괄 수정하지 않습니다

문제 해결

인증 문제

CLI:

# 다시 초기화
jira init

# 연결 확인
jira me

MCP:

• MCP 연결 상태를 확인합니다
• Atlassian 서비스를 다시 연결합니다
• API 토큰 권한을 확인합니다

흔한 오류

백엔드를 사용할 수 없음

CLI와 MCP가 모두 없으면:

1. jira CLI 설치(권장):

   brew install ankitpokhrel/jira-cli/jira-cli
   jira init
   

2. 또는 Claude 설정에서 Atlassian MCP 구성

참고 파일

고급 사용을 위해 이 스킬에는 자세한 참고 문서가 포함되어 있습니다:

• references/commands.md: 예제가 포함된 전체 CLI 명령 참고
• references/mcp.md: JQL 쿼리 가이드가 포함된 전체 MCP 도구 참고

다음과 같은 복잡한 작업을 처리할 때 필요할 때만 로드됩니다:

• 여러 줄 설명
• 복잡한 JQL 쿼리
• 전환 워크플로
• 이슈 연결

---

name: jira description: 사용자가 Jira 이슈(예: "PROJ-123")를 언급하거나, 티켓을 묻거나, 이슈 생성/조회/수정, 스프린트 상태 확인, Jira 워크플로 관리를 원할 때 사용합니다. "jira", "issue", "ticket", "sprint", "backlog" 같은 영문 키워드나 한국어 이슈 키 표현에서 트리거됩니다.

Jira

Jira와 자연어로 상호작용합니다. 여러 백엔드를 지원합니다.

백엔드 감지

어떤 백엔드를 사용할지 결정하려면 이 점검을 먼저 실행하세요:

1. jira CLI를 사용할 수 있는지 확인:
   → 실행: which jira
   → 발견되면: CLI BACKEND 사용

2. CLI가 없으면 Atlassian MCP 확인:
   → mcp__atlassian__* 도구를 찾기
   → 사용 가능하면: MCP BACKEND 사용

3. 둘 다 없으면:
   → 사용자에게 설정 안내

---

빠른 참고(CLI)

MCP 백엔드를 사용하는 경우 이 섹션은 건너뜁니다.

---

빠른 참고(MCP)

CLI 백엔드를 사용하는 경우 이 섹션은 건너뜁니다.

전체 MCP 패턴은 references/mcp.md를 참고하세요.

---

트리거

• "Jira 티켓 생성해 줘"
• "PROJ-123 보여줘"
• "내 티켓 목록 보여줘"
• "티켓을 완료로 이동해 줘"
• "현재 스프린트에 뭐가 있어?"

---

이슈 키 감지

이슈 키는 [A-Z]+-[0-9]+ 패턴을 따릅니다(예: PROJ-123, ABC-1).

사용자가 대화에서 이슈 키를 언급하면:

• CLI: jira issue view KEY 또는 jira open KEY
• MCP: 해당 키와 함께 mcp__atlassian__jira_get_issue

---

워크플로

티켓 생성:

1. 사용자가 코드/티켓/PR을 언급하면 맥락을 조사합니다
2. 티켓 내용을 초안 작성합니다
3. 사용자와 검토합니다
4. 적절한 백엔드로 생성합니다

티켓 수정:

1. 먼저 이슈 세부 정보를 가져옵니다
2. 상태를 확인합니다(진행 중 티켓은 특히 주의)
3. 현재 내용과 제안 변경 사항을 보여줍니다
4. 수정 전에 승인을 받습니다
5. 변경 설명 댓글을 추가합니다

---

작업 전 점검

스스로에게 물어보세요:

1. 현재 상태가 무엇인가? — 항상 이슈를 먼저 가져옵니다. 상태, 담당자, 필드가 사용자가 생각하는 것과 같다고 가정하지 않습니다.

2. 누가 영향을 받는가? — 감시자, 연결된 이슈, 상위 에픽을 확인합니다. "간단한 수정"도 10명에게 알림을 보낼 수 있습니다.

3. 되돌릴 수 있는가? — 전환에는 단방향 게이트가 있을 수 있습니다. 어떤 워크플로는 중간 상태를 요구합니다. 설명 수정에는 되돌리기가 없습니다.

4. 올바른 식별자가 있는가? — 이슈 키, 전환 ID, 계정 ID를 확인합니다. MCP 할당에서는 표시 이름이 작동하지 않습니다.

---

절대 하지 말 것

• 현재 상태를 가져오지 않고 전환하지 않기 — 워크플로가 중간 상태를 요구할 수 있습니다. "To Do" → "Done"은 먼저 "In Progress"가 필요하면 조용히 실패할 수 있습니다.

• MCP에서 표시 이름으로 할당하지 않기 — 계정 ID만 작동합니다. 항상 먼저 lookupJiraAccountId를 호출해야 하며, 그렇지 않으면 할당이 조용히 실패합니다.

• 원본을 보여주지 않고 설명을 수정하지 않기 — Jira에는 되돌리기가 없습니다. 사용자는 무엇을 대체하는지 봐야 합니다.

• 모든 필수 필드 없이 --no-input을 사용하지 않기 — 모호한 오류로 조용히 실패합니다. 먼저 프로젝트의 필수 필드를 확인하세요.

• 전환 이름이 보편적이라고 가정하지 않기 — "Done", "Closed", "Complete"는 프로젝트마다 다릅니다. 항상 사용 가능한 전환을 먼저 가져옵니다.

• 명시적 승인 없이 일괄 수정하지 않기 — 각 티켓 변경은 감시자에게 알림을 보냅니다. 10개 수정은 10번의 알림 폭주입니다.

---

안전

• 실행 전에 항상 명령/도구 호출을 보여줍니다
• 티켓을 수정하기 전에 항상 승인을 받습니다
• 수정할 때 원본 정보를 보존합니다
• 적용 후 업데이트를 검증합니다
• 인증 문제는 사용자가 해결할 수 있도록 항상 명확히 드러냅니다

---

사용 가능한 백엔드가 없을 때

CLI와 MCP가 모두 없으면 사용자에게 안내합니다:

Jira를 사용하려면 다음 중 하나가 필요합니다:

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

   설치: brew install ankitpokhrel/jira-cli/jira-cli
   설정: jira init

2. **Atlassian MCP**:
   Atlassian 자격 증명으로 MCP 설정에 구성합니다.

---

심층 참고

다음 경우 참고 문서를 로드합니다:

• 복잡한 필드나 여러 줄 내용이 있는 이슈를 생성할 때
• 단순 필터를 넘어서는 JQL 쿼리를 만들 때
• 오류나 인증 문제를 해결할 때
• 전환, 연결, 스프린트를 다룰 때

다음 경우 참고 문서를 로드하지 않습니다:

• 단순 조회/목록 작업(위 빠른 참고로 충분)
• 기본 상태 확인(jira issue view KEY)
• 브라우저에서 이슈 열기

References:

• CLI 패턴: references/commands.md
• MCP 패턴: references/mcp.md