next-upgrade

next-upgrade 스킬 개요

next-upgrade가 하는 일

next-upgrade 스킬은 기억에 의존해 추측하는 대신, 공식 마이그레이션 가이드와 codemod를 기준으로 실제 Next.js 프로젝트를 더 최신의 메이저 버전으로 업그레이드하도록 에이전트를 돕습니다. 역할은 매우 실무적입니다. 현재 앱의 next 버전을 확인하고, 가장 안전한 업그레이드 경로를 정한 뒤, 먼저 맞는 codemod를 적용하고, 그다음 의존성을 업데이트하며, 마지막으로 수동 수정이 필요한 breaking change를 점검합니다.

어떤 경우에 next-upgrade 스킬을 써야 하나요

이 스킬은 기존 Next.js 코드베이스를 유지보수하는 개발자가, 공식 가이드에서 벗어나지 않으면서 AI 어시스턴트에게 업그레이드 계획 수립이나 실행을 맡기고 싶을 때 가장 적합합니다. 특히 아래와 같은 경우에 유용합니다.

• 프로젝트가 이미 한 개 이상의 메이저 버전 뒤처져 있을 때
• 일반적인 체크리스트가 아니라 repo 맥락을 반영한 업그레이드 계획이 필요할 때
• 버전별 codemod와 의존성 정렬 포인트를 함께 짚어야 할 때
• 브라우저용 요약이 아니라 Code Editing 워크플로 안에서 지원이 필요할 때

실제로 해결하려는 문제

대부분의 사용자는 “Next.js 업그레이드 정보” 자체가 필요한 것이 아닙니다. 지금은 정상 동작하는 앱을 기준으로, 라우팅, React 호환성, 빌드 결과물, 런타임 API를 망가뜨리지 않고 더 새로운 Next.js 버전으로 옮기는 것이 진짜 목적입니다. next-upgrade 스킬은 바로 그 판단과 실행 경로에 맞춰져 있습니다.

일반 프롬프트와 다른 점

일반 프롬프트는 넓은 범위의 업그레이드 조언을 제시할 수 있습니다. 반면 next-upgrade는 더 좁고, 그래서 실무적으로 더 유용합니다. 구조 자체가 다음 순서를 중심으로 잡혀 있기 때문입니다.

• 먼저 package.json을 읽기
• 목표 버전에 맞는 공식 Next.js 업그레이드 가이드 확인하기
• 메이저 버전 점프를 단계적으로 처리하기
• 수동 수정 전에 공식 codemod를 우선 적용하기
• next, react, react-dom 업그레이드를 올바르게 묶어서 진행하기

이 스킬이 대신해주지 않는 것

이 스킬이 검증 과정 자체를 없애주지는 않습니다. 코드 변경과 의존성 업데이트 방향은 안내할 수 있지만, 최종적으로는 직접 앱 실행, 테스트, lint, 빌드 검증을 해야 합니다. 또한 monorepo, 특이한 번들러 통합, 서버/런타임 동작을 깊게 패치한 환경처럼 커스텀이 많은 구성에서는 프레임워크별 이해를 완전히 대체하지도 못합니다.

next-upgrade 스킬 사용 방법

next-upgrade 설치 맥락

업그레이드하려는 저장소 안에서 호출할 수 있도록, AI 코딩 환경에 이 스킬을 설치하면 됩니다. 일반적인 설치 방식은 다음과 같습니다.

npx skills add https://github.com/vercel-labs/next-skills --skill next-upgrade

이미 사용 중인 환경이 vercel-labs/next-skills의 GitHub 스킬을 노출하고 있다면, next-upgrade를 바로 호출하기만 해도 되는 경우가 있습니다.

실무에서 next-upgrade를 호출하는 방법

저장소에는 인자 힌트로 [target-version]이 표시되어 있으므로, 원하는 버전을 명시적으로 주는 것이 가장 깔끔합니다. 예를 들면:

• Use next-upgrade for Next.js 16
• Run next-upgrade targeting v15
• Apply the next-upgrade skill to move this app from 13 to 15 incrementally

아직 목표 버전을 정하지 못했다면, 먼저 계획부터 요청하세요.

• Use next-upgrade to inspect this repo and recommend the safest target version

스킬이 필요로 하는 입력

next-upgrade는 에이전트가 아래 항목을 확인할 수 있을 때 가장 잘 동작합니다.

• package.json
• package-lock.json, pnpm-lock.yaml, yarn.lock 같은 lockfile
• 앱이 monorepo 안에 있다면 workspace 설정
• 앱 디렉터리 구조, 특히 app/를 쓰는지 pages/를 쓰는지
• 업그레이드 검증에 사용하는 CI 또는 빌드 명령

최소한 아래 정보가 있으면 유용합니다.

• 현재 Next.js 버전
• 패키지 매니저
• 원하는 목표 버전
• 계획만 필요한지, 실제 코드 수정까지 원하는지

모호한 요청을 강한 next-upgrade 프롬프트로 바꾸기

약한 프롬프트:

• Upgrade my app

더 나은 프롬프트:

• Use next-upgrade to inspect package.json, determine the current Next.js version, upgrade this project to Next.js 15 using official migration guides, run the relevant @next/codemod transforms first, then update next/react/react-dom together and summarize any manual follow-up changes.

repo 구성이 복잡할 때 가장 좋은 프롬프트:

• Use next-upgrade for Code Editing on this monorepo app in apps/web. Read apps/web/package.json, identify the current next/react versions, plan the required incremental major upgrades to reach Next.js 16, apply official codemods where relevant, update dependencies with pnpm-compatible commands, and leave a checklist of manual verification steps for build, routing, and runtime APIs.

이렇게 구체적으로 쓰면 결과가 좋아집니다. 스킬 자체는 간결한 편이라, repo 경계, 패키지 매니저, 실행 범위 같은 정보는 프롬프트가 직접 채워줘야 하기 때문입니다.

수정 전에 권장되는 next-upgrade 워크플로

신뢰할 수 있는 next-upgrade usage 흐름은 다음과 같습니다.

1. package.json과 현재 의존성 버전 확인
2. 목표 버전 선택
3. 포함되는 각 메이저 단계별 공식 Next.js 업그레이드 가이드 확인
4. 수동 정리 전에 codemod 실행
5. next, react, react-dom 업데이트
6. lint, typecheck, 테스트, production build 실행
7. 가이드나 런타임 에러에서 드러난 남은 breaking change 수정

여러 버전 뒤처져 있다면 한 번에 건너뛰지 마세요. 13 -> 14 -> 15 -> 16처럼 분리된 업그레이드 단계로 처리하도록 에이전트에 요청하는 편이 안전합니다.

먼저 읽어볼 저장소 파일

우선 상위 저장소의 skills/next-upgrade/SKILL.md부터 보세요.

• https://github.com/vercel-labs/next-skills/tree/main/skills/next-upgrade

짧은 스킬이라 따로 살펴볼 보조 파일이 많지는 않습니다. 핵심 가치는 SKILL.md에 담긴 워크플로에 있습니다. 버전 감지, 공식 문서 조회, 단계적 업그레이드, codemod 우선 실행, 이후 의존성 업데이트라는 흐름이 명확하게 들어 있습니다.

이 스킬이 의존하는 공식 문서

이 스킬은 다음과 같은 공식 Next.js 업그레이드 리소스를 명시적으로 가리킵니다.

• codemods: https://nextjs.org/docs/app/guides/upgrading/codemods
• 버전별 가이드:
  • https://nextjs.org/docs/app/guides/upgrading/version-16
  • https://nextjs.org/docs/app/guides/upgrading/version-15
  • https://nextjs.org/docs/app/guides/upgrading/version-14

이 점은 도입 판단에서 중요합니다. next-upgrade의 품질은 결국 에이전트가 오래된 프레임워크 지식에 기대지 않고, 실제로 해당 가이드를 가져와 따르는지에 달려 있기 때문입니다.

codemod는 마지막이 아니라 먼저

next-upgrade guide의 강점 중 하나는 순서 설계입니다. 에이전트에게 공식 codemod를 초반에 실행하도록 지시합니다.
npx @next/codemod@latest <transform> <path>

스킬에서 예시로 드러나는 항목은 다음과 같습니다.

• next-async-request-api
• next-request-geo-ip
• next-dynamic-access-named-export

이 순서가 중요한 이유는, codemod가 의존성 업데이트 후 수작업으로 처리하는 것보다 반복적인 breaking change를 더 빠르고 안전하게 정리하는 경우가 많기 때문입니다.

명시적으로 요청해야 할 의존성 업데이트

next-upgrade를 사용할 때는 peer dependency를 함께 올리도록 요청하는 것이 좋습니다. 스킬도 다음 패턴을 중심에 둡니다.
npm install next@latest react@latest react-dom@latest

pnpm이나 yarn을 쓰더라도 핵심은 같습니다. 공식 가이드에서 별도 지시가 없는 한, next, react, react-dom은 함께 움직이는 묶음으로 취급해야 합니다.

Code Editing에서의 next-upgrade 활용

Code Editing에서는 next-upgrade가 계획만 내놓을 때보다, 에이전트가 파일을 직접 읽고 수정할 수 있을 때 훨씬 유용합니다. 잘 맞는 작업은 다음과 같습니다.

• package.json의 의존성 범위 업데이트
• codemod 명령 적용
• breaking change 영향이 있는 API 수정
• 수동 검토용 inline comment나 마이그레이션 요약 남기기

반대로, 저장소 파일이나 외부 문서에 접근할 수 없는 환경에서는 효용이 떨어집니다. 이 스킬의 장점은 repo inspection과 공식 가이드 조회가 결합될 때 가장 크게 나오기 때문입니다.

실무적 제약과 트레이드오프

체계적인 경로가 필요할 때 next-upgrade는 유용하지만, 몇 가지 한계는 예상해야 합니다.

• 모든 버전별 뉘앙스를 로컬에 내장하고 있지는 않으며, 실시간 가이드 조회를 전제로 함
• 고도로 커스텀된 인프라보다 표준적인 Next.js 앱에서 가장 강함
• 프로젝트별 테스트 자동화가 내장되어 있지 않음
• monorepo, 서브앱, 루트가 아닌 패키지 파일은 추가 프롬프트가 필요할 수 있음

즉, 이 스킬은 추측을 줄여주지만, 범위를 분명히 정의하는 일까지 대신해주지는 않습니다.

next-upgrade 스킬 FAQ

next-upgrade는 일반 업그레이드 프롬프트보다 더 나은가요?

대체로 그렇습니다. 반복 가능한 업그레이드 프로세스가 필요하다면 특히 그렇습니다. 일반 프롬프트는 그럴듯하지만 오래된 조언을 내놓기 쉽습니다. next-upgrade는 공식 마이그레이션 가이드, codemod, 그리고 프로젝트 파일 기반 버전 감지에 기준을 두고 있습니다.

next-upgrade 스킬은 초보자도 쓰기 쉬운가요?

네. 다만 한 가지 전제가 있습니다. 초보자라면 먼저 계획 모드로 사용하는 편이 좋습니다. 아래 항목을 요청해 보세요.

• 현재 버전 감지
• 목표 버전 추천
• 실행할 codemod
• 수동 수정 가능성이 높은 부분
• 검증 체크리스트

이렇게 하면 실제 수정 허용 전에 결과를 검토하기가 훨씬 쉬워집니다.

목표 버전을 먼저 알아야 하나요?

아니요. next-upgrade에게 repo를 점검하고 가장 안전한 목표 버전을 추천해 달라고 요청할 수 있습니다. 다만 플랫폼 제약이나 특정 의존성 사유로 꼭 필요한 버전이 이미 정해져 있다면, 처음부터 목표를 주는 편이 더 깔끔한 계획으로 이어집니다.

언제 next-upgrade를 쓰지 않는 편이 좋나요?

다음 경우라면 next-upgrade는 건너뛰는 편이 낫습니다.

• 업그레이드가 아니라 새 앱을 만드는 중일 때
• 문제의 본질이 버전 마이그레이션과 무관할 때
• 공식 문서로 다뤄지지 않는 커스텀 내부 구현에 크게 의존할 때
• 정확한 버전 경로를 이미 알고 있고, 한 줄짜리 명령만 필요할 때

여러 메이저 버전을 한 번에 건너뛸 수 있나요?

가능은 하지만, 반드시 단계적으로 처리해야 합니다. 이 스킬은 무작정 한 번에 점프하는 방식보다 메이저 버전을 하나씩 밟는 접근을 분명히 선호합니다. 앱이 많이 뒤처져 있다면, 각 메이저 버전마다 체크포인트가 있는 단계별 계획을 요청하세요.

app router 프로젝트에서만 동작하나요?

아니요. 다만 가져오는 공식 가이드는 더 최신의 Next.js 패턴에 초점을 두는 경우가 있습니다. 코드베이스가 여전히 예전 관례를 많이 쓰고 있다면, 수정 전에 가이드 중 어떤 부분이 적용되고 어떤 부분은 해당하지 않는지 먼저 구분해 달라고 요청하는 것이 좋습니다.

next-upgrade 스킬 개선 방법

next-upgrade에 repo 경계를 더 명확히 알려주기

결과를 가장 빨리 개선하는 방법은 Next.js 앱이 정확히 어디에 있는지 에이전트에게 분명히 알려주는 것입니다. monorepo라면 다음을 구체적으로 지정하세요.

• apps/web 같은 앱 경로
• 패키지 매니저
• workspace 도구
• 수정 범위를 해당 앱 내부로만 제한할지 여부

이 정보가 없으면 스킬이 잘못된 package.json을 읽거나, 명령을 엉뚱한 레벨에서 제안할 수 있습니다.

2단계 출력으로 요청하기

강력한 패턴은 다음과 같습니다.

1. 계획만 먼저
2. 이후 수정 실행

예시:

• Use next-upgrade to first produce an upgrade plan with required codemods and risks. After I approve it, apply the changes.

이 방식은 의도치 않게 범위가 넓은 수정이 들어가는 일을 줄여주고, 운영 중인 코드베이스에서도 스킬을 더 신뢰할 수 있게 만들어 줍니다.

검증 기준을 더 구체적으로 주기

그냥 “성공적으로 업그레이드해줘”라고만 하지 마세요. 아래처럼 구체적인 명령으로 검증하라고 요청하는 편이 좋습니다.

• install
• lint
• typecheck
• unit tests
• production build

이렇게 해야 next-upgrade usage가 더 좋아집니다. 에이전트가 단순히 의존성 버전만 바꾸는 것이 아니라, 실제로 통과하는 repo 상태를 목표로 작업할 수 있기 때문입니다.

중요하게 보는 실패 유형을 명시하기

특정 회귀를 특히 피하고 싶다면, 그 점을 분명히 말하세요. 예를 들면:

• Prioritize route behavior and middleware compatibility
• Watch for request API changes introduced in newer Next.js versions
• Do not migrate unrelated code while applying next-upgrade

이런 제약은 막연한 “어떻게든 동작하게 해줘”보다 훨씬 더 좋은 수정 방향을 만들어냅니다.

codemod 선택 이유까지 요청하기

유용한 개선 프롬프트 예시는 다음과 같습니다.

• List which @next/codemod transforms apply to this repo and why before running them

이렇게 하면 에이전트가 codemod를 무분별하게 실행하는지, 아니면 실제 코드 패턴에 맞춰 선택하는지를 검토하기가 쉬워집니다.

next-upgrade에서 흔한 실패 패턴

결과가 약하게 나오는 전형적인 패턴은 다음과 같습니다.

• 현재 버전을 먼저 확인하지 않고 의존성부터 업그레이드함
• 중간 메이저 버전을 건너뜀
• codemod 검토 전에 수동 수정부터 시작함
• react와 react-dom 정렬을 무시함
• monorepo에서 루트 package.json이 곧 앱 패키지라고 가정함

이런 징후가 보이면 멈추고, 버전별 단계 계획부터 다시 요청하세요.

첫 결과 이후에는 어떻게 반복 개선할까

첫 번째 결과가 나온 뒤에는, 처음부터 다시 시작하기보다 실패한 지점에 맞춘 두 번째 패스를 요청하는 편이 낫습니다.

• Re-run next-upgrade analysis based on these build errors
• Compare the remaining errors against the official v15 guide
• Propose the smallest manual edits still needed after codemods

이 방식이 더 나은 이유는, 이 스킬이 한 번에 완벽히 끝내는 도구라기보다 마이그레이션 단계를 따라가도록 설계되어 있기 때문입니다.

더 좋은 next-upgrade 결과를 위한 최적 프롬프트 패턴

신호 대비 잡음이 적은 간결한 템플릿은 다음과 같습니다.

Use next-upgrade on <path>. Detect the current Next.js version from package.json, determine the correct incremental upgrade path to <target-version>, fetch the official migration guides for each step, identify and run the applicable @next/codemod transforms first, then update next/react/react-dom together. After edits, summarize breaking changes addressed, remaining manual follow-ups, and the exact verification commands I should run.

이 프롬프트는 next-upgrade skill이 일반적인 Code Editing 요청보다 실제로 더 나은 결과를 낼 수 있을 만큼 충분한 구조를 제공합니다.