# jira-sprint-report

> 스프린트 기반 주간업무보고서 생성. 스프린트 이름을 입력하면 Jira에서 이슈와 코멘트를 가져와 CATEGORY_CONFIG.md에 정의된 섹션별 마크다운 보고서를 자동 생성한다.

- Author: hnc-minjae
- Repository: hnc-minjae/claude-plugin
- Version: 20260208222957
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/hnc-minjae/claude-plugin
- Web: https://mule.run/skillshub/@@hnc-minjae/claude-plugin~jira-sprint-report:20260208222957

---

---
name: jira-sprint-report
description: 스프린트 기반 주간업무보고서 생성. 스프린트 이름을 입력하면 Jira에서 이슈와 코멘트를 가져와 CATEGORY_CONFIG.md에 정의된 섹션별 마크다운 보고서를 자동 생성한다.
user_invocable: true
argument: "{스프린트명} — 예: 'Sprint 5', '{PROJECT_KEY} Sprint 5'"
---

# 스프린트 보고서 생성 워크플로우

참조: [TEAM_CONFIG.md](TEAM_CONFIG.md) | [CATEGORY_CONFIG.md](CATEGORY_CONFIG.md) | [REPORT_FORMAT.md](REPORT_FORMAT.md)

## Step 0: 환경 검증

`JIRA_USER`, `JIRA_TOKEN` 환경변수 확인 → 미설정 시 안내 후 중단.

> `{API_BASE}`, `{PROJECT_KEY}`는 [TEAM_CONFIG.md](TEAM_CONFIG.md)에서 읽는다.

```bash
curl -s -u "$JIRA_USER:$JIRA_TOKEN" \
  "{API_BASE}/rest/api/3/myself" \
  -H "Accept: application/json" -w "\nHTTP_STATUS:%{http_code}"
```
HTTP 200 아니면 중단.

## Step 1: 스프린트 정보 조회

1. 보드 ID 조회:
   ```bash
   curl -s -u "$JIRA_USER:$JIRA_TOKEN" \
     "{API_BASE}/rest/agile/1.0/board?projectKeyOrId={PROJECT_KEY}&type=scrum" \
     -H "Accept: application/json"
   ```
   → `values[0].id` = BOARD_ID

2. 스프린트 검색:
   ```bash
   curl -s -u "$JIRA_USER:$JIRA_TOKEN" \
     "{API_BASE}/rest/agile/1.0/board/{BOARD_ID}/sprint?state=active,closed" \
     -H "Accept: application/json"
   ```
   - `name`이 `{스프린트명}`과 부분일치(대소문자 무시)하는 스프린트 선택
   - 다수 매칭 → 사용자 선택 / 매칭 없음 → 전체 목록 제시

3. 추출: `id`(SPRINT_ID), `name`(SPRINT_NAME), `startDate`, `endDate` (ISO 8601)

## Step 2: 이슈 조회 및 팀원 필터링

> 프로젝트를 한정하지 않고 스프린트 기준으로만 조회한다.

```bash
curl -s -u "$JIRA_USER:$JIRA_TOKEN" \
  "{API_BASE}/rest/api/3/search/jql" -G \
  --data-urlencode "jql=sprint = {SPRINT_ID}" \
  --data-urlencode "fields=key,summary,status,assignee,fixVersions,parent,comment,issuetype,labels,components,created,updated,statuscategorychangedate,description" \
  --data-urlencode "maxResults=100" --data-urlencode "startAt=0" \
  -H "Accept: application/json"
```

> `total > maxResults`이면 `startAt` 증가시키며 반복.

[TEAM_CONFIG.md](TEAM_CONFIG.md) 팀원의 이슈만 포함 (미지정 이슈 제외). 통계 집계 전에 적용.

## Step 3: 코멘트에서 작업 내용 추출

### 필터링 (3단계)

1. **스프린트 기간 내** 코멘트만
2. **담당자 작성분만** — `comment.author.displayName == assignee.displayName`
3. **진행 내용만** — 의견/질문/요청/상태변경알림/인사/자동생성 코멘트 제외

### ADF 텍스트 추출

```
extractAdfText(node):
  text → node.text | hardBreak → "\n" | mention → "@"+attrs.text
  emoji → attrs.shortName | inlineCard → attrs.url
  content(배열) → children.map(extractAdfText).join("")
```

블록: paragraph→텍스트+줄바꿈, bulletList/orderedList→"- "+텍스트, heading→텍스트, codeBlock/table/media→무시

### 요약

- 1~2개 한국어 개조식 bullet ("~구현", "~수정", "~완료", "~적용")
- 여러 코멘트 통합. "..."으로 자르지 않음. 원문 복사 금지, 핵심만 재작성

### Fallback

완료/종료/Done → "{제목} 완료" | 진행중 → "{제목} 진행중" | 대기/To do → "{제목} 착수 예정"

## Step 4: fixVersion 확보

[CATEGORY_CONFIG.md](CATEGORY_CONFIG.md)의 fixVersion 교차 조회 규칙을 따른다.

- 이슈 자체 fixVersions가 있으면 그대로 사용.
- 없으면 CATEGORY_CONFIG의 교차 조회 로직 적용: summary에서 외부 이슈 키 패턴 추출 → 해당 이슈의 fixVersions API 조회 (결과 캐싱):
```bash
curl -s -u "$JIRA_USER:$JIRA_TOKEN" \
  "{API_BASE}/rest/api/3/issue/{issueKey}?fields=fixVersions" \
  -H "Accept: application/json"
```
→ `fixVersions[0].name` 사용. 실패 시 빈 값.

## Step 5: 이슈 분류 및 그룹핑

[CATEGORY_CONFIG.md](CATEGORY_CONFIG.md)의 `### 섹션 N:` 헤더를 순서대로 파싱하여 섹션 목록을 구성한다. 각 섹션의 분류 규칙 테이블(P0~P5)과 그룹핑 설정을 적용한다.

## Step 6: 마크다운 생성

[REPORT_FORMAT.md](REPORT_FORMAT.md) 형식에 따라 생성. 섹션 순서는 CATEGORY_CONFIG 정의 순서를 따른다. 빈 섹션은 출력하지 않음.

## Step 7: 관리 포인트 분석

팀원 이슈의 **summary, description(ADF), 전체 코멘트(담당자 외 포함)** 를 종합 분석.

판별 기준: 일정 지연/이관, 리소스 부족, 외부 의존성/차단, 의사결정 필요, 기술적 리스크, 범위 변경

> 코멘트 맥락을 종합 판단. 해당 사항 없으면 섹션 생략.

## Step 8: 파일 저장 및 결과 요약

```bash
mkdir -p ~/.tasks/reports
```
파일명: `sprint-{SPRINT_NAME}-{YYMMDD-HHmm}.md` (KST, 특수문자 제거)

```
✅ 스프린트 보고서 생성 완료
📁 파일: ~/.tasks/reports/sprint-{name}-{timestamp}.md
📊 통계: 전체 {N}건 | 완료 {N}건 | 진행중 {N}건
📋 분류: {CATEGORY_CONFIG에서 파싱한 섹션별} {N}건 | ... | 기타 {N}건
```

## 에러 처리

| 상황 | 대응 |
|------|------|
| 환경변수 미설정 | 설정 안내 후 중단 |
| 인증 실패 (401/403) | 토큰 확인 안내 후 중단 |
| 스프린트 미발견 | 전체 목록 제시, 선택 요청 |
| API 실패 (5xx) | 1회 재시도, 실패 시 에러 출력 |
| 이슈 0건 | "해당 스프린트에 이슈가 없습니다" |
| ADF 파싱 실패 | 해당 코멘트 무시, fallback 사용 |