dependency-update-plan

name	dependency-update-plan
description	의존 패키지 업데이트 영향을 분석하고, 안전한 업데이트 순서와 계획을 수립한다.
argument-hint	[project-dir|package-file] (선택: 특정 패키지명)
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob, Bash(npm outdated *), Bash(pip list *)

당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

목적

프로젝트의 의존 패키지 업데이트 현황을 분석하고, 업데이트로 인한 영향 범위·호환성 깨짐(브레이킹 체인지) 리스크·업데이트 우선순위를 평가한다.
안전한 업데이트 순서를 수립하고, 단계적으로 의존성을 최신 상태에 가깝게 만드는 계획을 작성한다.

입력

• 프로젝트 디렉터리 또는 패키지 관리 파일 경로 (필수)
• 선택: 특정 패키지명 (해당 패키지 중심 분석)
• 선택: 업데이트 목적 (보안 취약점 대응, 신규 기능 활용, 지원 종료(EOL) 대응 등)
• 선택: 업데이트를 피하고 싶은 패키지와 그 사유
• 정보가 부족하면 사용자에게 질문한다

절차

1. 의존성 현황 파악

   • 패키지 관리 파일을 Read로 확인:
     • Node.js: package.json, package-lock.json / yarn.lock / pnpm-lock.yaml
     • Python: pyproject.toml, requirements.txt, poetry.lock / Pipfile.lock
     • Go: go.mod, go.sum
   • 가능하다면 패키지 매니저로 업데이트 가능 패키지 확인:
     • npm outdated --json (Node.js)
     • pip list --outdated --format=json (Python)
   • 전체 의존 패키지 수, 직접 의존과 간접 의존 비율 파악

2. 업데이트 대상 분류 및 우선순위 설정

   • 업데이트 가능 패키지를 다음 기준으로 분류:
     • 보안 수정: 알려진 취약점(CVE)이 수정된 버전
     • 호환성 깨짐(메이저): API 변경이 포함된 메이저 버전 업
     • 기능 추가(마이너): 하위 호환성을 유지하는 기능 추가
     • 버그 수정(패치): 하위 호환성을 유지하는 버그 수정
   • 각 패키지의 우선순위를 다음 기준으로 평가:
     • 보안 리스크 존재 여부 (최우선)
     • 지원 종료(EOL) 또는 사용 중단(deprecated) 여부 (높은 우선순위)
     • 프로젝트 내 사용 범위 (넓을수록 신중)
     • 업데이트 리스크 (호환성 깨짐 규모)

3. 영향 범위 분석

   • 각 패키지가 프로젝트 어디에서 사용되는지 Grep으로 검색
   • import, require, from ... import 검색으로 직접 사용 위치 파악
   • 프로젝트에서 실제 사용하는 API 목록 정리
   • 메이저 업데이트의 경우, CHANGELOG에서 호환성 깨짐 내용 확인

4. 의존성 충돌 점검

   • 패키지 간 의존 관계 확인:
     • peer dependency 요구 사항
     • 버전 범위 제약 조건
     • 동일 패키지 다중 버전 공존 가능 여부
   • 연쇄적으로 업데이트가 필요한 패키지 식별
   • 잠금 파일(lock file) 재생성이 필요한 경우 파악

5. 안전한 업데이트 순서 수립

   • 다음 원칙에 따라 순서 결정:
     • 패치 → 마이너 → 메이저 순
     • 다른 패키지에 의존되는 패키지를 먼저 업데이트
     • 테스트 검증이 쉬운 패키지를 우선 업데이트
     • 보안 수정은 최우선
   • 한 번의 PR로 처리 가능한 단위로 그룹화
   • 각 그룹 업데이트 후 실행해야 할 테스트 및 검증 절차 명시

6. 업데이트 계획 문서화

   • 단계별 업데이트 일정 수립
   • 각 단계의 롤백(되돌리기) 절차 명시
   • Dependabot / Renovate 설정이 있다면 자동 업데이트 정책과 정합성 검토
   • 업데이트 후 점검 체크리스트 작성

출력 형식

## 의존성 현황

- **패키지 매니저**: [npm/yarn/pip/poetry/go mod]
- **직접 의존 수**: [N개]
- **간접 의존 수**: [N개 (확인 가능한 경우)]
- **업데이트 가능 패키지 수**: [N개]
- **잠금 파일(lock file)**: [있음/없음]

## 업데이트 대상 목록

| # | 패키지 | 현재 | 최신 | 유형 | 우선순위 | 리스크 |
|---|--------|------|------|------|----------|--------|
| 1 | [이름] | [현재 버전] | [최신 버전] | 보안 | P1 | 낮음 |
| 2 | [이름] | [현재 버전] | [최신 버전] | 메이저 | P2 | 높음 |
| 3 | [이름] | [현재 버전] | [최신 버전] | 마이너 | P3 | 낮음 |
| 4 | [이름] | [현재 버전] | [최신 버전] | 패치 | P3 | 낮음 |

# 영향 분석

### [패키지명1] (메이저 업데이트)

- **사용 위치**: [파일 수 및 주요 사용 패턴]
- **호환성 깨짐 내용**: [변경 사항 요약]
- **필요 수정 사항**: [수정이 필요한 코드와 내용]
- **예상 작업 시간**: [대략적인 소요 시간]

## 의존성 충돌

| 패키지 A | 패키지 B | 충돌 내용 | 해결 방안 |
|-----------|-----------|-----------|-----------|
| [이름] | [이름] | [충돌 내용] | [해결 방법] |

## 업데이트 계획

### 그룹 1: 보안 수정 (최우선)

- **대상**: [패키지 목록]
- **업데이트 명령어**: [실행 명령어]
- **검증 절차**: [테스트 및 확인 절차]
- **롤백 방법**: [되돌리는 방법]

### 그룹 2: 패치·마이너 업데이트 (저위험)

- **대상**: [패키지 목록]
- **업데이트 명령어**: [실행 명령어]
- **검증 절차**: [테스트 및 확인 절차]

### 그룹 3: 메이저 업데이트 (주의 필요)

- **대상**: [패키지 목록]
- **사전 준비**: [코드 수정, 테스트 보강 등]
- **업데이트 절차**: [단계별 실행 방법]
- **검증 절차**: [테스트 및 확인 절차]
- **롤백 방법**: [되돌리는 방법]

## 자동화 설정

- **Dependabot / Renovate**: [현재 설정 상태 및 권장 설정]
- **자동 병합 조건**: [패치 업데이트 자동 병합 기준]
- **업데이트 점검 주기**: [권장 주기]

## 업데이트 후 체크리스트

- [ ] 모든 테스트 통과
- [ ] 빌드 성공
- [ ] 잠금 파일이 정상적으로 갱신됨
- [ ] 타입 검사 및 린트 통과
- [ ] 핵심 기능 동작 확인 완료

보안 주의사항

• 실제 패키지 업데이트(npm install, pip install 등)는 실행하지 말고, 계획만 작성한다.
• npm outdated, pip list --outdated는 조회 전용 명령으로 안전하게 실행한다.
• 취약점의 구체적인 공격 방법은 포함하지 않는다 (CVE 번호와 요약만 기재).
• 잠금 파일 삭제·재생성은 계획에 포함할 수 있으나, 실행 여부는 사용자 판단에 맡긴다.
• 사설 레지스트리 인증 정보는 출력하지 않는다.
• 라이선스 변경이 있는 경우 경고한다.

종료 조건

위 출력 형식에 맞춘 의존성 업데이트 계획을 작성하면 종료한다. 업데이트 대상 목록(우선순위·리스크 포함), 영향 분석, 업데이트 순서, 그룹별 실행 절차, 체크리스트가 반드시 포함되어야 한다. 실제 패키지 업데이트는 사용자의 추가 지시를 기다린다.