package-lock을 지우기 전, npm ci로 오류 원인을 좁히는 순서

npm 오류가 나자 AI가 “node_modules와 package-lock.json을 지우고 다시 설치하세요”라고 답할 때가 있다. 초보자에게는 가장 빨라 보이지만, 이 조언을 그대로 따르면 지금 프로젝트가 어떤 의존성 조합으로 돌아가던 상태였는지 잃을 수 있다. 특히 배포나 CI에서만 실패하는 상황이라면 lockfile은 쓰레기가 아니라 재현 가능한 설치 상태를 보여 주는 증거다.

먼저 결론부터 잡는다. package-lock.json은 아무 때나 지우는 파일이 아니다. docs.npmjs.com의 npm 공식 문서는 이 파일이 dependency tree의 정확한 형태를 기록해서 팀원, 배포, CI가 같은 의존성을 설치하도록 돕는다고 설명한다. 오늘 할 일은 오류를 한 번에 없애는 것이 아니라 lockfile을 지워야 하는 상황인지, package.json과 맞춰야 하는 상황인지 3분 안에 가르는 것이다.

Tap to zoom

첫 30초에는 삭제보다 diff를 먼저 본다

AI에게 맡긴 직후 npm 오류가 났다면 터미널에서 바로 삭제 명령을 치기 전에 변경 파일을 본다.

git status
git diff -- package.json package-lock.json

여기서 봐야 할 것은 세 가지다. package.json에 새 패키지가 들어갔는지, package-lock.json만 크게 바뀌었는지, 두 파일 중 하나만 바뀌었는지다. package.json만 바뀌고 lockfile이 그대로면 설치 기록이 따라오지 않은 상태일 수 있다. 반대로 lockfile만 수천 줄 바뀌었다면 AI가 실제 문제와 관계없는 재해석을 만든 것일 수 있다.

이 단계에서 전체 재설치를 요청하면 AI는 문제를 좁히기보다 “깨끗한 상태”를 만들려고 할 가능성이 높다. 그러면 AI가 파일을 너무 많이 고칠 때 막는 프롬프트에서 다룬 것처럼 수정 범위가 커진다. 삭제보다 먼저 diff를 저장해야 나중에 되돌릴 수 있다.

1분에는 npm ci로 현재 lockfile을 검증한다

기존 프로젝트가 “이 lockfile대로 설치되는지” 확인하려면 npm ci가 더 좋은 증거가 된다.

npm ci

docs.npmjs.com의 npm ci 문서에 따르면 이 명령은 테스트, CI, 배포처럼 깨끗한 설치가 필요한 환경을 위한 명령이다. 기존 package-lock.json이나 npm-shrinkwrap.json이 있어야 하고, package.json과 lockfile이 맞지 않으면 lockfile을 고쳐 쓰는 대신 오류로 종료한다. 이미 node_modules가 있으면 지우고 새로 설치하지만, package.json이나 lockfile에는 쓰지 않는다.

그래서 초보자에게 npm ci의 가치는 “해결”보다 “판정”에 있다. 통과하면 현재 lockfile 조합은 재현 가능하다는 뜻에 가깝다. 실패하면 오류 문장에서 어떤 패키지와 버전 요구가 충돌하는지 읽어야 한다. 이때 바로 --force를 붙이면 판정 과정을 건너뛰게 된다.

Tap to zoom

2분에는 ERESOLVE에서 패키지 이름과 요구 버전을 떼어 낸다

ERESOLVE나 peer dependency 오류가 보이면 전체 로그를 무섭게 보지 말고 아래 네 줄만 복사한다.

1. 충돌한 패키지 이름
2. 현재 설치하려는 버전
3. 상대 패키지가 요구하는 peer dependency 범위
4. npm이 제안한 --force 또는 --legacy-peer-deps 문장

--force나 --legacy-peer-deps가 로그에 보인다고 해서 그것이 첫 번째 해결책이라는 뜻은 아니다. npm 문서도 npm ci에서 lockfile을 만들 때 사용한 설치 플래그가 있다면 같은 설정을 프로젝트에 남겨야 오류를 피할 수 있다고 설명한다. 즉 플래그는 “이번 한 번 무시”가 아니라 프로젝트 설치 규칙이 될 수 있다.

AI에게도 이 네 줄만 준다. “다 고쳐줘” 대신 충돌 패키지와 요구 버전을 기준으로 물어야 한다.

3분에는 AI에게 lockfile 삭제 금지 조건을 준다

아래처럼 요청하면 AI가 파일 전체를 새로 만들기보다 원인을 좁히게 된다.

Tap to zoom

npm install 또는 npm ci에서 의존성 오류가 납니다.

요청:
- package-lock.json을 삭제하거나 재생성하는 해결책을 먼저 제안하지 마세요.
- package.json과 package-lock.json의 차이를 기준으로 원인을 좁혀 주세요.
- 충돌한 패키지 이름, 현재 버전, 요구 peer dependency 범위를 표로 정리해 주세요.
- 수정은 package.json의 한 줄 변경, npm install <패키지>@<버전>, 또는 설정 파일 변경 중 하나로만 제안해 주세요.
- 마지막에 확인 명령은 npm ci 하나로 제시해 주세요.

오류 로그:
[ERESOLVE 또는 npm ci 실패 로그에서 핵심 부분만 붙여 넣기]

현재 변경 파일:
[git diff -- package.json package-lock.json 결과 붙여 넣기]

이 프롬프트의 핵심은 lockfile 삭제를 기본값에서 빼는 것이다. 정말로 lockfile을 갱신해야 할 수는 있다. 다만 그때도 이유는 “오류가 나서”가 아니라 “package.json 변경을 반영해야 해서”처럼 설명되어야 한다.

마지막에는 지운 파일보다 확인 명령을 남긴다

수정 뒤에는 아래 순서로만 확인한다.

git diff -- package.json package-lock.json
npm ci
npm run build

npm ci가 통과하고 빌드가 통과하면 lockfile과 실제 프로젝트 상태가 맞아졌다는 근거가 생긴다. 아직 실패한다면 GitHub Actions 로그를 읽는 순서처럼 실패 위치를 다시 좁힌다. 배포 환경의 Node 버전 차이나 CI 설정 문제일 수도 있으므로 lockfile만 계속 지우면 원인이 가려질 수 있다.

오늘 기준은 간단하다. AI가 npm 오류를 고치자고 해도 바로 삭제하지 않는다. 먼저 git diff로 변경 파일을 보고, npm ci로 lockfile을 검증하고, 충돌 패키지 이름과 요구 버전을 AI에게 좁혀 묻는다. package-lock.json은 마지막에 지우는 선택지이지, 첫 번째 반응이 아니다.

참고 출처

• npm Docs, package-lock.json: https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json/
• npm Docs, npm ci: https://docs.npmjs.com/cli/commands/npm-ci/
• npm Docs, npm install: https://docs.npmjs.com/cli/install/

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.