2장 재현 가능한 첫 실행을 만든다

“제 컴퓨터에서는 됩니다”는 환경 설명이 빠진 문장이다. 복구 가능한 프로젝트는 새 폴더에서도 같은 명령으로 같은 결과를 낸다. 런타임 버전, 설치 명령, 환경 변수 이름, 시작 명령을 README에 고정한다.

첫 실행은 세 단계로 나눈다.

1. 구문과 의존성: 프로세스가 시작되는가.
2. 준비 상태: 데이터 저장소와 필수 설정이 준비됐는가.
3. 핵심 여정: 예약 보류와 운영자 확인이 이어지는가.

오류가 나면 긴 로그 전체를 AI에 던지기보다 첫 원인과 환경을 함께 준다.

목표: npm test가 새 체크아웃에서 실행되어야 한다.
환경: Node 24, macOS, API 키 없음.
관찰: 첫 실패는 ERR_MODULE_NOT_FOUND이며 경로는 .../booking.mjs다.
제약: 새 의존성을 추가하지 않는다. 라이브 결제를 호출하지 않는다.
완료: 원인을 설명하고 최소 수정 후 전체 테스트가 통과한다.

종료 코드는 중요한 증거다. 화면에 “완료”가 보이더라도 프로세스가 1로 끝났다면 자동화에서는 실패다. 반대로 경고 한 줄이 있어도 종료 코드가 0이고 기대 결과가 맞을 수 있다. 로그 문구, 종료 코드, 생성 파일을 함께 본다.

환경 변수 표

비밀값 자체가 아니라 이름·필수 여부·실패 방식을 문서화한다.