systematic-debugging

Files (1)

• SKILL.md

SKILL.md (first lines)

# systematic-debugging

## Iron Law

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

"일단 이것 바꿔보자", "아마 이게 문제일 거야" — 전부 **추측**이다.
Phase 1을 완료하지 않으면, 수정을 제안할 수 없다.

## 4단계 프로세스

각 단계를 완료해야 다음 단계로 넘어간다.

**Todo verbatim 규칙**: 멀티스텝 디버깅을 시작하면 Phase 1~4의 단계를 `todo_write`에 **그대로 복사**한다. 스킬을 읽고 자체 요약 계획을 세우다 단계를 흘리는 것이 대표 실패 모드다. 수행하지 않을 단계는 삭제하지 않고 해당 todo에 `skip: <이유>`를 남긴다. 조용한 생략 금지.

### Phase 1: 근본원인 조사

**수정 시도 전에 반드시 수행:**

1. **에러 메시지 정독**
   
   - 스택 트레이스 전체를 읽는다
   
   - 라인 번호, 파일 경로, 에러 코드를 기록한다
   
   - "대충 이런 에러" 금지 — 정확히 읽는다

2. **일관된 재현**
   
   - 정확한 재현 단계를 확인한다
   
   - 매번 발생하는가? 간헐적인가?
   
   - 재현 불가 → 추가 데이터 수집, 추측 금지

   - 로그인·2FA 등 인증 장벽으로 격리 브라우저 재현이 불가하면 `chrome-cdp` 스킬로 이미 로그인된 실제 세션에서 증거를 수집한다 (연결 시 사용자의 Chrome Allow 승인 1회 필요)

3. **최근 변경 확인**
   
   - `git diff`, 최근 커밋, 설정 변경
   
   - 새 의존성, 환경 차이
   
   - "이건 관계없을 거야" 가정 금지

4. **다중 컴포넌트 시스템: 진단 계측**
   
   ```
   각 컴포넌트 경계마다:
     - 입력 데이터 로깅
     - 출력 데이터 로깅
     - 환경/설정 전파 확인
     - 각 레이어 상태 체크
   
   한 번 실행 → 어디서 깨지는지 증거 수집
   그 다음 해당 컴포넌트 집중 조사
   ```

5. **데이터 흐름 추적**
   
   - 잘못된 값이 어디서 시작되는가?
   
   - 무엇이 이 잘못된 값을 전달했는가?
   
   - 원점을 찾을 때까지 역추적
   
   - **원점에서 수정**, 증상에서 수정하지 않음

### Phase 2: 패턴 분석

1. **작동하는 예시 찾기** — 같은 코드베이스에서 비슷하게 작동하는 코드
2. **참조와 비교** — 패턴 구현 시 참조를 **완전히** 읽기 (대충 훑기 금지)
3. **차이 식별** — 작동하는 것과 깨진 것의 모든 차이 나열
4. **의존성 이해** — 필요한 컴포넌트, 설정, 환경, 가정

### Phase 3: 가설 + 테스트

1. **단일 가설 수립** — "X가 원인이다. 왜냐하면 Y"
2. **최소 변경으로 테스트** — 한 번에 하나의 변수만
3. **확인 후 진행** — 맞으면 Phase 4, 틀리면 새 가설 (추가 수정 금지)
4. **모르면 인정** — "모르겠다"가 거짓 확신보다 낫다

### Phase 4: 구현

1. **실패 테스트 작성** — 버그를 재현하는 테스트
2. **단일 수정** — 근본원인만 해결, "여기 있는 김에" 개선 금지
3. **수정 검증** — 테스트 통과? 다른 테스트 영향 없는지? 최종 판정은 `prove-it-works` 스킬 기준: 버그가 보고된 것과 같은 surface에서 원래 재현이 통과해야 한다
4. **3회 실패 시 아키텍처 재검토** (아래 참고)

## 3회 실패 규칙

**3번 수정을 시도해도 해결 안 되면:**

패턴이 근본적으로 잘못되었을 가능성:

- 매 수정이 다른 곳에서 새 문제를 드러낸다
- "대규모 리팩터링"이 필요하다고 느낀다
- 수정할수록 상황이 복잡해진다

**멈추고 아키텍처를 질문한다:**

- 이 패턴이 근본적으로 건전한가?
- 관성으로 유지하고 있는 건 아닌가?
- 증상 수정 대신 아키텍처 변경이 필요한가?

**추가 수정을 시도하기 전에 사용자와 논의한다.** 재설계로 방향이 잡히면 `design-first`로 재진입한다.

## Red Flags — 프로세스로 돌아가라

다음 중 하나라도 해당되면 **Phase 1로 복귀**:

- "일단 X를 바꿔보자"
- "여러 변경을 한꺼번에 적용하고 테스트하자"
- "테스트 건너뛰고 수동 확인하자"
- "아마 X일 거야, 고쳐보자"
- "완전히 이해는 못했지만 될 것 같아"
- 데이터 흐름 추적 없이 해결책 제안

From Jonghakseo/my-pi, MIT.

More from Jonghakseo/my-pi