systematic-debug

Systematic Debug

증상만 보고 바로 고치는 안티패턴을 막는 디버깅 워크플로우. 이전 단계 산출물 없이 다음 단계로 진행 금지 — 재현 없는 가설, 가설 없는 수정은 동일 증상 재발 1순위 원인.

속도 원칙: 전체 레포/전체 로그를 먼저 훑지 않는다. Phase 1~2에서 증상·스택·재현 명령으로 범위를 좁히고, 긴 명령은 full log를 파일로 저장하고 실패 중심 요약만 대화에 남긴다.

쓰는 경우

• 버그/장애/예상치 못한 동작 + 근본 원인 불투명
• 같은 버그를 추측 수정했는데 재발

쓰지 않는 경우

• 빌드·타입 에러 → build-fix
• 한 줄 수정으로 명확한 경우 → 직접

---

Phase 0 — 입력 게이트

부실 입력(에러 정보 없음, "그냥 고쳐줘", 한 줄 증상)에서 바로 수정하지 않는다. 정보 없는 상태의 수정은 실제 원인과 무관한 코드를 건드릴 확률이 높고, 사용자에게 "고친 척"만 남긴다. 조사를 선행한다.

행동 순서:

1. 레포에서 확보 가능한 증거부터 수집 (git log, 로그, 관련 코드)
2. 부족하면 사용자에게 최소 정보 요청 (화면/엔드포인트, 에러 메시지, 발생 조건)
3. 사용자가 "그냥 고쳐달라" 고집 → "원인 불명 상태에서 수정은 재발 확률 높음, 먼저 5분만 조사" 제안
4. 그래도 덮개 수정 요청 → 승인 확인 + TODO 기록 + 후속 티켓 제안 필수
5. noisy log/build/test 명령은 출력을 파일로 저장하고, full log path를 Phase 1 증거로 기록한다.

게이트 통과 = Phase 1 작성 가능한 재료 확보됨.

---

Phase 1 — 에러 분석 (Observation)

관찰된 사실만 기록한다. 이 단계에서 원인을 추정하면 이후 단계가 그 가설을 정당화하는 방향으로 편향된다.

• 증상 / 에러 메시지·스택 / 환경·입력 / 빈도 / 최근 변경 / 모르는 것

원인 추정은 Phase 4에서.

---

Phase 2 — 재현 확립 (Reproduction)

최소 재현 케이스(MRE) 확보. 재현 없이 수정하면 "고쳤다고 믿는" 상태가 된다 — 사용자 환경에서 재발했을 때 같은 추측을 반복하게 된다.

• 재현 불가 시: 환경 차이 조사 (버전, 데이터, 플래그, 캐시, 타이밍)
• 간헐적 버그: 재현 조건 좁히기
• 그래도 재현 불가: 로깅 추가 → Phase 1 복귀

중단 조건: 재현 수단이 없으면 Phase 3 이후는 의미가 없다 (수정 검증 수단이 없으므로). 재현 명령 출력이 길면 저장한 로그 파일 경로를 재현 증거로 삼고, 대화에는 실패 핵심 라인과 tail만 남긴다.

---

Phase 3 — 실패 테스트 박제 (Failing Test) · 옵셔널

자동화 테스트를 작성할 수 있는 환경이면, Phase 2 재현 케이스를 지금 실패하는 테스트로 먼저 박제한다 (red 확인). 이 실패 테스트가 Phase 4~6의 종료 조건이 된다 — "통과할 때까지 원인 조사·수정"을 혼자 루프 돌 수 있게 하는 강한 성공 기준.

• 재현 입력 → 기대 결과를 테스트로 고정하고, 실행해서 실패(red)를 눈으로 확인한다. red가 안 뜨면 재현 또는 기대가 틀린 것 → Phase 1~2 복귀.
• 수정 전에 만든다. 수정 후 작성한 테스트는 내 수정에 맞춰져 정작 버그를 못 잡는다.

테스트 작성은 서브에이전트에 위임 (권장)

디버깅 본문 맥락(가설·의심·수정안)을 공유한 채 테스트를 쓰면, 버그를 재현하는 테스트가 아니라 수정안을 정당화하는 테스트로 기운다. 맥락을 격리한 서브에이전트에 위임해 이 편향을 끊는다. 단, 격리만으로 환각이 없어지지는 않는다 — 편향은 격리가 막고, 환각은 grounding이 막는다. 둘을 나눠 다룬다.

• 주입 (grounding): Phase 2 재현 명세(입력 → 기대), 대상 테스트 파일·기존 컨벤션·픽스처, 실제 API 시그니처, 실행 커맨드. 이걸 안 주면 프레임워크·심볼을 환각한다.
• 차단 (편향 방화벽): 리딩 가설·추정 근본 원인·수정안. 임무는 "증상을 재현하는, 지금 실패하는 테스트"이지 "수정이 동작함 증명"이 아니다.
• 증거 반환: 테스트 코드 + 실제 red 실행 출력. red가 옳은 이유로(증상과 일치하는 assertion 실패) 떴는지 확인 — import/픽스처 누락 같은 거짓 red는 반려.