@package.json 분석 클로드 코드 의존성 정리 명령어

@package.json 분석으로 Claude Code 의존성 정리하는 가장 안전한 방법

프로젝트가 커질수록 어느 날 갑자기 이런 생각이 듭니다.


“이 패키지… 우리가 아직 쓰고 있나?”


Claude Code로 작업하다 보면 답이 엉키거나 빌드가 느려지는 순간이 오는데, 그 원인의 상당수는 정리되지 않은 package.json에서 시작됩니다.


이 글은 package.json을 기준으로 Claude Code가 프로젝트를 정확히 이해하도록 만드는 의존성 정리의 현실적인 방법을 지금 기준 팩트로 풀어드립니다.

---

📚 목차

• 1. package.json의 진짜 역할
• 2. Claude Code가 의존성을 해석하는 방식
• 3. 반드시 알아야 할 의존성 정리 명령어
• 4. 안전하게 정리하는 순서
• 5. 자주 터지는 실수와 예방 팁

---

1️⃣ package.json의 진짜 역할

package.json은 단순한 라이브러리 목록이 아닙니다.


Claude Code 입장에서 보면 이 파일은 “프로젝트의 헌법”에 가깝습니다.


어떤 언어 환경인지, 어떤 도구를 쓰는지, 무엇이 핵심 의존성인지 모두 이 파일에서 판단합니다.


그래서 package.json이 더러우면 Claude의 추론도 같이 흐려집니다.

---

2️⃣ Claude Code가 의존성을 해석하는 방식

Claude Code는 dependencies와 devDependencies를 역할 중심으로 구분해 해석합니다.


문제는 쓰지 않는 패키지가 남아 있으면 “이걸 기반으로 코드가 있겠지”라고 추측을 시작한다는 점입니다.


이게 쌓이면 존재하지 않는 코드 기준으로 답을 만들어내는 현상이 발생합니다.


즉, 의존성 정리는 성능 문제가 아니라 정확도 문제입니다.

---

3️⃣ 반드시 알아야 할 의존성 정리 명령어

가장 기본이 되는 명령어는 이것입니다.


npm ls


현재 실제로 설치되어 어떤 패키지가 어디서 쓰이는지 트리 구조로 확인할 수 있습니다.


다음으로 중요한 건 npm prune입니다.


package.json에 없는데 node_modules에 남아 있는 찌꺼기를 안전하게 제거합니다.

---

4️⃣ 안전하게 정리하는 권장 순서

의존성 정리는 순서를 지키는 게 전부입니다.


① 실제 사용 여부 확인


② package.json에서 제거


③ install 재실행


이 순서를 지키면 Claude Code가 “없는 세계를 상상하는 일”을 원천 차단할 수 있습니다.


반대로 node_modules부터 지우면 지옥이 열립니다.

---

5️⃣ 가장 많이 터지는 실수와 예방 팁

가장 흔한 실수는 “빌드만 되면 됐다”는 생각입니다.


하지만 Claude Code는 빌드 성공 여부보다 의존성 선언 자체를 더 신뢰합니다.


또 하나는 devDependencies를 무작정 dependencies로 옮기는 경우입니다.


이러면 AI는 불필요한 도구까지 실행 환경으로 오해합니다.

---

🔗 이 글에 꼭 필요한 공식 자료

npm package.json 공식 문서

Claude Code 공식 페이지

---

의존성 정리는 정리벽 있는 사람만 하는 작업이 아닙니다.


Claude Code를 똑똑하게 쓰고 싶은 사람이라면 반드시 거쳐야 할 과정입니다.


package.json이 정리되는 순간, Claude의 답변도 확실히 달라집니다.