Gh Issue

/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]

버그 1개당 아래 블록을 반복한다. 여러 버그가 있으면 ---로 구분한다.

### [prefix-NNNN] 버그 제목

**파일**: `경로/파일명.js:라인번호`

**무슨 일이 일어나나?**
개발자가 아닌 팀원도 이해할 수 있는 평이한 언어로 설명한다.
실제로 무엇이 잘못 표시되거나 동작하는지, 사용자 관점에서 서술한다.

**원인**
기술적 원인. 핵심 코드 스니펫을 Before 형태로 포함한다.

```js
// Before
문제가 되는 코드

영향 이 버그로 인한 실제 피해 (데이터 오표시, 비용 낭비, UX 손상 등).

수정 방법 어떻게 고쳤는지 설명한다.

✅ 수정 완료 (커밋해시)

// After
수정된 코드

**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]

🛡️ 안전장치도 같이 추가 (있으면)

[직접 버그 수정은 아니지만 미래 방어 차원의 변경 설명]

// 핵심 코드 1~5줄

직접적인 버그 수정은 아니지만, [방어 효과].

📋 정리 — 뭘 고쳤나

→ 적용 커밋: [해시](commit url)

🟡 나중에 추가로 봐야 할 것 (이번 작업 범위 밖)

1. [잔존 의심점 1]

[설명. "사용자 화면엔 영향 없지만 ~할 수 있음" 형태로 영향 범위 명시]

2. [잔존 의심점 2]

[설명]

→ 별도 작업으로 분리 권장.

🛠️ 직접 확인하고 싶다면 (재현 명령어)

# 1. [무엇을 확인]
[명령어]
# → [기대 결과]

# 2. [무엇을 확인]
[명령어]

📎 참고 링크

• 적용 커밋: 해시
• 추적 과정 (기술적 디테일): 코멘트/PR

### 분석 리포트 작성 시 체크리스트

- [ ] 한 줄 요약이 제목/맨 위에 있는가?
- [ ] 의심 → 조사 → 발견 → 해결 흐름인가?
- [ ] 표가 코드보다 많은가?
- [ ] 처음 등장한 전문 용어를 즉시 풀어 썼는가?
- [ ] 사용자 영향(노출 여부)을 명시했는가?
- [ ] 잔존 의심점을 별도 섹션으로 빼서 후속 추적용으로 남겼는가?
- [ ] 재현 명령어가 있는가?

---

## 플로우

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 "..."` 사용.