---
name: debug
description: Analyze errors and apply fixes. Use when you have an error message, traceback, or failing log to diagnose.
---

# 디버깅 실행

> 4-Phase Debugging
> Reproduce → Isolate → Fix → Verify

호출되면 바로 파이프라인을 시작한다. 단계가 바뀔 때 한 줄로 진행을 알린다.

에러 정보: $ARGUMENTS

---

## 파이프라인 구조

```
┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│ Phase 1      │ → │ Phase 2      │ → │ Phase 3      │ → │ Phase 4      │
│ Reproduce    │   │ Isolate      │   │ Fix          │   │ Verify       │
│ (재현)       │   │ (격리)       │   │ (수정)       │   │ (검증)       │
└──────────────┘   └──────────────┘   └──────────────┘   └──────────────┘
      │                    │                  │                  │
      └──── diagnose ──────┘        fix-bugs ─┘      verify-code ┘
           (opus)                   (sonnet)          (haiku)
```

---

---

## 위임 수단이 없는 하네스 — 강등 경로 (이 스킬의 **모든** 위임 블록에 적용)

아래 단계들은 `Task tool 사용:` / `subagent_type:` 형태로 전용 에이전트에게 위임한다.
**그 위임은 계약을 실행하는 한 가지 운송 수단일 뿐이고, 불변식은 각 블록의 `prompt:`
본문에 적힌 계약이다** — 페르소나·검사 항목·출력 형식·완료 선언이 그것이다.

운송은 **사다리**다. 위에서부터 쓸 수 있는 것을 쓰고, **한 칸씩 내려간다 — 건너뛰지 않는다.**
쓸 수 있는 수단은 호스트에 직접 확인한다 — 이 문서는 위임이 가능하다고 보증하지 않는다.

**1단 — 네이티브 서브에이전트.** 아래 블록을 그대로 쓴다. **격리 있음.**

**2단 — 호스트가 제공하는 위임 수단.** 네이티브 서브에이전트가 없어도, **격리된 별도
작업을 띄우는 수단을 호스트가 제공할 수 있다.** 있으면 그것을 쓴다 — 수단의 이름은
하네스마다 다르므로 여기 적지 않는다(배포물이 특정 하네스를 전제하면 다른 하네스에서
그 지시가 죽는다). 넘기는 방법이 이 단의 전부다:

- 지시문은 **에이전트 정의 파일의 본문을 그대로** 넘긴다 — 설치본의
  `<플러그인 루트>/agents/<카테고리>/<이름>.md`. `$CLAUDE_PLUGIN_ROOT` 가 설정돼
  있으면 그것이 플러그인 루트지만 **빈 값일 수 있으니 파일 존재를 확인하고**, 없으면
  플러그인 캐시에서 같은 상대경로를 찾는다.
- **요약해서 넘기지 마라.** 페르소나·검사 항목·출력 형식·완료 선언이 그 본문에 있고,
  요약하면 그 계약이 손실된다 — 그러면 2단은 운송이 아니라 다른 작업이 된다.
- 정의 본문 **뒤에** 이 블록의 `prompt:` 를 붙여 대상·범위를 준다.
- **회신은 자기보고다.** 위임 수단이 "했다"고 돌려준 요약이 아니라 **계약이 요구하는
  산출물 자체**(리포트 본문·완료 선언·파일)로 판정하라.
- **격리는 유지된다** — 별도 컨텍스트에서 돌므로 사각지대 분리 효과가 살아 있다.
  따라서 아래 3단의 강등 표시를 붙이지 않는다.

**3단 — 이 세션에서 직접 수행.** 1·2단이 **모두** 없을 때만 여기로 내려온다.
**서브에이전트 위임 수단이 없는 하네스에서는 같은 계약을 이 세션에서 직접 수행한다.**
각 블록의 `prompt:` 를 자기 지시로 읽고, 같은 항목을 같은 형식으로 산출한다.
**수단이 없다고 단계를 건너뛰지 마라. 하지 않은 위임을 했다고 보고하지도 마라.**

> **3단(직접 수행)의 대가 — 격리 이점은 사라진다.** 직접 수행은 이 세션의 컨텍스트를
> 공유하므로 별도 에이전트의 **사각지대 분리** 효과가 없다. 이 세션이 이미 세운 가설에 진단이 끌려가 대안 원인을 덜 본다 — Phase 2(격리)의 값이 줄어든다. 상쇄책: 판정을 서술이 아니라 **재현 명령의 실제 출력**으로 하고, 기각한 대안 원인을 최소 1개 명시하라.
> 없는 이점을 있다고 쓰지 않기 위해 명시한다.

## Phase 1-2: 재현 및 격리 (Reproduce + Isolate)

```
Task tool 사용:
subagent_type: fix-bugs
model: opus
prompt: |
  (진단 전용 — 이 단계에서는 수정하지 말고 원인·재현 명령·근거만 보고)
  다음 에러를 진단해주세요:
  $ARGUMENTS

  ### Phase 1: Reproduce (재현)
  - 에러를 재현하는 최소 단계 식별
  - 재현 조건 및 환경 확인
  - 에러 발생 빈도 (항상/간헐적)

  ### Phase 2: Isolate (격리)
  - 에러 유형 (문법/타입/런타임/빌드/외부API)
  - 파일 위치 및 라인 번호
  - 스택 트레이스 분석
  - 루트 원인 파악
  - 영향 범위 (단일 함수/모듈/시스템 전체)

  ### 수정 방안 제안
  - 옵션 A: [빠른 수정]
  - 옵션 B: [근본 해결]
```

---

## Phase 3: 수정 (Fix)

```
Task tool 사용:
subagent_type: fix-bugs
model: sonnet
prompt: |
  [diagnose 결과 포함]

  진단 결과를 바탕으로 버그를 수정해주세요.

  수정 원칙:
  - 최소 변경 원칙
  - exc_info=True 포함 (Python 로깅)
  - 에러 핸들링 추가 (필요시)
  - 같은 패턴의 버그가 다른 곳에 없는지 확인
```

---

## Phase 4: 검증 (Verify)

```
Task tool 사용:
subagent_type: verify-code
model: haiku
prompt: |
  수정된 코드를 검증해주세요:
  [변경된 파일 목록]

  검증 항목:
  1. 에러 재현 → 해결 확인
  2. 빌드/컴파일 성공
  3. 타입 체크 통과
  4. 관련 테스트 통과
  5. 엣지 케이스 확인
```

---

## 출력 형식

### Phase 1-2: 재현 및 격리

| 항목      | 내용                       |
| --------- | -------------------------- |
| 유형      | [타입/런타임/빌드/외부API] |
| 위치      | [파일:라인]                |
| 재현 조건 | [최소 재현 단계]           |
| 루트 원인 | [원인 설명]                |
| 영향 범위 | [함수/모듈/시스템]         |

### Phase 3: 수정

[변경사항 diff 또는 설명]

### Phase 4: 검증

[테스트/빌드 통과 여부]

### 예방 권장

[재발 방지를 위한 제안]

- 테스트 추가
- 타입 강화
- 에러 핸들링 개선