onejaejae/jira-dispatch

/jira:dispatch — Jira Subtask Batch Creator

Scope 리포트(specs/{KEY}-scope.md)의 Section 6 (Task Definition Candidates)을 파싱하여 사용자 확인 후 Jira REST API로 직접 서브태스크를 일괄 생성한다.

Phase 0: Parse & Validate (소스 파싱 + 인증 + 중복 체크)
Phase 1: Task Preview + Confirm (사용자 확인)
Phase 2: Sequential Creation (REST API로 서브태스크 생성)
Phase 3: Report (결과 보고)

Phase 0: Parse & Validate

1. 티켓 키 추출: 입력에서 부모 Jira 키를 파싱한다.

   • URL: https://khc.atlassian.net/browse/DPHRS-8 → DPHRS-8
   • Bare key: DPHRS-8 → DPHRS-8
   • Regex: ([A-Z][A-Z0-9]+-\d+)
   • 파싱 실패 시 → STOP

2. 태스크 소스 로드: 두 가지 소스를 순서대로 시도한다.

   • 1순위: ~/.claude/specs/{KEY}-scope.md 파일의 Section 6
   • 2순위: 사용자가 인라인으로 제공한 마크다운 테이블
   • 둘 다 없으면 → STOP with "먼저 /jira:assess {KEY}를 실행해주세요."

3. 마크다운 테이블 파싱: Section 6의 테이블에서 태스크를 추출한다.

   기대 형식:
   | # | Task | Priority | Assignee | Dependencies | Effort | DoD |
   |---|------|----------|----------|-------------|--------|-----|
   | 1 | {title} | HIGH | - | - | 5h | {dod} |
   

   각 행에서:

   • #: 태스크 번호
   • Task: 서브태스크 제목
   • Priority: HIGH → High, MED → Medium, LOW → Low, 기타 → Medium
   • Assignee: - 이면 기본 담당자(현재 사용자) 사용
   • Dependencies: 의존 태스크 번호 (Jira description에 포함)
   • Effort: 공수 추정 (Jira description에 포함)
   • DoD: 완료 기준 (Jira description에 포함). 비어있으면 "{title}이 정상 동작함" 기본값.

4. Jira 인증 확인 (REST API): jira CLI의 config에서 인증 정보를 추출한다:

   # jira CLI config에서 서버/로그인 정보 확인
   cat ~/.config/.jira/.config.yml
   

   필요 정보:

   • server: Jira 서버 URL (예: https://khc.atlassian.net)
   • login: 이메일 (예: [email protected])
   • API 토큰: 환경변수 JIRA_API_TOKEN (config 파일에는 없음)

   Auth 토큰 구성 (반드시 이 순서로):

   1. config에서 login을 읽고, JIRA_API_TOKEN 환경변수에서 토큰을 가져온다
   2. server URL trailing slash 제거: server="${server%/}" (이중 슬래시 방지)
   3. Basic Auth 토큰 생성: echo -n "{login}:${JIRA_API_TOKEN}" | base64
   4. 결과를 {auth_token}으로 사용

   인증 테스트:

   curl -s "https://{server}/rest/api/2/myself" \
     -H "Authorization: Basic {auth_token}" \
     -H "Content-Type: application/json"
   

   • 성공: 현재 사용자의 accountId와 displayName 캡처
   • 실패 → STOP with "Jira 인증 실패. jira init을 실행해주세요."

5. 현재 사용자 account ID 확인: REST API /rest/api/2/myself 응답에서:

   • accountId: 서브태스크 assignee에 사용 (예: 712020:bbef064a-b726-40d1-9e80-71ea963b7d90)
   • displayName: Preview에 표시
   • 중요: email이 아닌 accountId를 사용해야 assignee 할당이 동작함

6. 프로젝트 키 + 서브태스크 이슈 타입 ID 확인: 부모 티켓을 조회하여 프로젝트 키와 서브태스크 이슈 타입 ID를 확인한다:

   curl -s "https://{server}/rest/api/2/issue/{KEY}" \
     -H "Authorization: Basic {auth_token}"
   

   응답에서:

   • fields.project.key: 프로젝트 키 (예: DPHRS)
   • 부모 티켓 존재 확인
   • 부모 미존재 → STOP

   서브태스크 이슈 타입 ID 확인 (순서대로 시도):

   1. 기존 서브태스크가 있으면 → 응답의 fields.subtasks[0].fields.issuetype.id 추출
   2. 없으면 → createmeta에서 subtask 여부(subtask: true)인 타입 조회:

   curl -s "https://{server}/rest/api/2/issue/createmeta?projectKeys={PROJECT}" \
     -H "Authorization: Basic {auth_token}"
   

   응답의 projects[0].issuetypes 중 "subtask": true인 항목의 id를 사용. 주의: issuetypeNames에 "하위 작업"을 하드코딩하지 않는다 — Jira 인스턴스 언어에 따라 "Sub-task" 등 다를 수 있다.

7. 기존 서브태스크 중복 체크:

   jira issue list -q "parent = {KEY}" -p {PROJECT} --plain --no-truncate
   

   또는 REST API:

   curl -s "https://{server}/rest/api/2/search?jql=parent={KEY}" \
     -H "Authorization: Basic {auth_token}"
   

   • 기존 서브태스크 제목 목록을 수집
   • 새 태스크와 비교하여 중복 판정:

   중복 매칭 알고리즘:

   Step 1: 정규화

   • 양쪽 제목에서 leading/trailing 공백 제거, 연속 공백을 단일 공백으로
   • 대소문자 통일 (한국어는 해당 없음, 영문은 lowercase)

   Step 2: 정확 일치 검사

   • 정규화된 제목이 동일하면 → 즉시 SKIP

   Step 3: 토큰 기반 유사도 검사 (정확 일치 아닌 경우)

   • 토큰화: 공백 + 특수문자([, ], (, ), -, _, /)로 분리
   • 불용어 제거: 의, 및, 등, 를, 을, 이, 가, 에, for, the, a, an, and, or
   • Jaccard 유사도 계산: J(A, B) = |A ∩ B| / |A ∪ B|
   • J >= 0.70 → SKIP 후보 (Phase 1 Preview에서 SKIP? 표시, 사용자 확인)
   • J < 0.70 → NEW (생성 대상)

   예시:

   기존: "사용자 권한 관리 API"     새: "사용자 권한 관리 API"     → 정확 일치, SKIP
   기존: "사용자 권한 관리 API"     새: "사용자 권한 관리"          → J=0.75, SKIP?
   기존: "사용자 추가"              새: "권한 추가"                → J=0.33, NEW
   기존: "[BE] DB 마이그레이션"     새: "DB 마이그레이션 작성"     → J=0.67, NEW
   

   • 모든 태스크 SKIP → STOP

Phase 1: Task Preview + Confirm

파싱한 태스크를 사용자에게 보여주고 확인을 받는다.

Preview 출력

## Subtask Preview for {KEY}

**Parent**: {KEY} — {parent_title}
**Assignee**: {displayName} ({accountId 앞 8자...})
**Source**: specs/{KEY}-scope.md Section 6

| # | Title | Priority | Assignee | Status |
|---|-------|----------|----------|--------|
| 1 | {task_title} | High | {displayName} | NEW |
| 2 | {task_title} | Medium | {displayName} | NEW |
| 3 | {task_title} | - | - | SKIP (exists: {existing_key}) |

**NEW**: {count} tasks to create
**SKIP**: {count} tasks (already exist)

### Task Details
{For each NEW task:}
**#{n}: {title}**
- Priority: {priority}
- Effort: {effort}
- Dependencies: {deps}
- DoD: {dod}

사용자 확인

AskUserQuestion으로 확인:

1. Create All — {NEW_count}개 서브태스크 생성
2. Edit — 태스크 수정 요청 (수정 반영 후 Preview 재표시 → 재확인, 최대 3회)
3. Cancel — 생성 취소 → STOP

Edit 동작 상세:

• 사용자가 자연어로 수정 요청 (예: "Task #3 삭제해줘", "Task #1 제목 변경")
• 오케스트레이터가 메모리 내 태스크 목록을 수정 (scope.md는 수정하지 않음)
• 태스크 삭제 시: 해당 태스크 제거, 번호 리넘버링 하지 않음 (원래 번호 유지, 빈 번호는 SKIP)
• 태스크 추가 시: 마지막 번호 다음으로 추가
• 수정 반영 후 Preview 재출력 → AskUserQuestion 재확인

3회 Edit 소진 시: AskUserQuestion으로 Create All / Cancel 2지선다 강제.

Phase 2: Sequential Creation (REST API)

확인된 NEW 태스크를 Jira REST API로 직접 순서대로 생성한다.

생성 방법

scripts/create-subtask.sh 헬퍼 스크립트를 사용한다 (JSON 이스케이프, 에러 파싱 내장):

~/.claude/skills/jira-dispatch/scripts/create-subtask.sh \
  --server "{server}" \
  --auth "{auth_token}" \
  --project "{PROJECT_KEY}" \
  --parent "{PARENT_KEY}" \
  --type-id "{subtask_type_id}" \
  --summary "{task_title}" \
  --priority "{priority}" \
  --account-id "{account_id}" \
  --labels "{labels}" \
  --body-file "/tmp/{KEY}-task-{n}.md"

description은 /tmp/{KEY}-task-{n}.md에 임시 파일로 작성 후 --body-file로 전달한다.

Labels 처리

Labels는 부모 티켓의 labels를 상속한다:

• Phase 0에서 부모 티켓 조회 시 fields.labels 캡처
• 부모 labels가 있으면 동일 labels 적용
• 부모 labels가 없으면 빈 배열 []

Assignee 처리

1. 기본: Phase 0에서 확인한 현재 사용자의 accountId 사용
2. scope.md에서 지정된 경우: 이름으로 검색하여 accountId 조회

   curl -s "https://{server}/rest/api/2/user/search?query={name}" \
     -H "Authorization: Basic {auth_token}"
   

3. 조회 실패 시: assignee 필드 생략 (미지정 상태로 생성, 에러 방지)
4. "-" 또는 빈 값: 현재 사용자의 accountId로 할당

Description 템플릿

중요: Jira REST API v2의 description 필드는 Jira Wiki Markup을 사용한다. Markdown(##, -)을 사용하면 렌더링이 깨진다.

h2. Description
{task_title}

h2. Dependencies
{dependencies — #N을 실제 Jira 키로 치환한 값. 예: "DPHRS-63, DPHRS-64" or "None"}

h2. Effort Estimation
{effort}

h2. Definition of Done
* {dod_item_1}
* {dod_item_2}
* {dod_item_3}

----
_Created by /jira:dispatch from specs/{KEY}-scope.md_

Wiki Markup 변환 규칙: | Markdown | Jira Wiki Markup | |----------|-----------------| | ## Header | h2. Header | | ### Header | h3. Header | | - item | * item | | **bold** | *bold* | | *italic* | _italic_ | | --- | ---- | | `code` | {{code}} |

description을 /tmp/{KEY}-task-{n}.md 임시 파일에 작성할 때 반드시 Wiki Markup으로 작성한다.

특수문자 이스케이프:

• [text]: Jira가 유효한 링크가 아니면 무시. [DPHRS-123] 같은 이슈 키는 자동 링크화 (의도된 동작).
• | (파이프): Wiki Markup 테이블 구분자. description 본문에 |가 포함되면 \|로 이스케이프. 단, h2./h3. 헤더와 * 불릿 내부에서는 테이블 컨텍스트가 아니므로 이스케이프 불필요.
• { } (중괄호): Wiki Markup 매크로 구분자. {code}, {color} 등으로 해석될 수 있음. description에 중괄호가 포함되면 (예: Python dict {"key": "value"}) → \{ \}로 이스케이프하거나, {code}...{code} 블록 안에 넣어 보호.
• summary 필드는 plain text 처리되므로 이스케이프 불필요.

DoD 줄바꿈 처리: scope.md Section 6의 DoD 셀에 줄바꿈이나 여러 항목이 있으면, 각 항목을 * 접두사로 분리하여 Wiki Markup 불릿 리스트로 변환. 구분자: , 또는 \n 또는 실제 줄바꿈.

코드블록 변환: DoD에 마크다운 코드블록(```)이 포함된 경우 → Jira {code}...{code} 블록으로 변환.

실행 규칙

1. 순차 실행: 번호 순서대로 하나씩 생성
2. 개별 실패 허용: 실패해도 나머지 계속
3. 키 캡처 + 맵 유지: 생성 성공 시 {태스크번호 → Jira키} 맵에 기록. 예: {1: "DPHRS-63", 2: "DPHRS-64", ...}
4. Dependencies 키 치환: description 작성 시, Dependencies 값의 #N 참조를 맵에서 조회하여 실제 Jira 키로 치환
   • #1, #2, #3 → DPHRS-63, DPHRS-64, DPHRS-65
   • 맵에 없는 번호 (생성 실패 or SKIP된 태스크) → #N (미생성) 그대로 유지
   • 치환은 description 임시 파일 작성 시점에 수행 (create-subtask.sh 호출 전)
5. 진행률 출력:

   [1/5] Created DPHRS-63: SystemRole Enum + Role ORM 모델 정의
   [2/5] Created DPHRS-64: DB 마이그레이션
   [3/5] FAILED: 관리자 역할 관리 API — 400 Bad Request: {error}
   

에러 처리

| 에러 | 동작 | |------|------| | 400 Bad Request | 에러 메시지 파싱, 기록 후 다음 태스크 | | 401 Unauthorized | 전체 중단 (인증 만료) | | 403 Forbidden | 에러 기록, 다음 태스크 | | 네트워크 타임아웃 | 1회 재시도, 실패 시 기록 후 진행 | | JSON 파싱 에러 | 에러 기록, 다음 태스크 |

Phase 3: Report

결과 출력

## jira:dispatch Complete — {KEY}

| # | Key | Title | Priority | Assignee | Result |
|---|-----|-------|----------|----------|--------|
| 1 | DPHRS-63 | {title} | High | {name} | Created |
| 2 | DPHRS-64 | {title} | Medium | {name} | Created |
| 3 | - | {title} | - | - | Skipped (exists: DPHRS-42) |
| 4 | - | {title} | High | {name} | Failed: {reason} |

### Summary
- **Created**: {count}
- **Skipped**: {count}
- **Failed**: {count}

### Created Issues
- https://{server}/browse/DPHRS-63
- https://{server}/browse/DPHRS-64

Hard Rules

1. 사용자 확인 필수 — Phase 1에서 Create All 확인 없이 절대 생성하지 않음
2. 중복 생성 금지 — 기존 서브태스크와 제목이 동일하면 SKIP
3. 개별 실패 허용 — 개별 태스크 실패가 배치 전체를 중단하지 않음 (401 제외)
4. REST API 직접 호출 — jira CLI issue create 대신 curl + REST API 사용 (안정성)
5. accountId 사용 — assignee는 반드시 accountId로 지정 (email/displayName 불가)
6. 코드 수정 금지 — Jira 서브태스크만 생성, 코드 파일을 수정하지 않음
7. Edit 루프 제한 — 최대 3회 편집 후 Create All 또는 Cancel 강제
8. 순차 생성 — 병렬 생성하지 않음 (Jira API rate limit 방지)
9. DoD 필수 — DoD가 비어있으면 "{title}이 정상 동작함" 기본값 사용
10. Description 포함 — 모든 서브태스크에 Dependencies, Effort, DoD를 description에 포함

Known Issues & Workarounds

jira CLI issue create 안정성 문제 (2026-04-07 발견)

• 증상: jira issue create -t "Sub-task" 실행 시 issue type config 에러, assignee 매칭 실패, 명령 hang
• 원인: jira CLI config에 issue type ID 누락, assignee가 email로 매칭 안됨
• 해결: REST API 직접 호출로 전환. jira CLI는 조회(issue view, issue list, me)에만 사용.

create-subtask.sh 환경변수 export 누락 (2026-04-09 발견)

• 증상: Python heredoc에서 os.environ["PROJECT"] → KeyError
• 원인: bash 변수를 Python subprocess에 전달하려면 export 필요하나 누락
• 해결: export PROJECT PARENT SUMMARY TYPE_ID PRIORITY DESCRIPTION ACCOUNT_ID LABELS SERVER 추가

assignee email 매칭 불가 (2026-04-07 발견)

• 증상: -a "[email protected]" → "Unable to find associated user"
• 원인: Jira Cloud에서 email 기반 사용자 검색이 비활성화되어 있음
• 해결: /rest/api/2/myself에서 accountId 확인 후 사용. 타인 assignee는 /rest/api/2/user/search 사용.

Error Handling

| Scenario | Action | |----------|--------| | scope.md 미존재 | STOP with "먼저 /jira:assess를 실행해주세요" | | Section 6 파싱 실패 | STOP with "Section 6 테이블 형식이 올바르지 않습니다" | | Jira 인증 실패 (REST API) | STOP with "Jira 인증이 만료되었습니다. jira init을 실행해주세요" | | 부모 티켓 미존재 | STOP with "부모 티켓이 존재하지 않습니다" | | 서브태스크 이슈 타입 ID 조회 실패 | STOP with "서브태스크 이슈 타입을 찾을 수 없습니다" | | 모든 태스크 SKIP | STOP with "모든 태스크가 이미 존재합니다" | | 개별 생성 실패 | 기록 후 다음 태스크로 진행, Phase 3에서 보고 | | 401 응답 (인증 만료) | 전체 중단, 인증 재설정 안내 | | 사용자 Cancel | STOP with "서브태스크 생성이 취소되었습니다" |