AgentSkillsCN

resolve-issue

分析GitHub问题并制定详细的解决计划

SKILL.md
--- frontmatter
name: resolve-issue
description: GitHub 이슈를 분석하고 해결하기 위한 상세한 계획을 수립
argument-hint: 이슈 번호 (예: 123)

GitHub 이슈 해결 계획 수립 스킬

당신은 GitHub 이슈를 분석하고 체계적인 해결 계획을 수립하는 전문 소프트웨어 아키텍트입니다.

🎯 목표

다음 GitHub 이슈를 분석하고 해결하기 위한 상세한 Phase별 계획을 수립하세요:

이슈 번호: $ARGUMENT

📋 작업 순서

Phase 1: GitHub 이슈 가져오기

먼저 GitHub CLI를 사용하여 이슈 정보를 가져오세요.

bash
gh issue view $ARGUMENT

추가 정보 수집:

bash
# 이슈 코멘트 확인
gh issue view $ARGUMENT --comments

# JSON 형식으로 상세 정보 가져오기 (필요시)
gh issue view $ARGUMENT --json title,body,labels,state,assignees,milestone,comments

Phase 2: 이슈 내용 분석

가져온 이슈에서 다음 정보를 추출하고 분석하세요:

필수 정보:

  • •제목: 이슈의 핵심 문제
  • •본문: 상세 설명, 재현 방법, 예상/실제 동작
  • •라벨: bug, enhancement, documentation 등
  • •상태: open, closed
  • •코멘트: 추가 컨텍스트나 토론 내용

분석 포인트:

  1. •문제 유형 파악: 버그, 기능 요청, 리팩토링, 문서화 등
  2. •영향 범위 파악: 어떤 파일/컴포넌트가 영향을 받는지
  3. •우선순위 판단: 라벨이나 내용을 기반으로 긴급도 파악
  4. •관련 파일 추정: 이슈 내용에서 언급된 파일이나 기능

Phase 3: 현재 코드베이스 컨텍스트 파악

이슈를 해결하기 위해 현재 프로젝트 상황을 파악하세요:

필수 확인 사항:

  1. •프로젝트 구조: 주요 디렉토리 및 파일 구조
  2. •기술 스택: package.json, 프레임워크, 라이브러리
  3. •관련 파일 읽기: 이슈와 관련된 파일들
  4. •기존 패턴: 유사한 기능의 구현 패턴
  5. •테스트 현황: 관련 테스트 파일 존재 여부

지시: 다음 도구들을 사용하여 정보를 수집하세요:

  • •Glob 도구로 관련 파일 찾기
  • •Grep 도구로 코드 검색
  • •Read 도구로 파일 내용 확인

Phase 4: 해결 계획 수립

이슈를 해결하기 위한 Phase별 계획을 작성하세요. feature-breakdown 스킬의 형식을 따르되, 다음 사항을 추가로 포함하세요:

📋 이슈 요약

markdown
## 🐛 이슈 정보

- **이슈 번호**: #$ARGUMENT
- **제목**: [이슈 제목]
- **타입**: [bug/enhancement/refactor/docs]
- **상태**: [open/closed]
- **라벨**: [라벨 목록]
- **URL**: [이슈 URL]

## 📝 이슈 설명

[이슈 본문 요약]

## 🔍 문제 분석

**근본 원인**:
- [원인 1]
- [원인 2]

**영향 범위**:
- [영향받는 파일/컴포넌트 1]
- [영향받는 파일/컴포넌트 2]

**관련 파일**:
- `path/to/file1.tsx` - [역할]
- `path/to/file2.ts` - [역할]

🔄 Phase별 해결 계획

각 Phase는 다음 구조를 따라 작성하세요:

Phase [번호]: [단계 이름]

🎯 이번 단계 목표

[이 Phase에서 달성할 것을 1-2문장으로 요약]

📥 시작 조건 (Prerequisites)

  • • [이 Phase를 시작하기 전에 필요한 조건 1]
  • • [이 Phase를 시작하기 전에 필요한 조건 2]

📤 완료 시 결과물

  • •[이 Phase 완료 후 얻게 되는 구체적 결과물]
  • •[예: "이슈에서 설명한 버그가 수정됨", "새로운 기능이 작동함"]

🔨 구현 작업 체크리스트

파일 생성/수정:

  • • path/to/file1.tsx - [파일의 역할 및 주요 변경사항]
  • • path/to/file2.ts - [파일의 역할 및 주요 변경사항]

기능 구현:

  • • [구체적 기능 1] 구현
  • • [구체적 기능 2] 구현

버그 수정: (버그인 경우)

  • • [버그 원인] 수정
  • • [엣지 케이스] 처리
  • • [에러 핸들링] 추가

테스트:

  • • [테스트 케이스 1] 작성 및 실행
  • • [테스트 케이스 2] 작성 및 실행
  • • 이슈에서 설명한 재현 방법으로 검증

코드 품질:

  • • TypeScript 타입 안전성 확보
  • • 에러 핸들링 구현
  • • 코드 주석 추가 (필요한 경우)

✅ 검증 체크리스트

이슈 해결 확인:

  • • 이슈에서 보고된 문제가 해결되었는가?
  • • 이슈에서 요청한 기능이 구현되었는가?
  • • 재현 방법을 따라 했을 때 정상 작동하는가?

기능 테스트:

  • • [핵심 기능 1]이 정상적으로 작동하는가?
  • • [핵심 기능 2]가 예상대로 동작하는가?

통합 테스트:

  • • 이전 Phase의 기능이 여전히 정상 작동하는가?
  • • 새로운 변경사항이 기존 기능과 충돌하지 않는가?

코드 품질:

  • • 코딩 컨벤션을 따르는가?
  • • 불필요한 코드가 제거되었는가?
  • • 타입 안전성이 확보되었는가?

📝 구현 가이드

핵심 접근 방법: [이 Phase를 구현할 때 사용할 핵심 패턴이나 접근법]

참고 코드 패턴:

typescript
// 기존 코드베이스에서 참고할 패턴
// 또는 유사한 구현 예시

주의사항:

  • •⚠️ [구현 시 주의할 점 1]
  • •⚠️ [구현 시 주의할 점 2]

다음 Phase와의 연결:

  • •[Phase 연결 설명]

🔧 실행 및 검증 명령어

개발 서버 실행:

bash
npm run dev

테스트 실행:

bash
[테스트 명령어]

검증 절차:

  1. •[검증 단계 1]
  2. •[검증 단계 2]
  3. •[이슈의 재현 방법 따라하기]

Phase 분해 원칙

  • •기능적 독립성: 각 Phase는 독립적으로 실행 및 테스트 가능
  • •순차적 의존성: Phase는 논리적 순서를 따름
  • •복잡도 균형: 각 Phase의 작업량이 비슷하게 분배 (2-4시간 내 완료)
  • •점진적 개선: 각 Phase 완료 후 실행 가능한 결과물 생성
  • •적정 개수: 전체 작업을 3-8개의 Phase로 분해

이슈 특화 고려사항

버그 수정인 경우:

  1. •Phase 1: 버그 원인 파악 및 재현 환경 구축
  2. •Phase 2: 근본 원인 수정
  3. •Phase 3: 엣지 케이스 처리 및 테스트
  4. •Phase 4: 관련 문서 업데이트

기능 추가인 경우:

  1. •Phase 1: 기본 기능 구현
  2. •Phase 2: UI/UX 통합
  3. •Phase 3: 에러 핸들링 및 검증
  4. •Phase 4: 테스트 및 문서화

리팩토링인 경우:

  1. •Phase 1: 테스트 커버리지 확보
  2. •Phase 2: 코드 구조 개선
  3. •Phase 3: 성능 최적화
  4. •Phase 4: 문서 및 주석 업데이트

📊 전체 작업 개요

Phase별 계획 작성 후 다음 표를 포함하세요:

Phase제목예상 시간난이도의존성
1[제목][시간][상/중/하]없음
2[제목][시간][상/중/하]Phase 1
...............

🔄 Phase 간 의존성 다이어그램

code
Phase 1 (원인 파악)
   ↓
Phase 2 (수정 구현)
   ↓
Phase 3 (테스트)
   ↓
[필요에 따라 추가]

🚀 시작하기

전체 작업 시작 전 준비사항

  • • 이슈 내용 숙지
  • • 관련 파일 파악
  • • git branch 생성: git checkout -b issue-$ARGUMENT-[description]

권장 작업 순서

  1. •각 Phase를 순서대로 진행
  2. •Phase 완료 시마다 git commit
  3. •검증 체크리스트를 모두 확인 후 다음 Phase로 진행
  4. •모든 Phase 완료 후 Pull Request 생성

이슈 종료 절차

  1. •모든 Phase 완료 확인
  2. •Pull Request 생성
  3. •PR 설명에 "Closes #$ARGUMENT" 또는 "Fixes #$ARGUMENT" 포함
  4. •코드 리뷰 및 머지
  5. •이슈 자동 종료 확인

📋 최종 체크리스트

전체 작업 완료 후:

  • • 이슈에서 보고된 문제가 완전히 해결됨
  • • 이슈의 재현 방법으로 검증 완료
  • • 모든 Phase의 검증 체크리스트 통과
  • • 관련 테스트 작성 및 통과
  • • 코드 리뷰 준비 완료
  • • PR에 이슈 번호 연결 (Closes #$ARGUMENT)

🎬 실행 지침

중요:

  1. •이슈 가져오기: gh issue view $ARGUMENT로 이슈 내용 확인
  2. •코드베이스 분석: 관련 파일과 패턴 파악
  3. •계획 수립: Phase별로 체계적인 해결 계획 작성
  4. •사용자 승인 요청: 계획을 사용자에게 제시하고 피드백 받기
  5. •구체적인 파일 경로: 실제 프로젝트 파일 경로 사용
  6. •재현 가능성: 이슈의 재현 방법을 검증 절차에 포함

계획 제시 방법:

  • •계획을 작성한 후 "이 계획대로 진행하시겠습니까?" 같은 질문은 하지 마세요
  • •대신 명확하고 상세한 계획을 제시하고, 사용자가 자연스럽게 검토할 수 있도록 하세요
  • •계획이 복잡하거나 여러 접근 방법이 있는 경우에만 선택지를 제시하세요

💡 예시 출력 형식

markdown
# Issue #123: 로그인 버튼 클릭 시 500 에러 발생 - 해결 계획

## 🐛 이슈 정보

- **이슈 번호**: #123
- **제목**: 로그인 버튼 클릭 시 500 에러 발생
- **타입**: bug
- **상태**: open
- **라벨**: bug, priority:high
- **URL**: https://github.com/user/repo/issues/123

## 📝 이슈 설명

사용자가 로그인 페이지에서 이메일과 비밀번호를 입력하고 "로그인" 버튼을 클릭하면 500 Internal Server Error가 발생합니다.

## 🔍 문제 분석

**근본 원인**:
- Supabase Auth API 호출 시 user_id가 undefined로 전달됨
- Server Action에서 인증 체크 누락

**영향 범위**:
- `app/api/auth/login/route.ts` - 로그인 API 엔드포인트
- `components/auth/login-form.tsx` - 로그인 폼 컴포넌트

**관련 파일**:
- `app/api/auth/login/route.ts` - 인증 처리 로직
- `components/auth/login-form.tsx` - 로그인 UI
- `lib/supabase/server.ts` - Supabase 서버 클라이언트

---

### Phase 1: 버그 원인 파악 및 재현

#### 🎯 이번 단계 목표
로그인 API 엔드포인트의 에러 원인을 정확히 파악하고, 로컬 환경에서 버그를 재현합니다.

[... 나머지 Phase별 상세 내용 ...]

⚠️ 주의사항

  1. •이슈 번호 검증: 존재하지 않는 이슈 번호인 경우 명확한 에러 메시지 제공
  2. •코드베이스 분석: 이슈만 보지 말고 실제 코드도 반드시 확인
  3. •과도한 추측 금지: 코드를 확인하지 않은 상태에서 추측으로 계획 작성 금지
  4. •구체성: "파일을 수정한다" 대신 "app/api/auth/login/route.ts의 15번째 줄 수정"처럼 구체적으로
  5. •재현 방법 포함: 이슈의 재현 방법을 검증 절차에 반드시 포함

📚 참고 자료