Claude Code로 안전하게 의존성 관리하기: npm, pnpm, Yarn, CI

의존성 관리는 최신화가 아니라 운영 규칙이다

JavaScript/TypeScript 프로젝트는 직접 작성한 코드보다 의존 패키지 변화가 더 빠를 때가 많습니다. React, Vite, TypeScript, ESLint, 테스트 도구, UI 라이브러리, 결제 SDK, 빌드 플러그인까지 합치면 작은 앱도 금방 수백 개의 간접 의존성을 갖게 됩니다.

Claude Code를 이 작업에 쓰는 이유는 npm install package@latest를 대신 입력하게 하려는 것이 아닙니다. 더 안전한 방식은 현재 패키지 매니저와 lockfile을 확인하고, 업데이트를 patch/minor/major로 나누고, 보안 감사 결과를 분류하고, Renovate나 Dependabot PR을 검토하게 만드는 것입니다.

lockfile은 실제 설치된 패키지 버전과 무결성 정보를 고정하는 파일입니다. npm은 package-lock.json, pnpm은 pnpm-lock.yaml, Yarn은 yarn.lock을 사용합니다. package.json은 허용 범위이고, lockfile은 실제 결과입니다. CI는 이 결과가 재현되는지 확인해야지, 실행 중에 lockfile을 고치면 안 됩니다.

CI 전반은 Claude Code CI/CD 설정과 함께 보면 좋고, workspace를 쓴다면 pnpm workspace 가이드가 이어지는 글입니다.

---

Claude Code에 맡길 작업 흐름

의존성 업데이트는 다음 흐름으로 나누면 사고가 줄어듭니다.

flowchart LR
  scan["검사\noutdated / audit"] --> plan["계획\npatch / minor / major"]
  plan --> pr["업데이트 PR\nRenovate / Dependabot"]
  pr --> ci["CI\ninstall / test / build"]
  ci --> review["Claude Code 리뷰\n위험과 증거"]
  review --> merge["사람의 판단\nmerge 또는 반려"]

첫 요청은 수정이 아니라 조사여야 합니다.

claude -p "
Inspect dependency management in this repository. Do not edit files yet.
Report package manager, lockfile, outdated direct dependencies,
security audit command, scripts that must pass, and risky major updates.
Return file paths and exact commands.
"

Do not edit files yet가 중요합니다. Claude Code가 먼저 저장소의 상태를 읽고, 어떤 명령을 실행해야 하는지 설명하게 해야 합니다. 초보자에게는 “부품을 교체하기 전에 현재 장비와 위험 부품을 목록화하는 과정”이라고 이해하면 됩니다.

---

npm, pnpm, Yarn 차이

패키지 매니저를 섞으면 lockfile과 CI 결과가 흔들립니다. 저장소 하나에는 하나의 도구를 명확히 쓰는 것이 좋습니다.

도구	lockfile	CI 설치 명령	오래된 의존성 확인	보안 감사
npm	package-lock.json	npm ci	npm outdated	npm audit --audit-level=high
pnpm	pnpm-lock.yaml	pnpm install --frozen-lockfile	pnpm outdated --format table	pnpm audit --audit-level high
Yarn modern	yarn.lock	yarn install --immutable	yarn up -i 또는 yarn up <pattern>	yarn npm audit --recursive --severity high

npm 공식 문서는 npm ci를 CI나 배포 같은 자동 환경용 명령으로 설명하며, package.json과 lockfile이 맞지 않으면 실패한다고 설명합니다. pnpm의 --frozen-lockfile, Yarn의 --immutable도 같은 목적입니다. 업데이트 PR에서 lockfile을 바꾸고, CI에서는 그 lockfile이 그대로 재현되는지 확인합니다.

---

바로 쓸 수 있는 검증 스크립트

다음 파일을 scripts/verify-deps.mjs로 저장합니다. 패키지 매니저를 감지하고, 고정 설치, high 이상 보안 감사, typecheck, test, build를 실행합니다.

#!/usr/bin/env node
import { existsSync, readFileSync } from "node:fs";
import { spawnSync } from "node:child_process";

function readPackageJson() {
  return JSON.parse(readFileSync("package.json", "utf8"));
}

function detectPackageManager(pkg) {
  const declared = pkg.packageManager || "";
  if (declared.startsWith("pnpm@")) return "pnpm";
  if (declared.startsWith("yarn@")) return "yarn";
  if (declared.startsWith("npm@")) return "npm";
  if (existsSync("pnpm-lock.yaml")) return "pnpm";
  if (existsSync("yarn.lock")) return "yarn";
  if (existsSync("package-lock.json")) return "npm";
  throw new Error("No package manager or lockfile detected.");
}

function run(command, args) {
  const label = [command, ...args].join(" ");
  console.log(`\n$ ${label}`);
  const result = spawnSync(command, args, {
    stdio: "inherit",
    shell: process.platform === "win32",
  });
  if (result.status !== 0) throw new Error(`Command failed: ${label}`);
}

const pkg = readPackageJson();
const manager = detectPackageManager(pkg);

const installCommands = {
  npm: ["npm", ["ci"]],
  pnpm: ["pnpm", ["install", "--frozen-lockfile"]],
  yarn: ["yarn", ["install", "--immutable"]],
};

const auditCommands = {
  npm: ["npm", ["audit", "--audit-level=high"]],
  pnpm: ["pnpm", ["audit", "--audit-level", "high"]],
  yarn: ["yarn", ["npm", "audit", "--recursive", "--severity", "high"]],
};

const scriptCommands = {
  npm: (name) => ["npm", ["run", name]],
  pnpm: (name) => ["pnpm", ["run", name]],
  yarn: (name) => ["yarn", ["run", name]],
};

run(...installCommands[manager]);
run(...auditCommands[manager]);

for (const name of ["typecheck", "test", "build"]) {
  if (pkg.scripts?.[name]) run(...scriptCommands[manager](name));
  else console.log(`\n- skip ${name}: script not found`);
}

console.log(`\nDependency verification passed with ${manager}.`);

package.json에는 이렇게 연결합니다.

{
  "scripts": {
    "deps:verify": "node scripts/verify-deps.mjs"
  }
}

핵심은 업데이트 명령을 자동화하는 것이 아니라 검증 명령을 표준화하는 것입니다. Claude Code, Renovate, Dependabot, 사람이 만든 변경 모두 같은 검증을 통과해야 합니다.

---

세 가지 유스케이스

첫 번째는 작은 웹 앱의 개발 도구 업데이트입니다. ESLint, Prettier, Vite 플러그인, 테스트 도구의 patch/minor는 한 PR로 묶어도 됩니다. 단, major는 빼야 합니다.

claude -p "
Prepare a dependency update plan for devDependencies only.
Group patch and minor updates for lint/test/build tools.
Do not update major versions.
Run the dependency verification script after changes.
"

두 번째는 보안 취약점 대응입니다. audit fix --force부터 실행하면 major 업데이트가 들어와 API가 바뀔 수 있습니다. 먼저 JSON 보고서를 보고 직접 의존성인지, 간접 의존성인지, lockfile 갱신만으로 충분한지 분류해야 합니다.

npm audit --json
pnpm audit --json
yarn npm audit --recursive --json

세 번째는 workspace와 monorepo입니다. packages/ui가 apps/web을 import하기 시작하면 의존 방향이 깨집니다. 내부 패키지는 workspace:*를 쓰는지, React나 TypeScript 버전이 중복되는지 확인해야 합니다.

claude -p "
Inspect this workspace before dependency updates.
Find packages/* importing from apps/*, internal dependencies not using workspace:*,
duplicated versions of react/typescript/eslint, and scripts that should use filters.
Do not edit files.
"

---

Renovate와 Dependabot 설정

Renovate는 규칙을 세밀하게 나누고 싶을 때 좋습니다. 아래 설정은 major 업데이트를 수동 리뷰 대상으로 남기고, 개발 도구의 patch/minor는 CI 통과 후 자동 병합할 수 있게 합니다.

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "dependencyDashboard": true,
  "lockFileMaintenance": {
    "enabled": true,
    "schedule": ["before 5am on monday"],
    "automerge": true
  },
  "packageRules": [
    {
      "matchManagers": ["npm"],
      "matchDepTypes": ["devDependencies"],
      "matchUpdateTypes": ["patch", "minor"],
      "automerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "labels": ["dependency", "major-update"],
      "automerge": false
    }
  ]
}

GitHub만으로 시작하려면 Dependabot 설정도 충분합니다.

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    groups:
      dev-tooling:
        dependency-type: "development"
        update-types:
          - "minor"
          - "patch"

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "monthly"

GitHub Actions 자체도 업데이트 대상으로 넣어야 합니다. actions/setup-node나 actions/checkout이 오래된 채로 남으면 의존성 PR의 검증 환경도 낡습니다.

---

CI 검증

name: dependency-check

on:
  pull_request:
  push:
    branches: [main]

jobs:
  verify-dependencies:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: corepack enable
      - run: node scripts/verify-deps.mjs

처음에는 캐시보다 재현성을 우선하세요. 캐시는 빠르지만, 의존성 문제를 조사할 때 낡은 캐시가 원인을 가릴 수 있습니다.

---

자주 발생하는 실패

첫째, CI에서 npm install을 쓰는 실수입니다. npm ci를 써야 lockfile 불일치가 실패로 드러납니다. 둘째, audit fix --force를 기본 해결책으로 쓰는 실수입니다. 셋째, 여러 major 업데이트를 한 PR에 묶는 실수입니다. 넷째, package.json만 보고 lockfile diff를 보지 않는 실수입니다. 다섯째, 개발 의존성과 운영 의존성을 같은 위험도로 보는 실수입니다.

콘텐츠 사이트라면 MDX, CSS, 빌드 도구 업데이트가 코드 블록, CTA, 광고 영역을 깨뜨릴 수도 있습니다. 공개 전 확인은 검증 영수증 워크플로가 도움이 됩니다.

---

PR 리뷰 프롬프트

claude -p "
Review this dependency update PR.
Focus on package.json, lockfile, CI config, and test output.
Report updated packages, direct vs transitive changes, major updates,
peer dependency changes, commands that passed or failed, and manual checks.
Do not change files unless there is a blocking issue.
"

좋은 리뷰는 “괜찮아 보임”이 아니라 증거를 남깁니다. 무엇이 바뀌었고, 무엇이 통과했으며, 사람이 무엇을 봐야 하는지 적어야 합니다.

---

참고 자료와 다음 단계

공식 문서는 npm ci, npm audit, pnpm install, pnpm audit, yarn install, yarn npm audit, Claude Code CLI, Dependabot options, Renovate automerge를 확인하세요.

팀에서 이 흐름을 실제 저장소에 맞추려면 CLAUDE.md 베스트 프랙티스와 Claude Code 보안 감사를 함께 정리하세요. 운영 규칙까지 만들고 싶다면 교육 및 상담이 다음 단계입니다.

실제로 적용해 본 결과

Node.js 22, npm, pnpm, modern Yarn 기준으로 이 흐름을 정리했습니다. 가장 효과가 컸던 부분은 업데이트 생성과 검증을 분리한 것입니다. Claude Code는 계획과 리뷰에 강하지만, 최종 판단은 deps:verify와 lockfile diff를 기준으로 해야 합니다. major 업데이트를 자동 병합에서 제외하자 실패 원인 추적도 훨씬 쉬워졌습니다.