Debug

---
name: debug
description: "Root-cause investigation before any fix when you hit a bug, a failing test, or behavior that differs from expectations. Four investigation stages, backward tracing, layered defense. 트리거: \"에러 나\", \"왜 안 되지\", \"실패해\", \"깨졌어\"."
---

# debug

nereus:common 규칙을 따른다. 이 스킬은 **프로세스 스킬**이다 — 구현 스킬(build·frontend·backend·app)보다 먼저 온다.

## 철칙

```
근본 원인 조사 없이는 수정하지 않는다.
```

증상 위치를 고치는 것은 실패다. 1단계를 끝내지 않았으면 수정안을 제시할 자격이 없다.
"일단 이거 바꿔보고" 는 이 스킬을 어긴 것이다. 절차의 문구를 어기는 것은 정신을 어기는 것이다.

## 언제

테스트 실패, 런타임 버그, 예상과 다른 동작, 성능 문제, 빌드 실패, 통합 실패 — **전부**.

특히 건너뛰고 싶을 때 지켜야 한다.
- 급할 때 (급하면 추측이 유혹적이다 — 그런데 추측-확인 반복이 체계적 조사보다 느리다)
- "딱 한 줄이면 될 것 같은" 때
- 이미 두세 번 고쳐봤는데 안 될 때
- 문제를 완전히 이해하지 못했을 때

"간단한 버그니까" 는 이유가 안 된다. 간단한 버그에도 근본 원인이 있고, 간단하면 절차도 빨리 끝난다.

## 4단계 — 각 단계를 끝내고 다음으로

### 1단계. 근본 원인 조사

수정을 **하나도** 하기 전에:

1. **에러를 끝까지 읽는다.** 스택 트레이스 전체, 줄 번호, 파일 경로, 에러 코드. 답이 거기 적혀 있는 경우가 많다. 경고도 넘기지 않는다.
2. **재현 조건을 한 줄로 적는다.** 매번 나는가? 안정적으로 재현되지 않으면 데이터를 더 모은다 — 추측하지 않는다.
3. **최근 변경을 본다.** `git log --oneline -10`, `git diff`. 새 의존성, 설정 변경, 환경 차이.
4. **경계마다 계측한다** (컴포넌트가 여럿일 때 — CI→빌드→서명, API→서비스→DB).
   ```
   각 컴포넌트 경계에서:
     - 무엇이 들어가는지 로그
     - 무엇이 나오는지 로그
     - 환경·설정이 전달되는지 확인
   한 번 실행해 "어디서" 깨지는지 증거를 얻는다 → 그 컴포넌트만 파고든다
   ```
   가설을 세우기 전에 증거를 만든다. 어느 층에서 값이 사라지는지 보이면 조사 범위가 1/N 로 줄어든다.
5. **역추적한다.** 에러가 콜스택 깊은 곳에서 났으면 `references/root-cause-tracing.md` 의 절차대로 원래 트리거까지 거슬러 올라간다. 나쁜 값이 어디서 생겼는지 찾는다.

코드 구조 파악은 grep 보다 `codegraph_explore` 를 먼저 쓴다 — 동적 디스패치·콜백은 grep 으로 따라갈 수 없다.

### 2단계. 패턴 분석

1. **동작하는 예제를 찾는다.** 같은 저장소에서 비슷하지만 잘 되는 코드. 레퍼런스 구현이 있으면 **훑지 말고 전부 읽는다** — 부분 이해는 버그를 보장한다.
2. **차이를 전부 나열한다.** 아무리 작아도. "이게 영향 있을 리 없다"고 미리 자르지 않는다.
3. **의존 조건을 확인한다.** 필요한 설정·환경·다른 컴포넌트, 이 코드가 하는 암묵적 가정.

### 3단계. 가설 하나

1. **한 문장으로 쓴다.** "X 때문에 Y 가 난다." 모호하면 아직 가설이 아니다.
2. **가장 작은 실험으로 검증한다.** 로그 한 줄, 테스트 한 개. 한 번에 한 변수만.
3. **틀리면 새 가설을 세운다.** 기존 수정 위에 수정을 얹지 않는다. 틀린 가설은 이유와 함께 대화에 명시적으로 남긴다(자동 압축 요약의 MUST NOT 섹션이 이어받는다).
4. **모르면 모른다고 말한다.** "X 를 이해하지 못했습니다." 아는 척이 가장 비싸다.

### 4단계. 구현

1. **실패하는 테스트를 먼저 만든다.** 가장 단순한 재현. 프레임워크가 없으면 일회용 스크립트라도. 수정 전에 반드시 있어야 한다. `tdd.enforce: "block"` 이면 PreToolUse 가 실제로 막는다.
2. **한 번에 하나만 고친다.** 근본 원인만. "여기 온 김에" 개선 금지, 묶음 리팩터링 금지.
3. **검증한다.** `run-tests.mjs` 로 돌려 evidence 를 남긴다. 다른 테스트가 깨지지 않았는지, 원래 증상이 실제로 사라졌는지 확인한다. 실행 출력을 인용한다.
4. **필요하면 다층 방어를 추가한다.** `references/defense-in-depth.md` — 같은 버그가 구조적으로 불가능해지게 각 층에서 검증한다.

## 수정 3회 실패 = 아키텍처 문제

수정이 안 먹히면 **몇 번째인지 센다.**
- 3회 미만: 1단계로 돌아간다. 새로 알게 된 정보로 다시 조사한다.
- **3회 이상: 멈춘다.** 4번째 수정을 시도하지 않는다.

아키텍처 문제의 징후: 고칠 때마다 다른 곳에서 새 공유 상태·결합이 드러난다 / 수정에 "대규모 리팩터링"이 필요하다 / 고치면 다른 증상이 생긴다.

이건 실패한 가설이 아니라 **틀린 구조**다. `ooo unstuck` 을 부르고, 그래도 안 되면 사용자에게 재설계 여부를 묻는다. 시도한 접근 전부를 이유와 함께 대화에 명시적으로 남긴다(자동 압축 요약의 MUST NOT 섹션이 이어받는다).

## 위험 신호 — 이 생각이 들면 1단계로

| 생각 | 실제 |
|---|---|
| "일단 빠르게 고치고 나중에 조사" | 첫 수정이 패턴을 만든다. 처음부터 제대로. |
| "X 를 바꿔보고 되는지 보자" | 그건 조사가 아니라 추측이다. |
| "여러 개 같이 바꾸고 테스트" | 무엇이 먹혔는지 분리할 수 없다. |
| "테스트는 생략하고 수동으로 확인" | 검증 안 된 수정은 남지 않는다. |
| "아마 X 일 거야, 그거 고치자" | 증상을 본 것이지 원인을 이해한 게 아니다. |
| "완전히는 모르지만 이러면 될 듯" | 부분 이해는 버그를 보장한다. |
| "레퍼런스가 길어서 요지만 가져다 쓰자" | 전부 읽는다. |
| "한 번만 더 고쳐보자" (이미 2회 이상) | 3회 실패는 구조 문제다. |
| "급해서 절차 생략" | 체계적 조사가 추측-확인보다 빠르다. |

## 사용자가 이 말을 하면 절차를 어긴 것이다

- "그게 실제로 그런가요?" → 확인 없이 가정했다
- "추측하지 마세요" → 이해 없이 수정안을 냈다
- "그거 로그로 보이나요?" → 증거 수집을 건너뛰었다
- "또 안 되네요" → 접근 자체가 틀렸다. 1단계로.

## 에이전트 자기 진단 (내가 루프에 빠졌을 때)

같은 도구를 반복 호출하고 있거나, 토큰만 쓰고 진척이 없거나, 원래 작업에서 표류하고 있다면 그 자체가 디버깅 대상이다.

1. **멈추고 상태를 캡처한다.** 지금까지 시도한 것, 각각의 실패 이유, 현재 가설을 목록으로 적는다.
2. **환경 불일치를 확인한다.** 기대한 파일·경로·설정이 실제로 그 상태인지 직접 확인한다. 기억을 신뢰하지 않는다.
3. **범위를 좁힌 한 걸음으로 복구한다.** 큰 재시도가 아니라 가장 작은 검증 하나.
4. **그래도 안 되면 사람에게 올린다.** 위 목록을 그대로 보여준다. 무엇을 알아냈고 무엇이 막혔는지.

## 참고

- `references/root-cause-tracing.md` — 콜스택 역추적, 스택 트레이스 계측
- 테스트 오염원(어느 테스트가 이 파일을 만드는가) 이분 탐색:
```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/debug/scripts/find-polluter.mjs" ".git" "tests/**/*.test.ts" --cmd "npm test"
```
- `references/defense-in-depth.md` — 진입점·비즈니스 로직·환경 가드·계측 4층 검증
- 출처: superpowers `systematic-debugging`, ECC `agent-introspection-debugging` 을 Nereus(TDD 강제·evidence)에 맞춰 이식.