| name | gh-issue |
| description | area-insight 프로젝트 GitHub 이슈 생성/수정 스킬. 버그/작업/분석 리포트 유형별로 제목 태그와 본문 포맷, 그리고 "중학생도 이해할 수 있는" 글쓰기 원칙에 맞춰 작성한다. 이슈 생성, 수정, 포맷 통일 요청 시 반드시 이 스킬을 사용한다. |
/gh-issue
area-insight 프로젝트의 이슈 네이밍·본문 컨벤션 + 글쓰기 톤에 맞춰 GitHub 이슈를 생성하거나 수정한다.
절대 규칙
- 이슈는 항상 open 상태로 유지한다.
gh issue close 절대 금지.
- body는 항상 HEREDOC으로 전달한다.
- 생성 전
gh issue list --limit 10 --state all 로 최근 패턴을 재확인한다.
✍️ 글쓰기 원칙 (모든 유형 공통)
핵심 원칙: 중학생이 읽어도 이해할 수 있게 쓴다. 개발자만 아는 용어와 논리 전개를 최소화한다.
1. 한 줄로 결론부터
본문 맨 위에 "한 줄로 말하면" 또는 "TL;DR" 섹션. 의심한 것 → 진짜 결론을 한 두 문단으로 압축.
2. 이야기 흐름으로 전개
의심 → 조사 → 발견 → (반전) → 해결 → 정리 순서. 결과만 던지지 말고 추적 과정을 보여줘서 독자가 같이 따라오게.
3. 전문 용어 즉시 풀이
- ❌ "DynamoDB scan에서 prefix 필터링이 누락"
- ✅ "DB에서 데이터 가져올 때 ID 앞에 붙은 표시(
H#, D# 같은)로 거르는 단계가 빠져있음"
처음 등장하는 약어/용어는 항상 괄호로 풀어쓰기. 예: HNTRLT (주변 지역 분석용), regression (나중에 다시 잘못되는 것).
4. 표·비유 위주, 코드 블록 최소화
- 분류·비교는 표로
- 추상 개념은 비유로 ("보호막", "다른 서랍에 따로 보관")
- 코드 블록은 꼭 필요한 핵심만 (
Before/After 또는 1줄 인용)
5. 친근한 평어체
- "~합니다" 정중체 + "~음" 종결 혼용
- 의문문으로 호기심 유발: "근데 사용자한테 보이는 거 아냐?"
- 감탄/반전 표현 OK: "알고 보니 ~", "사실은 ~", "😲 진짜 좋은 상권이었음"
6. 이모지로 섹션 시각화
🔍 조사 / ⚠️ 문제 / ✅ 정상 / 🛡️ 안전장치 / 📋 정리 / 🟡 잔존이슈 / 🛠️ 재현 / 📎 참고
7. 사용자 영향 = 가장 중요
"이게 사용자 화면에 어떻게 보이나"를 항상 명시. "백엔드만 영향" / "사용자 노출 없음" / "오인 가능" 등 명확히.
제목 컨벤션
| 유형 | 완료 여부 | 제목 형식 | 예시 |
|---|
| 버그 수정 | 완료 | [BUG][수정완료] fix: 설명 | [BUG][수정완료] fix: 채팅 토큰 잘림 |
| 버그 리포트 | 미완료 | 🐛 [버그 리포트] 설명 | 🐛 [버그 리포트] 100점 상권 표시 이상 |
| 기능/개선/작업 | 완료 | [개선건][작업완료] feat/chore/refactor/개선: 설명 | [개선건][작업완료] feat: GA4 연동 |
| 기능/개선/작업 | 진행 중 | 태그 없이 설명만 | 상권 추천 알고리즘 개선 |
| 분석/조사 리포트 | 완료 | [데이터/조사] 한 줄 결론 형태로 | [데이터 품질] 건강점수 점검 — 데이터는 멀쩡, 등급 기준만 잘못 |
팁: 분석 리포트 제목은 결론을 미리 보여주기. 독자가 제목만 봐도 "아 별일 아니구나" 또는 "큰일이구나" 느낌이 와야 함.
본문 포맷 — 버그 이슈 [BUG]
버그 1개당 아래 블록을 반복한다. 여러 버그가 있으면 ---로 구분한다.
### [prefix-NNNN] 버그 제목
**파일**: `경로/파일명.js:라인번호`
**무슨 일이 일어나나?**
개발자가 아닌 팀원도 이해할 수 있는 평이한 언어로 설명한다.
실제로 무엇이 잘못 표시되거나 동작하는지, 사용자 관점에서 서술한다.
**원인**
기술적 원인. 핵심 코드 스니펫을 Before 형태로 포함한다.
```js
// Before
문제가 되는 코드
영향
이 버그로 인한 실제 피해 (데이터 오표시, 비용 낭비, UX 손상 등).
수정 방법
어떻게 고쳤는지 설명한다.
✅ 수정 완료 (커밋해시)
수정된 코드
**prefix 규칙**: `backend`, `ui`, `chat`, `ai`, `infra` 중 해당하는 것.
**NNNN**: 이슈 내 순번 (0001부터).
---
## 본문 포맷 — 작업/개선 이슈 `[개선건]`
```markdown
## 배경
왜 이 작업이 필요했는지. 해결하려는 문제 또는 도입 동기를 명확히 서술한다.
---
## 변경 내용
| 파일 | 변경 |
|------|------|
| `경로/파일명.js` | 무엇을 바꿨는지 |
핵심 변경사항은 Before/After 코드로 보여준다.
```js
// Before
기존 코드
// After
변경된 코드
개선 효과
- 측정 가능한 수치로 표현한다 (예: "탐색 비용 89% 감소", "월 $1.60 → $0")
- 정량화가 어려우면 "무엇이 가능해졌는지"로 서술한다
커밋
해시 — 커밋 메시지
---
## 본문 포맷 — 분석/조사 리포트 (데이터 품질, 전수조사, 원인 추적 등)
**참고 사례**: [#179](https://github.com/kangraemin/area-insight/issues/179)
```markdown
# 🔍 [한 문장 결론형 제목]
## 한 줄로 말하면
**[가장 중요한 결론 한 문장]**. 처음엔 "[의심 1]?", "[의심 2]?" 의심했는데, 알고 보니:
- [실제 결론 1]
- [실제 결론 2]
- [실제 결론 3]
진짜 [고쳐야 할 것 / 발견한 것]은 **[핵심 한 가지]**였고, [상태: 이미 고쳤습니다 / 추가 작업 필요].
---
## 처음 의심한 것
[화면/사용자 관점에서] 보면:
1. [의심 현상 1] — "[독자 시점 의문]?"
2. [의심 현상 2] — "[독자 시점 의문]?"
→ [어떻게 조사했는지 한 줄].
---
## 조사 결과 — N가지 그룹 (또는 분류)
[전체 데이터/현상]을 [기준]으로 나눠봄:
| 그룹 | 개수 | 상태 |
|------|------|------|
| [그룹 1] | N개 | ✅/⚠️/❌ [상태 한 줄] |
| [그룹 2] | N개 | ✅/⚠️/❌ [상태 한 줄] |
### 😲 / 🤔 / ⚠️ [그룹 1 상세] — [반전/발견]
[독자가 놀랄/이해할 핵심 내용. 비유와 표 위주]
[필요하면 검증 데이터 표]
| 항목 | 값 1 | 값 2 |
|------|------|------|
| 샘플 1 | ... | ... |
[코드는 꼭 필요한 핵심만]
```js
// 1~3줄 핵심 인용 + 한 줄 주석 설명
🤔 [그룹 2 상세] — [의문 → 해소]
[같은 패턴]
⚠️ 진짜 문제는 따로 있었음 — [실제 발견 이슈]
[조사 끝에 발견한 진짜 이슈를 별도 섹션으로]
[현재 상태와 분포 / 구체 수치]
해결: [한 줄 요약]
🛡️ 안전장치도 같이 추가 (있으면)
[직접 버그 수정은 아니지만 미래 방어 차원의 변경 설명]
직접적인 버그 수정은 아니지만, [방어 효과].
📋 정리 — 뭘 고쳤나
| 항목 | 상태 |
|---|
| [수정 1] | ✅ 고쳤음 |
| [수정 2] | ✅ 추가했음 |
| [원래 정상이었던 것] | ⚪ 안 건드림 — [이유] |
→ 적용 커밋: [해시](commit url)
🟡 나중에 추가로 봐야 할 것 (이번 작업 범위 밖)
1. [잔존 의심점 1]
[설명. "사용자 화면엔 영향 없지만 ~할 수 있음" 형태로 영향 범위 명시]
2. [잔존 의심점 2]
[설명]
→ 별도 작업으로 분리 권장.
🛠️ 직접 확인하고 싶다면 (재현 명령어)
[명령어]
[명령어]
📎 참고 링크
### 분석 리포트 작성 시 체크리스트
- [ ] 한 줄 요약이 제목/맨 위에 있는가?
- [ ] 의심 → 조사 → 발견 → 해결 흐름인가?
- [ ] 표가 코드보다 많은가?
- [ ] 처음 등장한 전문 용어를 즉시 풀어 썼는가?
- [ ] 사용자 영향(노출 여부)을 명시했는가?
- [ ] 잔존 의심점을 별도 섹션으로 빼서 후속 추적용으로 남겼는가?
- [ ] 재현 명령어가 있는가?
---
## 플로우
1. args에서 이슈 유형(버그/작업/분석) 및 내용 파악
2. `gh issue list --limit 10 --state all` 로 최근 제목 패턴 확인
3. 유형에 맞는 제목 태그 + 본문 포맷 결정
4. **글쓰기 원칙 7개 적용** (특히 한 줄 요약, 표 위주, 전문 용어 풀이)
5. body 작성 후 작성 체크리스트 검증
6. `gh issue create --title "..." --body "$(cat <<'EOF' ... EOF)"` 실행
7. 생성된 URL 출력
이슈 **수정** 요청이면 `gh issue edit <number> --title "..." --body "..."` 사용.
