원인 분석 스킬 (bug-cause-analysis) — 오류 원인 추적

bug-cause-analysis는 반복 업무를 더 안정적으로 처리하기 위한 AI 에이전트 스킬입니다.

사용자가 “원인 분석 스킬 사용해줘”, “왜 오류가 나는지 조사해줘”, “고치기 전에 원인부터 찾아줘”라고 요청할 때 사용한다. 파일을 바로 수정하지 않고 증거를 수집해 가능한 원인을 점수화하고 가장 효율적인 확인 순서를 제안한다.

사용 방법

Codex나 호환되는 AI 에이전트의 스킬 폴더에 아래 SKILL.md 내용을 저장한 뒤, 설명에 포함된 트리거 문장으로 호출하세요.

사용 예:
bug-cause-analysis 스킬 사용해줘.
이 작업은 bug-cause-analysis 기준으로 진행해줘.

원본 위치

.codex/skills/bug-cause-analysis/SKILL.md

SKILL.md

---
name: bug-cause-analysis
description: 사용자가 “원인 분석 스킬 사용해줘”, “왜 오류가 나는지 조사해줘”, “고치기 전에 원인부터 찾아줘”라고 요청할 때 사용한다. 파일을 바로 수정하지 않고 증거를 수집해 가능한 원인을 점수화하고 가장 효율적인 확인 순서를 제안한다.
---

# Bug Cause Analysis

## 목적

- 원인을 모른 채 여러 부분을 바꾸는 시행착오를 막는다.
- 관측된 사실과 추측을 구분해 가장 가능성 높은 원인을 찾는다.
- 수정 전에 무엇을 어떤 순서로 확인해야 하는지 제시한다.

## 절대 규칙

- 이 스킬은 원인 조사와 진단을 수행한다. 사용자가 수정까지 요청하지 않았다면 파일을 변경하지 않는다.
- 코드, 파일, 명령과 모듈이 실제로 존재하는지 확인한 뒤 언급한다.
- 근거가 없는 내용을 사실처럼 단정하지 않는다.
- 관련 없는 영역을 광범위하게 조사해 문제를 키우지 않는다.

## 진행 순서

### 1. 현상 정리

- 무엇을 했을 때 어떤 결과가 나왔는지 정리한다.
- 기대한 결과와 실제 결과를 구분한다.
- 오류 메시지, 재현 조건, 발생 시점과 최근 변경을 확인한다.

### 2. 증거 수집

- 관련 코드, 설정, 데이터와 실행 결과를 확인한다.
- 안전하고 범위가 작다면 문제를 재현한다.
- 브라우저, 터미널, 로그 또는 테스트 중 현재 문제에 직접 필요한 증거만 사용한다.
- 확인한 사실과 아직 확인하지 않은 가정을 따로 기록한다.

### 3. 원인 후보 구성

- 가능한 원인을 보통 3개, 필요하면 최대 5개까지 제시한다.
- 동일한 원인을 표현만 바꿔 여러 후보로 만들지 않는다.
- 코드, 설정, 입력 데이터, 실행 환경과 외부 의존성 등 관련된 층을 고르게 살펴본다.

### 4. 유력성 점수화

- 각 후보에 1~100점의 유력성 점수를 부여한다.
- 증거가 직접 연결될수록 높은 점수를 준다.
- 반증이 있거나 확인되지 않은 가정이 많으면 점수를 낮춘다.
- 점수는 상대 비교이며 합계가 100일 필요는 없다.

### 5. 확인 순서 제안

- 가능성이 높고 확인 비용이 낮은 후보부터 검증한다.
- 한 번에 여러 변수를 바꾸지 않는다.
- 기존 정보만으로 구분할 수 없다면 최소한의 추가 로그나 재현 절차를 제안한다.
- 로그를 추가해야 한다면 위치, 기록할 값과 검증할 가설을 구체적으로 설명한다.

## 점수 기준

- 81~100: 직접적인 증거나 재현 결과가 있음
- 61~80: 여러 정황이 일치하며 가능성이 높음
- 41~60: 일부 근거가 있으나 추가 확인이 필요함
- 21~40: 가능하지만 현재 증거가 약함
- 1~20: 반증이 있거나 관련성이 낮음

## 출력 형식

```text
문제 요약
- 기대 결과:
- 실제 결과:
- 재현 조건:

확인된 증거
- ...

가능한 원인
1. 원인 A — 82점
   - 근거:
   - 반증 또는 미확인 사항:
2. 원인 B — 55점
   - 근거:
   - 추가 확인 사항:

권장 확인 순서
1. ...
2. ...
3. ...

현재 판단
- 원인을 특정할 수 있는지
- 다음에 필요한 정보 또는 행동
```

## 완료 기준

- 가장 유력한 원인과 그 근거가 분명하다.
- 원인을 확정하지 못했다면 무엇을 확인하면 후보를 구분할 수 있는지 명확하다.
- 수정이 필요하면 범위와 위험을 설명하고 사용자의 다음 지시를 기다린다.