GitHub 이슈 작성 템플릿 모음 v1.0.0

개요

GitHub 이슈를 일관되고 명확하게 작성하기 위한 라벨별 구조화된 템플릿입니다.

각 라벨에 맞는 템플릿을 사용하면:

• ✅ 명확성: 이슈 내용이 명확하고 구조화됨
• ✅ 효율성: 누락된 정보가 줄어듦
• ✅ 일관성: 팀 전체의 이슈 형식이 통일됨
• ✅ 추적성: 모든 중요 정보가 기록됨

---

🐛 버그 리포트 템플릿

언제 사용?

• 예상하지 못한 동작이나 오류 발생
• 기능이 정상적으로 작동하지 않음
• 성능 저하 또는 비정상적인 동작

템플릿

## 버그 설명

[버그가 무엇인지 간단하게 설명하세요]

## 재현 단계

1. [첫 번째 단계]
2. [두 번째 단계]
3. [버그 발생하는 단계]

## 예상 동작

[정상적으로 동작해야 하는 내용 설명]

## 실제 동작

[실제로 일어나는 내용 설명]

## 환경 정보

- MoAI-ADK 버전: [버전]
- Python 버전: [버전]
- OS: [Windows/macOS/Linux]
- 브라우저: [선택사항]

## 추가 정보

[스크린샷, 에러 메시지, 로그 등]

예시

## 버그 설명

/alfred:1-plan 명령어 실행 시 스펙 생성이 안 됩니다.

## 재현 단계

1. `/alfred:1-plan "새로운 기능 추가"` 명령 실행
2. 단계 1~4를 모두 진행
3. 최종 확인 후 생성 버튼 클릭

## 예상 동작

새로운 SPEC 문서가 .moai/specs/SPEC-XXX/ 폴더에 생성되어야 함

## 실제 동작

"스펙 생성 실패" 에러 메시지만 출력되고 폴더 생성 안 됨

## 환경 정보

- MoAI-ADK 버전: 0.22.5
- Python 버전: 3.11.5
- OS: macOS 14.2

---

✨ 기능 요청 템플릿

언제 사용?

• 새로운 기능이 필요함
• 기존 기능의 개선 방안을 제안하고 싶음
• 새로운 명령어나 도구 추가를 요청

템플릿

## 기능 설명

[어떤 기능이 필요한지 설명하세요]

## 사용 시나리오

[이 기능이 언제/어떻게 사용될지 설명하세요]

예: 사용자가 X를 하려고 할 때, Y 기능이 있으면 Z를 쉽게 할 수 있습니다.

## 기대 효과

- [효과 1]
- [효과 2]
- [효과 3]

## 구현 아이디어 (선택사항)

[이 기능을 어떻게 구현할 수 있을지 아이디어가 있으면 제시하세요]

## 우선순위

- 🔴 긴급: 즉시 필요
- 🟠 높음: 곧 필요
- 🟡 중간: 적당히 필요 (기본값)
- 🟢 낮음: 나중에 괜찮음

예시

## 기능 설명

/alfred:9-feedback 명령어에 자동 정보 수집 기능이 필요합니다.
버그 리포트 시 환경 정보(버전, OS, Git 상태)를 자동으로 수집하면 좋을 것 같습니다.

## 사용 시나리오

버그를 발견한 사용자가 /alfred:9-feedback을 실행하면,
자동으로 MoAI-ADK 버전, Python 버전, 현재 Git 상태, 최근 에러 로그를 수집해서
이슈 본문에 포함시켜줍니다.

## 기대 효과

- 버그 리포팅 시간 단축 (수동 입력 제거)
- 환경 정보 누락 방지
- 버그 분석 시 필요한 정보를 처음부터 갖춤

---

⚡ 개선 사항 템플릿

언제 사용?

• 코드 품질 개선 제안
• 성능 최적화 아이디어
• 사용자 경험(UX) 개선
• 문서화 개선

템플릿

## 개선 내용

[무엇을 개선하고 싶은지 설명하세요]

## 현재 상태

[현재 어떻게 되어 있는지 설명하세요]

## 개선 후 상태

[개선되면 어떻게 달라질지 설명하세요]

## 성능/품질 영향

- 성능: [향상도, 예: 응답 시간 50% 단축]
- 사용성: [개선도, 예: 단계 2단계 감소]
- 유지보수성: [효과, 예: 코드 복잡도 30% 감소]

## 구현 복잡도

- ⚪ 낮음: 1-2시간
- 🟡 중간: 반나절
- 🔴 높음: 1일 이상

예시

## 개선 내용

AskUserQuestion의 단계를 줄여서 사용 편의성 개선

## 현재 상태

/alfred:9-feedback 실행 시 4단계 질문 (이슈 타입 → 제목 → 설명 → 우선순위)

## 개선 후 상태

1단계로 통합: 한 번에 필수 정보(타입, 우선순위) + 자동 템플릿 생성

## 성능/품질 영향

- 사용성: 4단계 → 1-2단계 (50% 단축)
- 시간: ~90초 → ~30초 (67% 단축)

---

🔄 리팩토링 템플릿

언제 사용?

• 기존 코드 재구성
• 설계 패턴 개선
• 기술 부채 해결
• 모듈 분리 또는 통합

템플릿

## 리팩토링 범위

[어떤 부분을 리팩토링할지 명확히 하세요]

예: src/moai_adk/core/template_engine.py 의 Template 클래스

## 현재 구조

[현재 코드의 구조나 문제점]

## 개선된 구조

[리팩토링 후 어떻게 바뀔지]

## 개선 이유

- [이유 1]
- [이유 2]
- [이유 3]

## 영향 분석

- 변경되는 모듈: [모듈 목록]
- 영향받는 테스트: [테스트 목록]
- 호환성: [호환성 유지 여부]

예시

## 리팩토링 범위

.claude/commands/alfred/ 의 명령어 파일들의 frontmatter 통일

## 현재 구조

각 명령어마다 frontmatter 형식이 다름:
- allowed-tools 리스트 형식 다름
- skills 섹션 있는 파일/없는 파일 혼재

## 개선된 구조

모든 명령어가 동일한 frontmatter 표준:

---

name: alfred:X allowed-tools: [...] skills: [...]

## 개선 이유

- 일관성: frontmatter 형식 통일
- 유지보수성: 스킬 추가/제거 명확화
- 자동화: 파싱 스크립트 단순화

---

📚 문서 템플릿

언제 사용?

• README, CLAUDE.md 같은 문서 개선
• 새로운 가이드/튜토리얼 작성
• 기존 문서의 명확성 개선
• 코드 주석/docstring 개선

템플릿

## 문서 내용

[무엇에 대한 문서인지 설명하세요]

## 대상 독자

[이 문서를 읽을 주요 독자는 누구인가요?]

예: 새 개발자, 팀 리더, API 사용자

## 문서 구조

[문서의 구조를 스케치하세요]

예:
1. 개요
2. 설치/설정
3. 사용법
4. FAQ
5. 참고자료

## 포함할 내용

- [내용 1]
- [내용 2]
- [내용 3]

## 관련 문서

[참고할 기존 문서들]

예시

## 문서 내용

/alfred:9-feedback 사용 가이드

## 대상 독자

MoAI-ADK 개발자, 버그/기능 리포팅이 처음인 팀원

## 문서 구조

1. 소개 (무엇인가)
2. 단계별 사용법 (어떻게 사용)
3. 라벨 설명 (어떤 라벨 사용)
4. 팁과 주의사항
5. FAQ

## 포함할 내용

- 명령어 실행 방법
- 각 단계별 화면
- 라벨 선택 가이드
- 환경 정보 자동 수집 설명

---

❓ 질문/토론 템플릿

언제 사용?

• 팀에게 물어볼 질문
• 의사결정이 필요한 사안
• 기술적 고민이나 제안

템플릿

## 배경

[이 질문/논의의 배경을 설명하세요]

## 질문 또는 제안

[핵심 질문을 명확하게 제시하세요]

## 선택지

- [ ] 선택지 1
- [ ] 선택지 2
- [ ] 선택지 3
- [ ] 기타

## 의사결정 기준

[어떤 기준으로 결정할지 설명하세요]

예: 개발 시간, 성능 영향, 팀 학습 곡선 등

## 추가 정보

[관련된 추가 정보나 참고자료]

예시

## 배경

/alfred:9-feedback의 AskUserQuestion 디자인 개선을 검토중입니다.
현재 4단계 질문이 많다는 피드백을 받았습니다.

## 질문 또는 제안

단계를 줄이기 위해 다음 중 어떤 방식이 좋을까요?

## 선택지

- [ ] multiSelect로 한 번에 필수 정보 수집 후 자동 템플릿 생성
- [ ] 기본값 최대화 (우선순위 기본값 medium, 설명 선택사항)
- [ ] Step 1에서 요약 정보만, Step 2에서 자세한 입력 받기
- [ ] 스크립트로 cli 형태로 변경 (예: `alfred:9-feedback bug "제목" -d "설명"`)

## 의사결정 기준

- 사용 편의성 (단계 최소화)
- 정보 수집 정확성 (필수 정보 누락 방지)
- 한국어 지원 일관성

---

📊 템플릿 비교

라벨	핵심 요소	최소 필드	추가 정보
bug	재현 단계, 예상 vs 실제	설명, 환경	스크린샷, 로그
feature	시나리오, 효과	설명, 사용 경우	구현 아이디어
improvement	개선 전후, 이유	설명, 기대 효과	복잡도, 영향도
refactor	범위, 이유	현재 vs 개선	영향 분석
docs	대상 독자, 구조	내용 개요	포함 항목 목록
question	배경, 선택지	기준	관련 정보

---

🎯 템플릿 활용 팁

DO ✅

• ✅ 템플릿의 모든 섹션을 채우세요
• ✅ 구체적이고 상세하게 작성하세요
• ✅ 환경/버전 정보를 정확하게 입력하세요
• ✅ 재현 단계를 단계별로 명확하게 기술하세요
• ✅ 스크린샷이나 에러 메시지를 첨부하세요

DON'T ❌

• ❌ 템플릿의 섹션을 건너뛰지 마세요
• ❌ "작동 안 함" 같은 모호한 설명을 하지 마세요
• ❌ 환경 정보를 생략하지 마세요
• ❌ 여러 문제를 한 이슈에 섞지 마세요

---

🔗 참고

• 명령어:

  /alfred:9-feedback

• 라벨 분류법:

  Skill("moai-alfred-issue-labels")

• 이전 버전: v0.22.5+부터 지원

---

Last Updated: 2025-11-12 Status: Production Ready (v1.0.0) Language: Korean (한국어)