القائمة
area-insight 프로젝트 GitHub 이슈 생성/수정 스킬. 버그/작업/분석 리포트 유형별로 제목 태그와 본문 포맷, 그리고 "중학생도 이해할 수 있는" 글쓰기 원칙에 맞춰 작성한다. 이슈 생성, 수정, 포맷 통일 요청 시 반드시 이 스킬을 사용한다.
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/kangraemin/claude-config --skill gh-issueيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| name | gh-issue |
| description | area-insight 프로젝트 GitHub 이슈 생성/수정 스킬. 버그/작업/분석 리포트 유형별로 제목 태그와 본문 포맷, 그리고 "중학생도 이해할 수 있는" 글쓰기 원칙에 맞춰 작성한다. 이슈 생성, 수정, 포맷 통일 요청 시 반드시 이 스킬을 사용한다. |
area-insight 프로젝트의 이슈 네이밍·본문 컨벤션 + 글쓰기 톤에 맞춰 GitHub 이슈를 생성하거나 수정한다.
gh issue close 절대 금지.gh issue list --limit 10 --state all 로 최근 패턴을 재확인한다.핵심 원칙: 중학생이 읽어도 이해할 수 있게 쓴다. 개발자만 아는 용어와 논리 전개를 최소화한다.
본문 맨 위에 "한 줄로 말하면" 또는 "TL;DR" 섹션. 의심한 것 → 진짜 결론을 한 두 문단으로 압축.
의심 → 조사 → 발견 → (반전) → 해결 → 정리 순서. 결과만 던지지 말고 추적 과정을 보여줘서 독자가 같이 따라오게.
H#, D# 같은)로 거르는 단계가 빠져있음"처음 등장하는 약어/용어는 항상 괄호로 풀어쓰기. 예: HNTRLT (주변 지역 분석용), regression (나중에 다시 잘못되는 것).
Before/After 또는 1줄 인용)🔍 조사 / ⚠️ 문제 / ✅ 정상 / 🛡️ 안전장치 / 📋 정리 / 🟡 잔존이슈 / 🛠️ 재현 / 📎 참고
"이게 사용자 화면에 어떻게 보이나"를 항상 명시. "백엔드만 영향" / "사용자 노출 없음" / "오인 가능" 등 명확히.
| 유형 | 완료 여부 | 제목 형식 | 예시 |
|---|---|---|---|
| 버그 수정 | 완료 | [BUG][수정완료] fix: 설명 | [BUG][수정완료] fix: 채팅 토큰 잘림 |
| 버그 리포트 | 미완료 | 🐛 [버그 리포트] 설명 | 🐛 [버그 리포트] 100점 상권 표시 이상 |
| 기능/개선/작업 | 완료 | [개선건][작업완료] feat/chore/refactor/개선: 설명 | [개선건][작업완료] feat: GA4 연동 |
| 기능/개선/작업 | 진행 중 | 태그 없이 설명만 | 상권 추천 알고리즘 개선 |
| 분석/조사 리포트 | 완료 | [데이터/조사] 한 줄 결론 형태로 | [데이터 품질] 건강점수 점검 — 데이터는 멀쩡, 등급 기준만 잘못 |
팁: 분석 리포트 제목은 결론을 미리 보여주기. 독자가 제목만 봐도 "아 별일 아니구나" 또는 "큰일이구나" 느낌이 와야 함.
[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
변경된 코드
해시 — 커밋 메시지
---
## 본문 포맷 — 분석/조사 리포트 (데이터 품질, 전수조사, 원인 추적 등)
**참고 사례**: [#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줄 핵심 인용 + 한 줄 주석 설명
[같은 패턴]
[조사 끝에 발견한 진짜 이슈를 별도 섹션으로]
[현재 상태와 분포 / 구체 수치]
[직접 버그 수정은 아니지만 미래 방어 차원의 변경 설명]
// 핵심 코드 1~5줄
직접적인 버그 수정은 아니지만, [방어 효과].
| 항목 | 상태 |
|---|---|
| [수정 1] | ✅ 고쳤음 |
| [수정 2] | ✅ 추가했음 |
| [원래 정상이었던 것] | ⚪ 안 건드림 — [이유] |
→ 적용 커밋: [해시](commit url)
[설명. "사용자 화면엔 영향 없지만 ~할 수 있음" 형태로 영향 범위 명시]
[설명]
→ 별도 작업으로 분리 권장.
# 1. [무엇을 확인]
[명령어]
# → [기대 결과]
# 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 "..."` 사용.