11강. 오류 재현 기록: ‘안 됩니다’를 재현 가능한 버그 보고로 바꾸기

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

“실행이 안 돼요”만으로는 다른 사람도, 미래의 나도 문제를 다시 만들 수 없습니다. 오류가 발생한 조건과 첫 번째 실패 지점을 짧고 정확하게 남기는 형식이 필요합니다.

✓2. 학습 목표

✓이번 강의를 마치면

• 기대 결과와 실제 결과를 구분해 씁니다.
• 환경, 입력, 재현 절차, 오류 원문을 한 기록에 모읍니다.
• 터미널 출력을 파일로 보존하면서 민감 정보는 제거합니다.

◇3. 핵심 개념

좋은 재현 기록에는 환경 → 사전 조건 → 최소 절차 → 기대 결과 → 실제 결과 → 증거가 있습니다. 여러 오류가 이어져도 가장 먼저 나온 오류부터 확인합니다. 전체 화면 캡처만 남기기보다 검색 가능한 오류 원문과 실행 명령을 함께 기록합니다.

재현에 필요하지 않은 개인정보, 토큰, 절대 사용자 경로는 지우거나 <사용자>처럼 바꿉니다.

✎4. 단계별 실습

Markdown · 파일 경로: docs/bugs/001-score-test-failure.md

docs/bugs/001-score-test-failure.md

# 점수 테스트 실패

## 환경
- OS: Windows 11
- Node.js: `node --version` 결과 기록
- 프로젝트: `D:\Projects\productivity-lab`

## 사전 조건
- 프로젝트 루트에서 의존성 설치가 끝난 상태

## 재현 절차
1. PowerShell에서 프로젝트 루트로 이동한다.
2. `npm.cmd test`를 실행한다.
3. `adds 10 points` 테스트를 확인한다.

## 기대 결과
- 모든 테스트가 통과하고 종료 코드가 0이다.

## 실제 결과
- `Expected 10, received 1` 메시지와 함께 종료 코드가 1이다.

## 증거
- `logs/test-failure.txt`의 첫 오류 참조
- 토큰, 사용자명, 개인 경로는 제거함

PowerShell · 실행 위치: D:\Projects\productivity-lab

New-Item -ItemType Directory -Force .\logs | Out-Null
npm.cmd test 2>&1 | Tee-Object -FilePath .\logs\test-failure.txt
$LASTEXITCODE

예상 결과: 화면과 파일에 같은 테스트 출력이 남고, 실패했다면 마지막 줄에 0이 아닌 종료 코드가 표시됩니다. 관리자 권한은 필요하지 않습니다.

→5. 도구와 설정이 동작하는 이유

2>&1은 오류 출력도 일반 출력 흐름에 합치고, Tee-Object는 화면에 보여 주면서 파일에도 저장합니다. 실행 명령과 종료 코드를 함께 남기면 “어떤 명령이 실패했는가”를 다시 검증할 수 있습니다.

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

!자주 하는 실수

• 결과만 적고 입력을 생략: 같은 입력과 사전 조건을 반드시 기록합니다.
• 오류 여러 개를 한 보고서에 혼합: 한 번에 한 현상만 최소 절차로 줄입니다.
• 로그 원문에 토큰을 포함: 공유 전에 비밀 값과 개인정보를 마스킹합니다.
• 해결 추측을 사실처럼 기록: 관찰한 사실과 원인 가설을 별도 문단으로 나눕니다.

✎7. 직접 실습

✎직접 실습

현재 프로젝트에서 의도적으로 잘못된 파일 경로나 설정 값 하나를 사용해 실패를 만드세요. 위 템플릿으로 재현 기록을 작성하고, 다른 터미널에서도 같은 절차로 동일한 첫 오류가 나오는지 확인합니다.

?8. 이해 점검 질문 3개

?이해 점검

1. 기대 결과와 실제 결과를 분리해야 하는 이유는 무엇인가요?
2. 여러 오류 중 첫 오류부터 확인하는 편이 좋은 이유는 무엇인가요?
3. 로그를 공유하기 전에 제거해야 할 정보에는 무엇이 있나요?

■9. 핵심 요약

■핵심 요약

재현 가능한 기록은 환경, 조건, 최소 절차, 기대·실제 결과와 증거를 포함합니다. 명령 출력과 종료 코드를 남기되 민감 정보는 먼저 제거합니다.