개인 프로젝트에서 에러를 빨리 잡는 체크리스트

개인 프로젝트에서 에러가 터지면 보통 "뭐가 문제인데?" 하면서 여기저기 건드린다. 하지만 처음부터 원인을 좁히는 습관을 들이면 해결 시간이 크게 줄어든다.

먼저 에러 메시지 전체를 읽는다

터미널에 나온 빨간 글씨는 보통 스택 트레이스의 마지막 줄만 읽는다. 하지만 전체 메시지에는 원인이 이미 적혀 있을 가능성이 높다.

npm run build
# 에러가 나면 메시지 전체를 위에서 아래까지 읽는다

예를 들어 "Cannot find module 'react-query'" 같은 메시지는 import 경로가 틀렸거나 패키지가 설치 안 된 거다. 이걸 30초 안에 판단할 수 있다.

재현 조건을 명확히 한다

"빌드가 실패한다"는 너무 넓다. 구체적으로 어떨 때인지 확인한다:

• dev 환경에서도 실패하는가, production build일 때만인가
• 모든 파일을 빌드할 때인가, 특정 페이지만인가
• 어떤 파일을 수정한 후부터 시작됐는가

이 정보만으로도 원인 후보가 5개에서 1개로 줄어든다.

환경 차이를 확인한다

로컬에서는 되는데 배포 후에 실패하는 경우가 잦다. 체크할 것:

• NODE_ENV가 정말 production인가
• 패키지 버전이 같은가 (.npmrc, lock 파일)
• 환경 변수 (API_URL, DATABASE_URL 등)가 제대로 설정됐는가

로컬 개발 환경과 빌드 환경이 다르다는 걸 명시적으로 인식하는 게 중요하다.

작은 범위에서 테스트한다

전체 빌드가 실패하면 원인을 찾기 어렵다. 대신 다음을 해본다:

1. node_modules 지운 뒤 새로 설치
2. 최근 수정한 파일 하나를 원래대로 돌려본다
3. dev 환경에서 같은 코드로 테스트

한 번에 하나만 바꾸고 매번 빌드해보면 어디서 깨지는지 정확히 알 수 있다.

관련 설정과 로그를 저장한다

문제를 해결한 후엔 다음을 남긴다:

• 에러 메시지 전문
• 빌드 명령 (NODE_ENV, 플래그)
• 수정한 코드 (변수명, import 경로 등)

메모 몇 줄이 다음에 15분을 절약한다.