Next.js Agent Skill과 Turbopack 모듈 그래프로 클라이언트 JS 번들 줄이는 방법
next-bundle-optimizer로 정적 import 누수를 찾고 수정 전후 스냅샷으로 검증하는 절차

핵심 요약
- Next.js 16.4에 도입된 next-bundle-optimizer Agent Skill은 Turbopack의 모듈 그래프를 에이전트에게 제공해, 사람이 찾기 힘든 정적 import 누수와 중복 의존성을 자동으로 찾아낸다.
- 가장 흔하고 효과가 큰 수정 패턴은 next/dynamic이나 React.lazy()로 감싼 무거운 컴포넌트에서 상수·유틸리티를 함께 정적 import해 지연 로딩이 깨진 사슬을 분리하는 것이다.
- 에이전트에게 수정을 맡길 때는 반드시 수정 전 스냅샷 저장 → 코드 수정 → 수정 후 스냅샷 비교 순서를 강제해 실제 초기 JS 전송량이 몇 KB 줄었는지 수치로 확인해야 한다.
웹 애플리케이션에 기능을 계속 추가하다 보면 어느 순간 초기 로딩에 내려받는 클라이언트 JavaScript 번들 크기가 수 메가바이트까지 불어난다. 기존의 시각적 트리맵(@next/bundle-analyzer)은 어떤 패키지가 큰지는 보여주지만, '수백 개의 파일 중 대체 어느 import 경로 때문에 이 무거운 모듈이 초기 청크에 딸려 들어왔는지' 역추적하는 일은 여전히 사람의 수작업에 의존했다. 이 글은 2026년 10월 28일 Next.js 팀이 공개한 next-bundle-optimizer Agent Skill과 Turbopack 모듈 그래프를 연결해, 코딩 에이전트가 번들 비대화 원인을 자동 진단하고 스냅샷 비교로 검증하는 절차를 다룬다.
10월 28일 공개된 Next.js Agent Skill: 에이전트에게 Turbopack 모듈 그래프를 쥐여주다
Frontend Newsletter 11월 1일호와 Next.js 공식 발표(Ship less JavaScript in Next.js with your AI agent)에 따르면, Next.js 16.4 이상 환경에서 동작하는 next-bundle-optimizer 스킬은 Turbopack이 생성하는 정밀한 모듈 그래프(Module Graph)와 청크 스냅샷(JSON)을 AI 코딩 에이전트가 직접 읽고 쿼리할 수 있게 해준다.
기존 Next.js Core Web Vitals(LCP·INP·CLS) 지표 진단 가이드가 브라우저에 나타난 결과 지표를 보고 원인을 좁혀가는 방법이었다면, 이 스킬은 빌드 산출물의 의존성 그래프 자체를 에이전트에게 넘겨 원인 발견 → 코드 리팩토링 → 재빌드 후 바이트 단위 비교까지 자동화하는 워크플로우다.
에이전트가 모듈 그래프에서 집중적으로 찾아내는 3가지 병목 패턴
사람이 눈으로 찾기 힘들지만 next-bundle-optimizer 스킬이 Turbopack 그래프를 순회하며 정확히 짚어내는 대표적인 문제는 다음 세 가지다.
- Lazy Loading(
next/dynamic/React.lazy)을 무력화하는 숨은 정적 Import: 특정 화면에서 무거운 에디터나 차트 컴포넌트를dynamic(() => import('./HeavyChart'))로 분리해 두었더라도, 같은 라우트에 포함된 다른 유틸리티 파일이나 배럴 파일(index.ts)이HeavyChart.tsx안의 작은 상수나 타입 하나를 정적import하고 있으면 번들러는 결국 전체 모듈을 초기 청크에 포함시킨다. - 중복된 의존성(Duplicate Dependencies)과 구버전 패키지 혼입:
서드파티 라이브러리가 각기 다른 메이저 버전의
date-fns,lodash, 아이콘 세트를 참조해 동일 기능의 코드가 클라이언트 번들에 두세 번 중복 포함되는 지점을 찾아낸다. - Tree-shaking 실패 지점과 서버/클라이언트 경계 누수:
"use client"가 파일 최상단에 너무 넓게 선언되어 서버 컴포넌트에 남아 있을 수 있는 마크다운 파서나 스키마 검증기까지 클라이언트 번들로 넘어간 경로(Next.js 서버·클라이언트 컴포넌트 경계 설계 참고)를 추적한다.
실제로 Vercel 내부 팀은 이 에이전트 스킬을 v0와 vercel.com 프로덕션 저장소에 실행해, lazy() 래퍼를 우회하던 정적 import 사슬을 끊어내는 것만으로 압축 기준 약 2MB에 달하는 클라이언트 JavaScript를 제거하거나 지연 로딩으로 전환했다고 보고했다.
실습: 내 Next.js 프로젝트에 스킬을 설치하고 번들 전후 스냅샷 비교하기
Next.js 16.4 이상 및 Turbopack이 적용된 프로젝트에서 next-bundle-optimizer 스킬을 설치해 실제로 번들을 줄이는 4단계 절차다.
1단계: 사전 버전 확인 및 next-bundle-optimizer 스킬 설치
먼저 프로젝트가 Next.js 16.4 이상(보안 패치 포함 시 16.4.5 권장)인지 확인한 뒤, skills CLI로 공식 스킬을 설치한다.
# 1. Next.js 최신 16.4.x 확인 후 공식 번들 최적화 스킬 추가
npx skills add vercel/next.js --skill next-bundle-optimizer
# 2. 스킬 파일 설치 확인
ls -la .claude/skills/next-bundle-optimizer/SKILL.md
2단계: 에이전트에서 진단 리포트 생성 (/next-bundle-optimizer)
Claude Code나 Cursor 등 Agent Skills를 지원하는 에이전트 창에서 스킬을 호출해 먼저 코드를 고치지 않고 진단 리포트와 베이스라인 스냅샷만 뽑도록 지시한다.
# 진단 모드 실행 (코드 수정 없이 모듈 그래프 분석 및 Top 5 감량 타깃 도출)
/next-bundle-optimizer
대상 라우트는 /dashboard 와 /editor 두 곳이야.
현재 클라이언트 JS 청크 스냅샷을 저장하고, 초기 번들 크기를 가장 많이 차지하는 상위 5개 원인과 import 경로 사슬을 표로 정리해줘.
3단계: 정적 Import 사슬 분리 및 컴포넌트 경계 수정 (/next-bundle-optimizer fix)
리포트에서 확인된 항목 중 안전한 수정 대상을 지정해 리팩토링을 수행하게 한다. 예를 들어 무거운 코드 에디터 모듈에서 상수만 빼내 별도 파일로 분리하는 전형적인 수정 코드는 다음과 같다.
// ❌ 수정 전: components/CodePreviewModal.tsx (dynamic import를 썼지만 정적 import가 섞인 상태)
"use client";
import dynamic from "next/dynamic";
// 아래 한 줄의 정적 import 때문에 Monaco 관련 무거운 의존성이 초기 번들에 딸려 들어옴!
import { DEFAULT_EDITOR_THEME } from "./MonacoEditorCore";
const MonacoEditorCore = dynamic(() => import("./MonacoEditorCore"), {
ssr: false,
});
// ✅ 수정 후: 상수/타입을 경량 파일(editor-constants.ts)로 분리해 지연 로딩 복원
"use client";
import dynamic from "next/dynamic";
import { DEFAULT_EDITOR_THEME } from "./editor-constants";
const MonacoEditorCore = dynamic(() => import("./MonacoEditorCore"), {
ssr: false,
});
4단계: 수정 전후 스냅샷 및 Lighthouse 지표 대조
코드가 변경되면 에이전트는 다시 Turbopack 분석기를 실행해 이전 스냅샷 JSON과 새 스냅샷 JSON을 비교한다.
| 비교 항목 | 확인 위치 | 판단 기준 |
|---|---|---|
| 라우트별 초기 전송 JS | 수정 전후 스냅샷 | 대상 라우트의 Initial JS가 실제로 줄었는가 |
| 공유 청크에 포함된 모듈 수 | Turbopack 모듈 그래프 | 무거운 모듈이 지연 청크로 옮겨졌는가 |
| 모바일 TBT(Total Blocking Time) | Lighthouse | 같은 조건에서 여러 번 측정해 중앙값을 비교했는가 |
감소 폭은 프로젝트마다 다르므로 수정 전 베이스라인을 직접 측정하고, 수정 후 값과 함께 PR 설명에 남긴다.
주의점: 에이전트가 제안한 번들 최적화를 그대로 믿지 않고 검증하는 절차
에이전트는 바이트 수치를 줄이는 데 집중하기 때문에, 때로는 사용자 경험(UX)이나 런타임 안정성을 해치는 과격한 코드 분할을 제안할 수 있다. 따라서 PR을 머지하기 전에 반드시 다음 세 가지를 스냅샷과 브라우저에서 교차 검증해야 한다.
- 초기 화면(Above the Fold) 컴포넌트의 과도한
dynamic분리 경계: 페이지에 접속하자마자 바로 보여야 하는 헤더나 히어로 영역까지ssr: false동적 임포트로 바꾸면 JS 크기는 줄어들지 몰라도 화면이 깜빡이거나 LCP(Largest Contentful Paint)와 CLS 지표가 오히려 나빠진다. - 스냅샷 Diff에서 총합(Total)이 아닌 초기 로드(Initial Load) 확인: 청크만 잘게 쪼개지고 페이지 진입 시 결국 그 청크들을 동시에 다 받아온다면 실제 네트워크 이득은 없다. 스냅샷 비교에서 해당 라우트의 Initial JS 크기가 실제로 줄었는지 확인한다.
- 배럴 파일(
index.ts) 제거 후 외부 패키지 import 경로 깨짐 확인: 모노레포 내부 공용 UI 패키지의index.ts를 쪼갰을 때 다른 앱의 빌드가 깨지지 않는지 전체 워크스페이스 타입 체크(tsc --noEmit)를 돌린다.
초보자가 자주 실수하는 포인트
- 모든 컴포넌트를 dynamic()으로 감싸면 좋다고 생각하는 실수: 작은 버튼이나 텍스트 컴포넌트까지 동적 청크로 쪼개면 HTTP 요청 수만 늘어나고 번들 로더 오버헤드가 커진다. 모달, 차트, 리치 텍스트 에디터처럼 초기 화면에 보이지 않거나 용량이 큰 모듈에만 적용해야 한다.
- 아이콘 라이브러리나 유틸리티를 루트 경로에서 통째로 가져오는 습관: Next.js의 optimizePackageImports가 많은 패키지를 자동 처리해 주지만, 자체 제작한 사내 배럴 파일(src/components/index.ts)은 모듈 그래프를 한 덩어리로 묶어버리는 주범이 되므로 직접 파일 경로로 import하는 편이 안전하다.
체크리스트
- 프로젝트가 Next.js 16.4 이상이며 Turbopack 기반으로 빌드/분석이 실행되는가?
- 코드 수정 전에 /next-bundle-optimizer로 베이스라인 스냅샷을 먼저 생성했는가?
- 에이전트가 dynamic(..., { ssr: false })를 추가한 컴포넌트가 검색 엔진 색인(SEO)이나 초기 LCP 영역에 해당하지 않는지 확인했는가?
- 수정 후 생성된 스냅샷 비교표에서 라우트별 Initial JS 크기 감소와 E2E 렌더링 정상 동작을 모두 확인했는가?
자주 묻는 질문
아직 Webpack 설정(--webpack)을 유지 중인 Next.js 프로젝트에서도 이 스킬을 쓸 수 있나요?
next-bundle-optimizer 스킬의 핵심 진단 기능은 Turbopack이 출력하는 모듈·청크 그래프를 기반으로 동작한다. Webpack 빌드에서의 지원 범위는 스킬 문서를 먼저 확인한다.
CI 파이프라인에 이 스킬을 붙여서 번들 크기가 커지면 PR을 자동으로 막을 수 있나요?
스킬 문서에서 비대화형 실행 방법을 확인한 뒤 구성한다. CI에서는 에이전트가 코드를 직접 고치게 하기보다, 헤드리스 모드로 스냅샷 비교만 실행해 특정 라우트의 Initial JS가 기준치(예: +20KB) 이상 증가했을 때 어떤 import 경로 때문인지 PR 코멘트로 리포트를 남기도록 구성하면 효과적이다.
참고 자료 · 검증 기준
- Next.js Blog - Ship less JavaScript in Next.js with your AI agent
- Frontend Digest (Nov 1, 2026) - Next.js Agent Skill & Bundle Optimization
위 자료와 내용을 대조한 날짜: . 도구·서비스 정책은 이후 바뀔 수 있으므로 적용 전 공식 문서를 다시 확인하세요.
이 글은 실제 실무 환경 테스트 및 검증된 기술 자료를 바탕으로 작성되었으며, 환경 변화에 따라 지속적으로 갱신됩니다.