issue

name	issue
description	대화 맥락이나 요구사항을 기반으로 프로젝트 이슈 템플릿(`.github/ISSUE_TEMPLATE/*` 자동 감지, 없으면 기본 구조)에 맞춘 GitHub 이슈 마크다운을 생성합니다.
when_to_use	이슈 만들어줘, GitHub 이슈 초안, 이슈로 등록할 내용 정리. PR 본문은 pr.
allowed-tools	Read, Write, Glob, Grep, Bash

외부-가시 문서: rules/external-doc.md 10원칙 준수. 이슈는 담당자, 파트너, 고객 참조 전제. 받는 쪽이 못 여는 내부 경로와 상수명 금지(같은 리포지토리의 코드 경로, PR/이슈 번호, 공개 URL은 허용), What > How, 정량과 절대 표기.

역할

대화 맥락, 요구사항, CS 분석 결과 등을 기반으로 프로젝트 이슈 템플릿(있을 시 .github/ISSUE_TEMPLATE/*, 없으면 기본 구조)에 맞춘 GitHub 이슈 제목과 본문을 마크다운으로 생성합니다.

출력만 합니다. 이슈를 직접 생성하지 않습니다.

다른 스킬과의 경계

질문	담당	이 스킬에서
완료된 브랜치 변경을 PR 본문으로 작성	/pr	[FAIL] 다루지 않음
고객 문의와 CS 접수 내용 분석	/cs	[FAIL] 다루지 않음 (CS 분석 결과를 이슈로는 변환)
개인 작업 할 일 분해와 관리	/todo	[FAIL] 다루지 않음 (TODO 목록을 이슈 체크리스트로는 참조)
요구사항, CS, 아이디어를 GitHub 이슈 본문으로 작성	이 스킬	[OK] 핵심

외부 데이터 의존

데이터	경로	필수/선택	부재 시 동작
프로젝트 컨텍스트	CLAUDE.md	선택	일반 가정으로 진행, [프로젝트 규칙 미확인] 태그
봇 인덱스	bot/INDEX.md 또는 .local.claude/ONBOARDING.md	선택	디렉터리 Glob 으로 fallback
비즈니스 규칙	.local.claude/biz-rules.md	선택	일반 SW 관점으로만 진행 (Tier 1)
모듈 상세	.local.claude/modules/{name}.md	선택	코드 Grep 직접 fallback
PR 템플릿	.github/PULL_REQUEST_TEMPLATE.md, .github/ISSUE_TEMPLATE/*	선택	일반 GitHub 이슈 형식으로 생성, 프로젝트별 템플릿 미반영
team 정보	.local.claude/team.md	선택	담당자 자동 할당 생략, 사용자에게 질문
고객 프로필	.local.claude/customers/*.md	선택	B2B 맥락 부재, 고객사명 사용자 지정

레포지토리 정보

GitHub owner/repo 는 프로젝트 컨텍스트에서 추출:

• git remote -v 로 remote URL 을 확인해 owner/repo 추출
• 추출 불가 시 사용자에게 확인 요청

입력

$ARGUMENTS로 이슈 내용이나 파일 경로를 받는다. 없으면 대화 맥락에서 이슈 내용을 추출하거나, 직접 입력을 요청한다.

스타일 참고

[1M 활용] 다음을 단일 메시지에서 병렬 호출:

• GitHub MCP: mcp__github__list_issues (최근 이슈 3~5개)
• Read: .github/ISSUE_TEMPLATE/*.md, CLAUDE.md, .local.claude/team.md
• Grep: 입력에서 언급된 모듈과 기능을 .local.claude/modules/*.md에서 매칭

GitHub MCP mcp__github__list_issues로 최근 이슈 3~5개를 읽어 팀의 실제 작성 스타일(제목 형식, 본문 상세 수준, 라벨 사용)을 확인한다.

이슈 유형 판단

입력 내용에서 자동 판단하거나, 애매하면 질문:

유형	판단 기준	제목 접두사	라벨
기능 개발	새 기능 추가	[신규 기능 개발]	신규기능개발
기능 수정	기존 기능 개선/변경	[기능 수정]	개선
버그	오류, 장애, 안 됨	[BUG]	버그
퍼블리싱	UI/스타일 변경	[퍼블리싱]	퍼블리싱
기타	설정, 빌드, 라이브러리 등	(없음)	기타

이슈 템플릿

기능 개발

## 이슈 제목
[신규 기능 개발] 기능명

## 이슈 본문

## 1. 기능 설명

기능에 대한 설명.

---

## 2. 주요 작업 내용

- [ ] 작업1
- [ ] 작업2
- [ ] 작업3
- [ ] 테스트

---

## 3. 참고 자료 (선택)

### 파일
> 필요한 경우 파일을 첨부해주세요.

### 링크
> 관련 링크

---

## 4. 영향 범위 (선택)
- [ ] API 변경
- [ ] DB 스키마 변경
- [ ] 기존 기능 영향 있음

기능 수정

## 이슈 제목
[기능 수정] 기능명

## 이슈 본문

## 1. 개선 대상
어떤 기능을 개선하는지.

---

## 2. 개선 방향
어떤 방식으로 개선하는지.

---

## 3. 작업 내용
- [ ] 원인 분석
- [ ] 개선 작업
- [ ] 테스트

버그

## 이슈 제목
[BUG] 증상 요약

## 이슈 본문

## 1. 문제 상황
문제 설명.

---

## 2. 재현 방법
1. 단계1
2. 단계2
3. 단계3

---

## 3. 기대 결과
정상 동작 설명.

---

## 4. 실제 결과
실제 발생한 결과.

---

## 5. 환경 정보 (선택)
- OS:
- 브라우저:
- 고객사:

---

## 6. 추가 정보 (선택)
로그, 스크린샷 등

퍼블리싱

## 이슈 제목
[퍼블리싱] 작업 요약

## 이슈 본문

## 1. 작업 내용
- [ ] 작업1
- [ ] 작업2

---

## 2. 변경 사항
- 변경1
- 변경2

---

## 3. 개발 전달 사항 (선택)
- 전달사항

기타

## 이슈 제목
작업 요약

## 이슈 본문

## 1. 작업 내용
수행하려는 작업 설명.

---

## 2. 작업 목적
필요한 이유.

---

## 3. 작업 목록
- [ ] 작업1
- [ ] 작업2
- [ ] 테스트

---

## 4. 참고 자료 (선택)
관련 문서 또는 링크

---

## 5. 영향 범위 (선택)
- [ ] 빌드 설정 변경
- [ ] 라이브러리 변경
- [ ] 환경 설정 변경

작성 규칙

외부-가시 문서 공통 원칙 준수: rules/external-doc.md (가독성 5 + 정직성 5 원칙). 아래는 이슈 고유 가이드.

톤 & 수준

• 외부 공개 톤: GitHub 이슈는 팀 외부에도 보일 수 있음. 내부 분석 라벨, 담당자 목록, 내부 문서 경로(.local.claude/...) 나열 금지. 사실 기반 간결 표현만
• 구현 세부는 이슈에 넣지 않음: 함수명, 파일 경로, 코드 스니펫은 PR 레벨에서 다룸. 이슈는 목표 + 체크리스트
• 증거는 스크린샷: 검증 결과를 글로 나열하지 말고 동작 스크린샷 이미지를 첨부. 한 장이 문서 경로 10줄보다 설득력 높음
• 외부 의사결정은 이슈 체크리스트에서 제외: 영업 통화, 라이선스 만료 등 개발 외 항목은 별도 트래킹. 체크리스트는 개발 작업 중심
• 옵션은 꼭 필요한 것만: 발생 가능성 낮은 옵션은 제거. 간결 > 완전

제목

• 템플릿 접두사 + 구체적 내용
• 예: [신규 기능 개발] {모듈} {기능명}
• 예: [BUG] {기능명} {증상} ({고객사})

작업 내용

• 대화 맥락에서 구체적 작업을 추출하여 체크리스트 형태로
• /todo 스킬에서 만든 TODO가 있으면 그 목록을 참조
• /cs 스킬에서 분석한 결과가 있으면 원인/수정 내용 반영

영향 범위

• 코드베이스의 modules/{name}.md를 참조하여 관련 모듈/테이블 명시

다이어그램 (선택)

기능 개발과 기능 수정 이슈에서 아키텍처나 흐름 설명이 필요하면 mermaid 다이어그램 포함. 버그, 퍼블리싱, 기타 유형에서는 생략.

• flowchart: 모듈 간 데이터 흐름, 처리 순서
• sequenceDiagram: API 요청 흐름
• stateDiagram-v2: 상태 전이 설명
• 간결하게 (노드 5개 이하)
• ## 1. 기능 설명 또는 ## 2. 주요 작업 내용 섹션에 배치
• TO-BE(해결안)를 AS-IS(현재)보다 먼저 배치: 읽는 사람이 "뭘 하겠다"를 먼저 봄

스킬 간 연결

• /prd 다음에 /issue (기능 개발 이슈)
• /cs 다음에 /issue (버그 이슈)
• /brainstorm 다음에 /issue (기능 수정 이슈)

파일 저장

Frontmatter (CONTRACT 7-2절 표준): category: issues, retention: 30d

이슈 마크다운을 화면 출력과 동시에 파일로 저장한다.

저장 경로

• .local.claude/issues/YYYY-MM-DD-{제목접두사}-{간략설명}.md
• 예: YYYY-MM-DD-신규기능개발-{기능명}.md
• 예: 2026-04-02-BUG-프로젝트목록빈화면.md
• 디렉터리 없으면 mkdir -p로 생성

저장 시점

• 이슈 마크다운 생성 완료 시 자동 저장
• 저장 후 파일 경로 안내

출력

[메타인지] 출력 전 자기 검증 (external-doc 10원칙):

1. 근거 재점검: 증상, 재현 단계, 기대/실제 결과가 사실 기반인가? 추측은 [추정] 태그로 구분했는가?
2. 전제 검증: 내부 경로, 담당자 목록, 내부 분석 라벨이 본문에 섞이지 않았는가?
3. 반대 증거: "담당자가 이 이슈만 보고 작업 착수할 수 있는가?" 자기 완결성 반박 1개 이상

화면에 제목과 본문을 분리하여 출력 (사용자가 복사하여 GitHub에 붙여넣기) + 파일로 저장.

사용자가 원하면 GitHub MCP (mcp__github__issue_write)로 이슈를 직접 생성할 수도 있다고 안내. 단, 직접 생성은 사용자가 명시적으로 요청한 경우에만.

제약조건

• 외부-가시 문서 공통 원칙 준수: rules/external-doc.md (가독성 5 + 정직성 5). 이슈는 담당자, 파트너, 고객이 참조. 원칙 재진술은 해당 문서 참조.
• 출력만 한다. 사용자가 명시적으로 요청하지 않으면 이슈 생성 금지.
• 이슈는 목표 + 체크리스트 중심. 함수명, 파일 경로, 코드 스니펫 등 구현 세부는 PR 레벨로 미룸.
• 내부 경로(.local.claude/*), 내부 분석 라벨, 담당자 목록을 본문에 나열 금지.
• 증상, 재현 단계, 기대/실제 결과는 사실 기반. 추측은 [추정] 태그로 구분.
• 영업 통화, 라이선스 만료 등 개발 외 항목은 체크리스트에서 제외하고 별도 트래킹.

검증 시나리오

공통 3블록(빈 / 부분 / 풀 데이터)은 CONTRACT 6-1절 참조.

이 스킬의 고유 실패 시나리오

[의존성 부재] .github/ISSUE_TEMPLATE/ 부재

• 신호: 저장소에 이슈 템플릿이 없거나 타입별 템플릿 구분이 없음
• 대응: 기본 구조(제목/배경/재현 단계/기대 동작/환경) 사용 + "팀 표준 템플릿 추가 권장" 안내

[사용자 개입 필요] 유형 판단 모호 (기능 요청 / 버그 / 질문 / 기타)

• 신호: 입력에 재현 단계, 기대 동작, 요구사항 중 2개 이상 누락으로 자동 분류 불가
• 대응: AskUserQuestion 으로 4가지 유형 중 선택 요청 + 각 유형별 필수 필드 체크리스트 안내