이슈 트라이지(Issue Triage)
보고된 문제를 조사하여 근본 원인을 찾고, TDD 수정 계획이 포함된 GitHub 이슈를 생성합니다. 사용자에게는 질문을 최소화하는 핸즈오프(hands-off) 워크플로우입니다.
프로세스
1. 문제 파악
사용자로부터 문제에 대한 간단한 설명을 얻습니다. 사용자가 설명을 제공하지 않았다면 한 가지 질문만 하세요: "어떤 문제가 발생했나요?"
아직 후속 질문을 하지 마세요. 즉시 조사를 시작합니다.
2. 탐색 및 진단
subagent_type=Explore를 사용하여 Agent 도구로 코드베이스를 깊이 탐색합니다. 목표는 다음을 찾는 것입니다:
- 어디서 버그가 나타나는지 (진입점, UI, API 응답)
- 어떤 코드 경로가 관련되어 있는지 (흐름 추적)
- 왜 실패하는지 (증상이 아닌 근본 원인)
- 어떤 관련 코드가 있는지 (유사 패턴, 테스트, 인접 모듈)
다음 항목들을 살펴보세요:
- 관련 소스 파일과 그 의존성
- 기존 테스트 (무엇이 테스트되었고, 무엇이 누락되었는지)
- 영향을 받는 파일의 최근 변경 사항 (
git log) - 코드 경로의 오류 처리
- 올바르게 동작하는 코드베이스 내 다른 유사 패턴
3. 수정 접근법 식별
조사 결과에 따라 다음을 결정하세요:
- 근본 원인을 고치는 데 필요한 최소 변경 사항
- 영향을 받는 모듈/인터페이스
- 테스트를 통해 검증해야 할 동작
- 이것이 회귀(regression), 누락된 기능, 설계 결함 중 무엇인지
4. TDD 수정 계획 설계
구체적이고 순서가 정해진 RED-GREEN 주기 목록을 만듭니다. 각 주기는 하나의 수직 조각(vertical slice)입니다:
- RED: 깨지거나 누락된 동작을 포착하는 특정 테스트를 설명
- GREEN: 해당 테스트를 통과시키는 최소 코드 변경을 설명
규칙:
- 테스트는 구현 세부 사항이 아닌 공개 인터페이스를 통해 동작을 검증합니다.
- 한 번에 하나의 테스트, 수직 조각 (모든 테스트를 먼저 작성하고 모든 코드를 나중에 작성하는 방식이 아닙니다)
- 각 테스트는 내부 리팩터링을 견딜 수 있어야 합니다.
- 필요한 경우 최종 리팩터링 단계를 포함합니다.
- 내구성(Durability): 급진적인 코드베이스 변경에도 살아남을 수 있는 수정만 제안하세요. 동작과 계약(contracts)을 설명하고, 내부 구조는 설명하지 마세요. 테스트는 관찰 가능한 결과(API 응답, UI 상태, 사용자에게 보이는 효과)에 대해 단언(assert)하며, 내부 상태에 대해서는 단언하지 않습니다. 좋은 제안은 명세(spec)처럼 읽히고, 나쁜 제안은 diff처럼 읽힙니다.
5. GitHub 이슈 생성
gh issue create 명령어를 사용하여 아래 템플릿으로 GitHub 이슈를 생성합니다. 생성 전에 사용자에게 검토를 요청하지 말고 바로 생성한 후 URL을 공유하세요.
문제
버그 또는 이슈에 대한 명확한 설명:
- 어떤 일이 발생하는지 (실제 동작)
- 어떤 일이 발생해야 하는지 (예상 동작)
- 재현 방법 (해당하는 경우)
근본 원인 분석
조사 중 발견한 내용을 설명하세요:
- 관련된 코드 경로
- 현재 코드가 실패하는 이유
- 기여 요인
현재 코드 레이아웃에 결합되는 구체적인 파일 경로, 줄 번호, 구현 세부 사항은 포함하지 마세요. 대신 모듈, 동작, 계약을 설명하세요. 대대적인 리팩터링 후에도 이슈가 유용하게 남아 있어야 합니다.
TDD 수정 계획
RED-GREEN 주기의 번호 매기기 목록:
-
RED: [예상 동작을 설명하는] 테스트를 작성 GREEN: [테스트를 통과시키는 최소 변경]
-
RED: [다음 동작을 설명하는] 테스트를 작성 GREEN: [테스트를 통과시키는 최소 변경]
...
REFACTOR: [모든 테스트 통과 후 필요한 정리]
수락 기준
- 기준 1
- 기준 2
- 모든 새 테스트 통과
- 기존 테스트 여전히 통과
이슈를 생성한 후, 이슈 URL과 근본 원인에 대한 한 줄 요약을 출력하세요.