Debugger

---
name: debugger
description: "버그 원인을 시스템 로그 기반으로 특정하고 수정·검증·정리까지 완료하는 디버깅 워크플로우 스킬. 트리거: '디버깅해줘', '버그 원인 찾아줘', '어디서 오류나는지', '로그 삽입해줘', 에러 메시지/스택 트레이스 붙여넣기, '--pw'/'--pw --headless'/'--pw --record' 플래그. 지원 언어: JS/TS, Python, Java, Kotlin. 안티-트리거: 단순 코드 리뷰, 신규 기능 구현, 원인이 이미 특정된 경우(수정만 진행), 성능 최적화, 기능 동작 검증/시나리오 PASS-FAIL 판정."
argument-hint: "[에러 메시지 또는 버그 설명] [--pw] [--headless] [--record]"
---

# DEBUGGER 워크플로우

$ARGUMENTS 를 파싱하여 모드와 플래그를 결정한다.

## 플래그 파싱

| 플래그 | 모드 |
|---|---|
| (없음) | 기본 모드 — 4단계 |
| `--pw` | Playwright MCP 모드 — 5단계 |
| `--pw --headless` | Playwright MCP headless 선호 |
| `--pw --record` | Playwright MCP trace/video 기록 선호 |

`--pw` 모드는 이 플러그인에 동봉된 Playwright MCP 서버(`.mcp.json`)를 사용한다.

---

## 안티-트리거 확인

아래 조건에 해당하면 스킬을 실행하지 않고 즉시 중단한다:
- 단순 코드 리뷰 요청 ("이 코드 어때?")
- 신규 기능 구현 요청 (버그가 아닌 경우)
- 원인이 이미 특정된 상태에서 수정만 요청 → 수정만 진행, 로그 삽입 스킵
- 성능 최적화 요청

---

## 기본 모드 (4단계)

### [1/4] 분석

1. 관련 코드 파일 읽기 — 버그 현상·에러 메시지·재현 조건 파악
2. **`sequential_thinking` 툴로 가설 도출 (필수)**
   - 각 Thought에서 하나의 가설을 검토하고 근거/반례를 기술
   - 가설이 기각되면 `isRevision: true`로 수정하거나 다음 가설로 이동
   - `nextThoughtNeeded: false`가 되면 상위 가설 최대 5개 확정
3. 의심 지점을 **최대 5개**까지 목록화 (우선순위 상위 5개만)
4. 출력 형식:

```
[1/4] 분석
의심 지점:
1. 파일:라인 — 근거
2. 파일:라인 — 근거
...
```

### [2/4] 로그 삽입

의심 지점 각각에 디버그 로그를 **파일에 직접 삽입**한다.

**로그 삽입 규칙 (§로그 규칙 참조)**를 엄격히 준수.

삽입 완료 후:
- 사용자에게 **실행 명령**과 **결과 붙여넣기 요청**을 명시
- **대기** — 사용자가 로그를 붙여넣기 전까지 [3/4]로 절대 진행하지 않음
- 도중에 사용자가 다른 질문을 하면 → 해당 질문에 답한 뒤 로그 결과 대기 상태임을 재고지

### [3/4] 원인 특정

사용자가 붙여넣은 로그를 읽고 의심 지점 중 실제 원인을 특정한다.

출력 형식:
```
원인: 파일:라인 — 설명
```

로그로 특정 불가 시:
- 추가 로그를 삽입하고 [2/4]로 복귀 (최대 2회)
- 2회 초과 시 → 사용자에게 추가 정보(재현 조건·환경 등) 요청 후 **중단**

### [4/4] 수정 + 정리

1. **범위 판정 게이트** (§범위 판정 게이트) → 수정 범위 확정
2. 확정 범위에 버그 수정 적용 — 기본은 원인 파일. 범위 판정에서 ⚠️ 변경필요로 나온 인접 경계는 *같은 원인의 다른 발현*이므로 함께 수정. stub→제대로 권고가 있으면 반영
3. 사용자에게 재실행 요청 → 결과 확인
4. **회귀 게이트** → 프로젝트 검증 스크립트(`verify.sh`, `npm test`, `npm run build`, `pytest` 등)가 있으면 실행. 재현 증상은 사라졌어도 수정이 다른 곳(tsc/lint/단위테스트)을 깨뜨리지 않았는지 확인. FAIL → 회귀 수정 후 재검증
5. **해결됨**(증상 해소 + 검증 스크립트 PASS) → §정리 단계 실행 후 수정 요약 출력 + 종료
6. **미해결** → [3/4]로 복귀 (최대 2회 반복). 2회 초과 시 상황 보고 후 중단

---

## `--pw` 모드 (5단계)

### 사전 조건 체크 (필수)

1. Playwright MCP 서버 연결 여부 확인 (이 플러그인에 동봉됨)
   - 미연결 → 연결 안내 제안. 사용자 거부 시 기본 모드(4단계) 폴백 여부 질문
2. 대상 프로젝트가 웹 UI 프로젝트인지 확인 (package.json, index.html, 사용자 명시)
3. 재현 URL과 재현 시나리오 확인 — 없으면 사용자에게 1회 질문
4. 백엔드 의존성이 있는 프로젝트라면, 재현/수정 사이클이 운영 데이터에 영향을 주지 않도록 로컬·테스트 환경(테스트 DB·개발 서버)을 사용하도록 사용자에게 안내한다

### [1/5] 분석

기본 모드 [1/4]와 동일. (`sequential_thinking` 툴 필수 실행 포함)

### [2/5] 로그 삽입

기본 모드 [2/4]와 동일. 단 클라이언트 코드는 `console.log` 사용 (브라우저 콘솔 가시성 확보).

### [3/5] Playwright MCP 자동 실행

Playwright MCP 도구로 지정된 URL/시나리오를 실행한다:
- 콘솔 로그, 네트워크 로그, 스크린샷 수집
- `--record` 시 trace 기록 옵션 선호
- 출력: 수집 로그 요약 + 스크린샷 경로 (MCP 반환 경로 그대로)

수집 대상별 Playwright MCP 도구:
- 콘솔 에러: `browser_console_messages`
- 네트워크 요청·응답: `browser_network_requests` / `browser_network_request`
- 스크린샷: `browser_take_screenshot`
- DOM 스냅샷: `browser_snapshot`

### [4/5] 원인 특정

수집된 로그·스크린샷 기반으로 원인 특정. 기본 모드 [3/4]와 동일 형식.

### [5/5] 수정 + 검증 + 정리

1. **범위 판정 게이트** (§범위 판정 게이트) → 수정 범위 확정 후 수정 코드 적용
2. Playwright MCP로 **동일 시나리오 재실행** → 로그·스크린샷으로 해결 검증
3. **회귀 게이트** → 프로젝트 검증 스크립트(`verify.sh`, `npm test`, `npm run build`, `pytest` 등)가 있으면 실행. 시나리오 재현은 동일 증상만 보므로, 정적+단위 게이트로 회귀를 추가 확인. FAIL → 회귀 수정 후 재검증
4. **해결됨**(증상 해소 + 검증 스크립트 PASS) → §정리 단계 실행 + before/after 스크린샷 경로 출력 + 종료
5. **미해결** → [4/5]로 복귀 (최대 2회). 2회 초과 시 가설·수정 이력·수집 로그 요약 보고 후 중단

---

## 범위 판정 게이트

원인 특정([3/4]·[4/5]) 직후, 수정을 **적용하기 전에** 실행한다. 단편적 수정(이 화면만 막고 넘어가 나중에 들어내는 것)과 부적절한 stub를 잡는 단계다.

### 판정 기준

특정된 원인(`파일:라인` + 설명)과 계획된 수정안(무엇을 어떻게 — 아직 미적용)을 놓고, **직접 인접한 경계**를 각각 점검한다:

- **호출부**: 이 함수/모듈을 부르는 쪽이 수정 후 계약을 그대로 유지하는가?
- **API/데이터 계약**: 반환 타입·스키마·에러 형태가 바뀌면 소비자가 깨지지 않는가?
- **공유 상태**: 전역·캐시·DB 등 공유 자원의 다른 사용처에서 같은 버그가 재발현하지 않는가?

임시구현(stub/fallback/하드코딩)을 넣으려 한다면 2×2로 평가한다:
- **형태가 known인가?** (제대로 된 구현의 모양을 지금 아는가)
- **되돌리기 비용이 낮은가?** (나중에 제대로 바꿀 때 파급이 작은가)
- 둘 다 "아니오"에 가까우면 stub 대신 처음부터 제대로 구현한다.

> 별도의 범위 검토용 read-only 서브에이전트가 설치·사용 가능한 환경이라면, 위 기준으로 판정을 위임해 교차검증할 수 있다. 없으면 위 기준으로 인라인 자기검토를 수행한다.

### 결과 처리

| 판정 결론 | 동작 |
|---|---|
| 수정안 그대로 OK | 계획대로 [4/4]·[5/5] 수정 적용 |
| 범위 확대 필요 | ⚠️ 경계를 수정 범위에 포함 (같은 원인의 발현 = 인스코프, 리팩토링 아님) |
| stub→제대로 권고 | stub 대신 제대로 구현 |

- 단일 함수 내부 순수 로직 버그처럼 인접 경계가 없으면 즉시 "그대로 OK" — 오버헤드가 작다.
- 판정을 정당한 근거로 무시할 수 있으나, 무시 시 **사유 1줄**을 남긴다(무비판 수용·무비판 무시 둘 다 금지).

---

## 로그 규칙

### 지원 언어별 로그 형식

| 언어 | 마커 주석 | 로그 함수 | 예시 |
|---|---|---|---|
| JavaScript/TypeScript | `// [DEBUG-INSERTED]` | `console.log` | `console.log('[DEBUG] userId:', userId);` |
| Python | `# [DEBUG-INSERTED]` | `print` (또는 기존 logger) | `print(f'[DEBUG] user_id: {user_id}')` |
| Java | `// [DEBUG-INSERTED]` | `System.out.println` (또는 기존 logger) | `System.out.println("[DEBUG] userId: " + userId);` |
| Kotlin | `// [DEBUG-INSERTED]` | `println` (또는 기존 Log/logger) | `println("[DEBUG] userId: $userId")` |

### 불변 규칙

1. 모든 삽입 로그는 `[DEBUG]` 문자열을 **반드시** 포함
2. 로그 라인 바로 위에 `// [DEBUG-INSERTED]` 또는 `# [DEBUG-INSERTED]` 마커 주석 삽입
3. 기존 logger (winston, pino, SLF4J 등)가 있으면 해당 logger의 debug 레벨 사용 — 마커 규칙은 동일 적용
4. 로그에 비밀번호·토큰·개인정보가 찍힐 가능성이 있으면 해당 필드를 `***`로 마스킹

---

## 정리 단계

**마커 주석 기반 제거만 수행한다:**
- `[DEBUG-INSERTED]` 마커 주석이 달린 라인과 **바로 아래 로그 라인** 쌍을 제거
- 마커 없이 `[DEBUG]`만 있는 라인은 **사용자의 기존 로그 → 절대 건드리지 않음**

**제거 후 검증 (필수):**
```bash
grep -r "\[DEBUG-INSERTED\]" . --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.java" --include="*.kt"
```
- 결과가 0건이어야 종료 가능
- 1건 이상이면 해당 파일로 돌아가 재정리

**정리 완료 출력:**
```
정리 완료: 제거한 로그 N개 / 수정된 파일: 파일목록
```

---

## 안전 규칙

- 수정 범위는 원인 + 범위 판정 게이트에서 ⚠️ 변경필요로 나온 인접 경계(같은 원인의 다른 발현)에 한정 — 그 외 관련 없는 리팩토링·기능 추가는 금지
- 테스트 파일(`*.spec.*`, `*.test.*`)·CI 설정·`.env`·secrets 파일에는 로그 삽입 금지
- 정리 단계 없이 커밋하는 것은 불가 — 종료 전 반드시 grep 검증 수행

---

## Known Pitfalls

> 본 skill 실행 중 반복 발생한 실패 패턴. 신규 패턴 발견 시 entry 추가.

_(현재 누적 entry 없음)_

### 작성 형식
- **[패턴명]** — YYYY-MM-DD
  - **상황**: 어떤 단계(로그 삽입/원인 특정/정리)·조건에서 발생
  - **원인**: 무엇 때문에 실패 (마커 누락 / 정리 실패 / 잘못된 원인 특정 등)
  - **회피**: 다음 실행 시 적용할 가이드