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

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

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

✓2. 학습 목표

✓이번 강의를 마치면

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

◇3. 핵심 개념

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

최소 사례를 비교해 보면 차이가 분명합니다.

• 부족한 기록: “테스트가 안 됩니다.”
• 재현 가능한 기록: “Node 버전, 프로젝트 상태, npm.cmd test 실행, 기대 종료 코드 0, 실제 첫 오류와 종료 코드 1”

첫 문장은 다른 사람이 무엇을 실행해야 할지 알 수 없지만 두 번째는 같은 조건을 만들고 결과를 비교할 수 있습니다. 관찰한 사실과 “아마 캐시 문제” 같은 원인 가설도 분리합니다.

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

✎4. 단계별 실습

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

시작 전 상태: 프로젝트 루트, Git 커밋 또는 변경 상태, 런타임 버전과 실패 명령을 기록합니다. 실제 토큰·사용자명·개인 절대 경로는 문서와 로그에서 제거합니다.

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

예상 결과: 화면과 logs/test-failure.txt에 같은 첫 오류가 남고 실패한 명령의 $LASTEXITCODE는 보통 0이 아닌 값입니다. 다른 터미널에서도 같은 절차로 같은 첫 오류와 종료 코드가 관찰돼야 합니다.

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

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

기록 흐름은 환경 고정 → 최소 명령 실행 → 첫 오류와 종료 코드 수집 → 민감 정보 제거 → 새 터미널 재현입니다. 수정 후에도 같은 절차를 사용해야 “다른 입력에서 우연히 성공”한 경우와 해결을 구분할 수 있습니다.

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

!자주 하는 실수

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

✎7. 직접 실습

✎직접 실습

실습 목표

복구 가능한 잘못된 경로 하나로 실패를 만들고 다른 터미널에서도 재현 가능한 보고서를 작성합니다.

시작 전 상태

학습용 프로젝트를 사용하고 현재 정상 실행 명령과 결과를 먼저 기록합니다. 실제 설정이나 의존성을 삭제하지 말고 명령의 입력 경로만 임시로 잘못 지정합니다.

1단계: 따라 하기

존재하지 않는 연습 파일 경로로 명령을 실행하고 첫 오류, 전체 명령, 종료 코드를 수집합니다. 템플릿의 환경·사전 조건·기대·실제를 채웁니다.

2단계: 조건 바꿔 보기

오류 메시지에서 개인 경로만 <사용자>로 치환합니다. 새 PowerShell에서 문서 절차만 따라 동일한 첫 오류가 나는지 확인합니다.

3단계: 직접 적용

경로를 올바르게 복구해 같은 명령을 다시 실행하고 성공 결과와 종료 코드를 문서에 추가합니다. 관찰과 원인 가설은 별도 항목으로 남깁니다.

4단계: 스스로 확인

• 문서만 보고 입력과 명령을 재현할 수 있나요?
• 기대 결과와 실제 결과가 수치·문장으로 비교되나요?
• 토큰, 이메일, 개인 경로가 제거됐나요?

막혔을 때

증상	확인·해결
다른 터미널에서는 재현 안 됨	현재 위치·환경 변수·의존성 버전을 추가 기록합니다.
로그 파일이 비어 있음	실행 명령과 리다이렉션 순서, 대상 폴더를 확인합니다.
오류가 너무 많음	첫 오류를 기준으로 최소 입력과 절차를 줄입니다.

?8. 이해 점검 질문 3개

?이해 점검

1. “안 됩니다”라는 보고를 받았을 때 같은 문제를 재현하려면 최소 어떤 정보 여섯 가지를 요청해야 하나요?
2. 마지막 오류만 고쳤더니 첫 오류가 그대로입니다. 오류 연쇄에서 첫 실패를 우선해야 하는 이유는 무엇인가요?
3. 로그에 사용자 홈 경로와 토큰이 함께 있을 때 재현성을 유지하면서 어떻게 공유본을 만들겠나요?

■9. 핵심 요약

■핵심 요약

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

§10. 다음 강의 연결

실패를 같은 조건에서 반복할 수 있는 증거로 바꿨습니다. 다음 강의에서는 이 재현 조건을 자동 테스트의 입력과 기대 결과로 옮깁니다.