bug-triage

name	bug-triage
description	에러 로그나 예외 정보를 기반으로 원인 후보와 원인 분리(트러블슈팅) 절차를 정리한다. 버그 조사 초기 단계에서 사용한다.
argument-hint	[log-file|error-message|url] (선택: 환경 정보)
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob, Bash(git log *), Bash(git diff *)

당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

목적

에러 로그, 예외 메시지, 장애 보고를 출발점으로 삼아 버그의 원인 후보를 체계적으로 도출하고, 효율적인 원인 분리(트러블슈팅) 절차를 수립한다.
개인의 감이나 경험에 의존하지 않고, 증거 기반의 조사 계획을 수립함으로써 버그 수정의 초기 대응 속도를 높인다.

입력

• 에러 로그 파일 경로, 에러 메시지 텍스트, 또는 장애가 발생한 URL
• 선택: 발생 환경 (OS, 런타임 버전, 배포 환경 등)
• 선택: 발생 빈도, 재현 조건 관련 정보
• 정보가 부족할 경우 사용자에게 질문할 것

절차

1. 에러 정보 분석 및 정리

   • 지정된 로그 파일 또는 에러 메시지를 Read로 읽는다.
   • 스택 트레이스가 있는 경우, 발생 지점의 파일명·라인 번호·함수명을 추출한다.
   • 에러 유형(예외 타입, HTTP 상태 코드, 종료 코드 등)을 분류한다.

2. 관련 코드 식별

   • 스택 트레이스 또는 에러 메시지에 포함된 파일·함수를 Grep으로 검색한다.
   • 해당 코드의 전후 로직(유효성 검사, 분기 처리, 외부 호출 등)을 Read로 확인한다.
   • 의존 중인 함수나 모듈도 추적하여 영향 범위를 파악한다.

3. 최근 변경 이력 확인

   • git log로 해당 파일의 최근 변경 이력을 확인한다.
   • git diff로 최근 커밋의 변경 내용을 확인한다.
   • 버그 유입 가능성이 있는 변경(로직 수정, 의존성 업데이트, 설정 변경 등)을 식별한다.

4. 원인 후보 도출 및 우선순위 설정

   • 수집한 증거를 기반으로, 가능성이 높은 원인 후보를 3개 이상 도출한다.
   • 각 후보에 대해 “왜 그렇게 판단하는지” 근거를 명확히 기술한다.
   • 조사 비용(확인 난이도)과 발생 가능성을 기준으로 우선순위를 정한다.

5. 원인 분리 절차 수립

   • 각 원인 후보를 확인 또는 배제하기 위한 구체적인 절차를 체크리스트 형식으로 작성한다.
   • 절차는 가장 효율적인 순서(적은 노력으로 많은 후보를 배제할 수 있는 순서)로 정렬한다.
   • 각 단계의 기대 결과(이 결과면 후보 A 확정/배제)를 명확히 기재한다.

출력 형식

## 에러 개요

- **에러 유형**: [예외 타입/에러 코드]
- **발생 위치**: [파일명:라인번호 함수명]
- **에러 메시지**: [메시지 전체]
- **발생 환경**: [확인된 환경 정보]

## 원인 후보

### 1. [원인 후보명] — 가능성: 높음/보통/낮음

- **근거**: [이 후보를 의심하는 이유와 증거]
- **관련 코드**: [파일명:라인번호]
- **확인 방법**: [이 후보를 확정/배제하는 방법]

### 2. [원인 후보명] — 가능성: 높음/보통/낮음

- **근거**: [이 후보를 의심하는 이유와 증거]
- **관련 코드**: [파일명:라인번호]
- **확인 방법**: [이 후보를 확정/배제하는 방법]

### 3. [원인 후보명] — 가능성: 높음/보통/낮음

- **근거**: [이 후보를 의심하는 이유와 증거]
- **관련 코드**: [파일명:라인번호]
- **확인 방법**: [이 후보를 확정/배제하는 방법]

## 원인 분리 절차

- [ ] 단계 1: [구체적인 작업 내용] → 기대 결과: [결과 해석]
- [ ] 단계 2: [구체적인 작업 내용] → 기대 결과: [결과 해석]
- [ ] 단계 3: [구체적인 작업 내용] → 기대 결과: [결과 해석]

## 다음 액션

- **최우선 작업**: [가장 먼저 수행해야 할 절차와 그 이유]
- **추가 정보 요청**: [조사에 필요한 추가 정보가 있다면 기재]

안전 주의사항

• 로그 파일에 포함된 인증 정보(토큰, 비밀번호, API 키 등)는 출력에 포함하지 말 것
• 운영 환경의 데이터나 엔드포인트를 직접 조작하는 절차는 포함하지 말 것
• git log, git diff 외의 git 명령어(reset, checkout 등)는 실행하지 말 것
• 파일 읽기 및 검색만 수행하고, 코드 수정은 절대 하지 말 것

종료 조건

위 출력 형식에 맞는 트리아지(초기 분석) 보고서를 작성한 후 종료한다. 원인 후보는 최소 3개 이상이며, 각각 근거를 포함해야 한다. 원인 분리 절차는 체크리스트 형식으로 작성되어야 한다. 수정 작업은 사용자 지시를 기다린다.