issue-writer

---
name: issue-writer
description: Use when the user asks to write a new GitHub issue or Jira ticket for developer work ("이슈 만들어줘", "이슈 작성", "티켓 생성"), to modify or update an existing one with new information ("이슈 수정", "이슈 업데이트", "#N 수정", "#N에 반영해줘", "티켓 업데이트", "블로커 해결됐어"), or to 정리/정돈 one ("이슈 정리", "#N 정리", "티켓 정리", "개발자가 보기 쉽게 바꿔줘"). Writes, updates, or rewrites the body to the standard issue form (what to do at a glance, why, done criteria, can-start-now) without inventing requirements or losing the rationale.
---

# 이슈 작성

## 목적

개발자가 이슈를 **딱 보면 무엇을 해야 하는지** 알고, **왜 해야 하는지** 확인할 수 있게 본문을 표준 이슈 폼에 맞게 쓴다.
- **새로 작성**: 사용자가 준 내용으로 새 이슈를 만든다.
- **수정·업데이트**: 기존 이슈에 바뀐 내용(요구 변경, 블로커 해결, 범위 조정 등)만 반영한다. 나머지는 그대로 둔다.
- **기존 정리**: 이미 있는 이슈 본문 전체를 폼에 맞게 다시 쓴다.

요청이 "수정/업데이트/반영"이면 수정 절차를, "정리/정돈/보기 쉽게"면 정리 절차를 쓴다. 애매하면 어느 쪽인지 묻는다.

결과물은 이슈 본문이다 (판정 보고서나 댓글이 아니다).

## 대상 제한

- **개발자가 할 일로 발행하는 이슈·티켓만** 다룬다 (GitHub Issue, Jira).
- 개발자 작업이 아니면(회의록, 문의, 정책 논의, 추적용 모음, 단순 공유 등) 작성·정리하지 않고 "개발자 작업 아님"이라고만 답하고 끝낸다.

## 표준 이슈 폼

읽는 순서대로 배치한다. **1~2번만 읽어도 무엇을·왜·지금 시작할 수 있는지**가 보여야 한다.

| # | 항목 | 필수 | 작성 기준 |
|---|---|---|---|
| 1 | **요약 (Summary)** | 필수 | 무엇을 하는 이슈인지 한두 문장. 제목만 봐도 대략 알 수 있고 여기서 한 번 더 명확히 한다. 끝에 **착수 상태**를 한 줄로 붙인다: `즉시 착수 가능` / `선행 필요(막는 것 한 줄)` / `착수 불가(막는 것 한 줄)`. |
| 2 | **배경 / 목적 (Why)** | 필수 | 왜 필요한지, 어떤 문제를 해결하는지. 애매한 상황에서 개발자가 스스로 판단할 수 있을 만큼 쓴다. 요구 출처(요구사항 문서 조항·요구사항 번호·티켓)를 표기하고, 원문·번역은 10번에서 접어서 보존한다. |
| 3 | **요구사항 (What)** | 필수 | 구현해야 할 동작을 구체적으로. 기능은 `사용자 동작 → 기대 결과`, 버그는 `재현 절차 → 현재 결과 → 기대 결과`. 지금 동작과 끝난 뒤 동작은 관찰 가능한 문장으로 대비한다. 완료 조건은 여기 넣지 않고 5번 섹션으로 뺀다. |
| 4 | **할 일** | 필수 | 동사 + 파일·함수 단위 체크리스트. 백엔드 작업은 `[BE]`를 앞에 붙인다. 하위 이슈는 번호·담당 FE/BE 표기. |
| 5 | **완료 조건 (Acceptance Criteria)** | 필수 | `## 완료 조건` 별도 섹션, 체크박스. "언제 끝난 건지"를 검증 가능한 문장(동작·테스트·화면)으로. 할 일을 마친 뒤 확인하는 기준이라 할 일 바로 뒤에 둔다. 리뷰와 QA에서 왔다 갔다 하지 않게 하는 가장 중요한 항목이다. |
| 6 | **의존성 / 블로커** | 막는 것이 있을 때 필수 | 선행 이슈, 타 팀 작업, 미확정 사항. 항목마다 체크박스 + 확정할 내용 / 담당 / 막는 대상. **남은 블로커(`- [ ]`)를 먼저, 해결된 블로커(`- [x]`)를 뒤에** 둔다. "미확인"은 개발을 막는지 안 막는지 구분한다. 개발자가 "지금 바로 시작할 수 있는지" 판단하는 근거다. 출처 문서는 여기 두지 않고 9번 자료의 출처 항목에 합친다. |
| 7 | **범위 밖 (Out of Scope)** | 필수 | 이번에 하지 않는 것. 혼동하기 쉬운 것, 후속 이슈로 넘기는 것. 없으면 "없음"이라고 적는다. |
| 8 | **기술 참고 (Technical Notes)** | 선택 | 관련 파일·모듈, API 스펙, DB 변경 여부, 참고할 기존 코드, 예상 구현 방향. 아는 만큼만 쓰고 **확정이 아니면 "제안"이라고 표시**한다. 줄 번호 대신 함수명. |
| 9 | **자료 (References)** | 선택 | 출처 문서, 디자인·스크린샷·로그, 관련 이슈·PR 링크, 기준 브랜치. 출처 문서는 `- **출처**` 한 항목 아래 문서별 하위 줄로 한 번만 쓴다(`` `파일명` — 시트·항목 코드 ``). 같은 문서를 "기준"·"출처"·"기준 문서" 줄로 나눠 반복하지 않는다. 2번의 요구사항 조항 출처는 요구 근거라 그대로 둔다. 화면 캡처는 `<details>`로 접는다. |
| 10 | **근거 원문** | 원문이 있을 때 필수 | 요구사항 문서 등 원문·번역을 삭제하지 않고 `<details>`로 접어 보존한다. |

- **메타 정보**(우선순위, 담당자, 마일스톤, 크기)는 본문이 아니라 **라벨/필드**로 처리한다. 본문에 중복해 쓰지 않는다.
- 상위(여러 하위 이슈를 묶는) 이슈는 4번(할 일)을 하위 이슈 목록으로 갈음하고, 5번(완료 조건)은 "하위 이슈 전부 완료"로 쓴다.
- 이슈 제목은 `[범주][그룹] 무엇을 한다` 형태의 한 줄로, 요약과 어긋나지 않게 한다.

## 절차 — 새로 작성

1. **입력 수집**: 사용자가 준 설명·문서·대화에서 무엇을·왜를 뽑는다. 관련 이슈·PR이 있으면 함께 조회한다.
2. **중복 확인**: `gh issue list --search "<핵심어>" --state all`(Jira는 Atlassian MCP `searchJiraIssuesUsingJql`)로 같은 이슈가 이미 있는지 확인한다. 있으면 새로 만들지 않고 사용자에게 알린다.
3. **코드 대조**: 이슈가 가리킬 파일·함수가 실제로 있는지 확인한다. 함수명 기준으로 적는다.
4. **초안 작성**: 표준 폼에 맞춰 제목과 본문을 쓴다. 근거가 없는 항목(특히 완료 조건·범위 밖)은 만들지 않고 `(미정 — 확인 필요)`로 두고 질문 목록으로 넘긴다.
5. **사용자 확인**: 제목·본문 초안을 **먼저 보여준다.**
6. **승인 후 생성**: 사용자가 확인하면 `gh issue create --title "<제목>" --body-file <파일>`(Jira는 Atlassian MCP `createJiraIssue`)로 만들고 링크를 알려준다. 라벨·담당자·마일스톤은 사용자가 지정한 것만 붙인다.

## 절차 — 수정·업데이트

1. **원문 조회**: 정리 절차 1번과 같이 본문·댓글·연결 이슈를 조회한다.
2. **변경 내용 확인**: 사용자가 준 변경 사항이 폼의 어느 항목(요구사항, 할 일, 완료 조건, 블로커, 범위 밖 등)에 해당하는지 정한다. 근거나 대상이 불분명하면 묻는다.
3. **연쇄 영향 반영**: 한 항목을 바꾸면 함께 맞춰야 하는 항목도 고친다.
   - 요구사항이 바뀌면 할 일·완료 조건도 맞춘다.
   - 블로커가 해결되면 `- [x]`로 바꿔 뒤로 옮기고, 1번 착수 상태를 다시 판정한다.
   - 범위에서 빠진 것은 지우지 않고 7번 범위 밖으로 옮긴다.
   - 요구 출처가 새로 생기면 2번·9번·10번에 반영한다.
4. **나머지 보존**: 변경과 관계없는 문장·서식은 고치지 않는다. 폼이 크게 어긋나 있으면 수정만 하고, 전체 정리가 필요한지 따로 제안한다.
5. **변경안 확인**: 바뀌는 부분만 `이전 → 이후`로 **사용자에게 먼저 보여준다.**
6. **승인 후 반영**: 원본 본문을 스크래치패드에 백업하고 `gh issue edit <N> --body-file`(Jira는 Atlassian MCP `editJiraIssue`)로 반영한다. 제목도 바뀌어야 하면 함께 제안한다. 반영 사실은 사용자가 요청할 때만 댓글로 남긴다.

## 절차 — 기존 정리

1. **원문 조회**
   - GitHub: `gh issue view <N> --json number,title,state,body,labels,comments,url` (댓글 내용이 본문을 정정한 경우 반영 여부 확인)
   - Jira: Atlassian MCP `getJiraIssue`
   - 하위/상위 이슈, 링크된 이슈가 있으면 상태(OPEN/CLOSED, Block 여부)까지 함께 조회한다.
2. **코드 대조**: 이슈가 가리키는 파일·함수가 실제와 맞는지 확인한다. 줄 번호는 쉽게 어긋나므로 함수명 기준으로 적는다.
3. **폼 점검**: 원문이 표준 폼의 각 항목을 충족하는지 확인해 결과를 사용자에게 먼저 보여준다.
   - 항목별로 `충족` / `부분` / `누락`을 표시한다.
   - 점검 기준:
     - 요약이 한두 문장이고 착수 상태가 한 줄로 붙어 있는가
     - 왜(출처 + 이유)가 있는가
     - 요구사항이 동작(기능: 동작 → 결과 / 버그: 재현 → 현재 → 기대)으로 쓰였고 동사 + 파일·함수 단위로 쪼개져 있는가
     - 완료 조건이 체크박스이고 검증 가능한가
     - 요구사항·완료 조건의 각 항목이 **단독으로 읽혀도 대상이 분명한가** ("두 보고서", "해당 화면", "이 기능"처럼 앞에서 정의한 것을 가리키는 표현 금지 — 보고서·화면·API는 이름을 풀어 쓴다)
     - 범위 밖이 적혀 있는가
     - 기술 참고의 미확정 사항이 "제안"으로 표시되어 있는가
     - 블로커가 담당·막는 대상까지 적혀 있는가
     - 정보가 여러 섹션에 중복되거나 서로 모순되지 않는가
4. **누락 처리**: 원문에서 도출할 수 없는 항목(특히 완료 조건·범위 밖)은 **임의로 만들지 않는다.** 근거가 있는 초안만 쓰고, 근거가 없으면 `(미정 — 확인 필요)`로 두고 사용자에게 질문 목록으로 넘긴다.
5. **정리안 작성**: 폼에 맞춰 새 본문을 쓰고 **사용자에게 먼저 보여준다.**
6. **승인 후 반영**: 사용자가 확인하면 `gh issue edit <N> --body-file`(Jira는 Atlassian MCP `editJiraIssue`)로 본문을 교체한다. 반영 전에 원본 본문을 스크래치패드에 백업하고 경로를 알려준다.

## 판정 기준 (1번 착수 상태)

| 판정 | 조건 |
|---|---|
| 즉시 착수 가능 | 범위가 명확하고, 선행 항목이 없거나 모두 완료됨 |
| 선행 필요 | 선행 이슈 미완료, 개념/설계 갱신 필요, 타 팀(BE 등) 산출물 필요 |
| 착수 불가 | 외부 확정(요청 측 답변, 규격 확정)이 없으면 설계 자체가 불가능 |

- "미확인" 항목은 개발을 **막는지 / 안 막는지** 구분해 쓴다.

## 남길 것 / 줄일 것

- **근거는 반드시 남긴다.** 요구 출처는 위쪽(2번)에 요약하고, 원문·번역은 삭제하지 않고 10번에서 `<details>`로 접는다.
- 화면 캡처도 삭제하지 않고 `<details>`로 접는다.
- 줄이는 것: 섹션 간 중복 서술, 같은 내용을 롤업한 중복 표·체크리스트, 장황한 현행 설명, 버전별로 덧붙은 이력(현재 유효한 내용으로 합친다).
- 합칠 때 **담당·대상·조건 같은 세부 내용을 잃지 않는다.**
- **지시어로 줄이지 않는다.** 체크박스 한 줄만 읽어도 무엇이 어떻게 되는지 알 수 있게, 대상의 이름(보고서명, 화면명, 함수명)을 그 줄 안에 쓴다.

## 하지 말 것

- 사용자 승인 없이 이슈를 만들거나 본문을 교체하지 않는다.
- 라벨, Status, 날짜 필드, 담당자는 사용자가 지정하지 않으면 건드리지 않는다. 본문만 다룬다.
- 정리 결과를 댓글로 달지 않는다 (요청이 있을 때만).
- 원문에 없는 요구·완료 조건·문구를 만들지 않는다. UI 문구·서식은 임의로 정하지 않는다.
- **개념(conceptpowers: 코드와 개념 정의를 묶어 관리하는 플러그인. 설치된 프로젝트에만 해당) 수정·갱신·검토는 이슈에 넣지 않는다.** 할 일·완료 조건·선행 조건·착수 상태 어디에도 "개념 갱신" 항목을 쓰지 않는다. 개념과 이슈는 분리해서 관리한다. 원문에 있어도 제거한다.
- 코드를 수정하거나 구현안 설계로 넘어가지 않는다.
- 답변은 한글, 긴 문장 없이 개괄식으로 쓴다.