# Bug Triage

> 에러 로그나 예외 정보를 기반으로 원인 후보와 원인 분리(트러블슈팅) 절차를 정리한다. 버그 조사 초기 단계에서 사용한다.

- Skill: `gaebalai-claude-code-kit-ko/bug-triage` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/bug-triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/bug-triage/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gaebalai (https://skillmd.com/u/gaebalai-claude-code-kit-ko)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/gaebalai-claude-code-kit-ko/bug-triage

---


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

## 목적

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

## 입력

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

## 절차

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

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

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

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

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

## 출력 형식

```markdown
## 에러 개요

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

## 원인 후보

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

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

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

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

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

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

## 원인 분리 절차

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

## 다음 액션

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

## 안전 주의사항

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

## 종료 조건

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