11강. 버그와 문제 해결 기록: 오류·가설·수정·검증 과정을 남기기

?1. 이번 강의에서 해결할 문제

“오류를 고쳤다”만 적으면 어떤 관찰과 판단을 거쳤는지 알 수 없습니다. 실제 문제 하나를 골라 누구나 반복할 수 있는 해결 기록으로 바꿉니다.

✓2. 학습 목표

✓이번 강의를 마치면

• 증상과 재현 절차를 원인 추측과 분리합니다.
• 가능한 가설을 증거로 좁힙니다.
• 수정 전후를 같은 테스트로 검증합니다.

◇3. 핵심 개념

문제 해결 기록은 환경 → 증상 → 최소 재현 → 관찰 → 가설 → 변경 → 같은 조건 재검증 → 남은 위험 순서입니다. 처음 가설이 틀렸다면 지우지 않고 왜 제외했는지 남깁니다.

✎4. 단계별 실습

문서 작업 · 산출물: <PROJECT_ROOT>/docs/bugs/001-example.md

docs/bugs/001-example.md

# BUG-001 빠른 재시작 뒤 결과가 두 번 반영됨

## 환경
- 검증 버전과 실행 방식: 실제 값 기록

## 재현 절차
1. 프로젝트를 시작한다.
2. 결과 직후 재시작을 빠르게 두 번 선택한다.
3. 첫 행동을 한 번 수행한다.

## 예상 / 실제
- 예상: 결과가 한 번 반영된다.
- 실제: 결과가 두 번 반영된다.

## 관찰과 가설
- 관찰: 재시작 횟수만큼 이벤트 로그가 늘어난다.
- 가설 A: 구독 해제가 없어 핸들러가 누적된다.
- 가설 B: 입력이 한 프레임에 두 번 전달된다.

## 수정
- 활성화 시 구독하고 비활성화 시 같은 핸들러를 해제했다.

## 검증
- T-04를 3회 반복: 모두 한 번만 반영됨

## 남은 위험
- 장시간 반복은 T-05에서 추가 확인한다.

코드 작업: 원인을 좁히는 데 필요한 최소 변경만 적용하고 관련 없는 리팩터링은 섞지 않습니다. 테스트 작업: 수정 전과 같은 절차를 다시 실행합니다.

완료 기준: 실제 문제 하나에 환경, 3단계 이상의 재현, 두 가설, 수정과 재검증 결과가 있습니다.

§5. 작성 방식이 필요한 이유

결과보다 과정이 남으면 디버깅 능력과 판단 근거를 보여 줄 수 있습니다. 같은 증상이 돌아왔을 때도 처음부터 추측하지 않고 이전 증거를 재사용합니다.

!6. 자주 하는 실수와 해결법

!자주 하는 실수

• 증상과 원인을 섞음: 관찰한 사실과 가설을 별도 항목으로 씁니다.
• 큰 리팩터링으로 덮음: 원인을 확인할 최소 변경부터 적용합니다.
• 수정 후 정상 흐름만 확인: 원래 재현 절차를 그대로 반복합니다.
• 해결하지 못한 문제를 삭제: 현재 가설과 다음 확인을 남깁니다.

✎7. 직접 실습

✎직접 실습

실패 테스트 하나를 docs/bugs/001-짧은이름.md로 기록하세요. 완료 기준은 다른 사람이 문서만 보고 증상을 재현할 수 있고, 수정 전후 결과와 남은 위험을 비교할 수 있는 것입니다.

?8. 이해 점검 질문 3개

?이해 점검

1. 관찰과 가설을 분리해야 하는 이유는 무엇인가요?
2. 수정 뒤 같은 재현 절차를 사용해야 하는 이유는 무엇인가요?
3. 틀린 가설도 기록할 가치가 있는 경우는 언제인가요?

■9. 핵심 요약

■핵심 요약

문제 해결 능력은 오류를 숨기는 것이 아니라 재현, 관찰, 가설, 최소 수정과 같은 조건의 재검증으로 드러납니다.