bundle-size-budget

번들 크기 예산 (Bundle Size Budget)

기능은 그대로 출시하되 클라이언트 번들은 부풀리지 않기 — size-limit 예산을 통과할 때까지 반복합니다.

이 루프는 언제 쓰나

기능을 더하다 보면 번들이 슬금슬금 무거워져서 초기 로딩이 느려지는데, "어디가 커졌나" 매번 빌드 결과를 직접 뒤지기 번거로울 때 씁니다. 한 번 시작하면 에이전트가 빌드 → 크기 측정 → 트림/lazy-load → 재측정을 스스로 반복하며 번들을 정한 예산 아래로 끌어내립니다. 핵심은 기능을 잘라내지 않고 무거운 모듈을 동적 import 하거나 미사용 의존성을 걷어내는 식으로 크기를 줄이는 것 — 정말 어쩔 수 없을 때만 기능 축소를 검토합니다.

루프 흐름

수동 시작 → 번들 측정 → 트림/lazy-load →〔피드백 게이트〕번들이 예산 이하?
                ↑                                          │ 아니오
                └──────────────────────────────────────────┘
                                                           │ 예
                                                         종료

매 반복(pass)마다 하는 일

1. 번들 측정 — 프로덕션 빌드와 번들 크기 체크를 돌립니다. 총 KB와 새로 커진 가장 큰 청크들을 보고합니다.

   npm run build && npm run size-limit
   

2. 트림 또는 lazy-load — 예산을 넘었으면: 무거운 모듈을 dynamic import 하거나, 미사용 의존성을 제거하거나, 라우트를 분할합니다. 정말 필요한 경우가 아니면 기능은 잘라내지 않습니다.

가드레일 (점수 조작 방지 규칙)

종료 조건을 "가짜로" 통과시키지 못하게 막는 규칙입니다. 반드시 지키세요.

• 체크 명령이나 종료 기준을 고쳐서 억지로 성공시키지 않는다.
• 체크를 건너뛰거나 비활성화·우회해서 종료 조건을 통과시키지 않는다.
• 여러 번 반복해도 막히면, 지표를 조작하지 말고 멈추고 블로커를 보고한다.

Claude Code에서 실행하기

가장 간단합니다. 아래 kickoff 프롬프트를 그대로 붙여넣으면 에이전트가 스스로 반복합니다.

"번들 크기 예산(Bundle Size Budget)" 루프를 시작합니다.

목표: 클라이언트 번들이 size-limit 예산 이하로 유지된다
최대 반복: 6
매 반복 사이 실행: npm run build && npm run size-limit
종료 조건: size-limit이 종료 코드 0으로 끝날 때

1단계: 빌드해서 번들 크기를 측정한다. 예산을 넘으면, size-limit이 통과할 때까지 무거운 모듈을 lazy-load 하거나 의존성을 줄인다.

이 루프를 스스로 페이싱(self-pace)하라. 매 반복 후 체크 명령을 실행하고 출력을 읽어, 종료
조건이 충족되지 않았을 때만 계속한다. 종료 조건이 통과하거나 최대 반복에 도달하면 멈춘다.
매 회차마다 한 줄 상태 업데이트를 남긴다.

전제: 프로젝트에 size-limit(또는 동등한 번들 예산 도구)이 설치·설정되어 있어야 하고, package.json에 build·size-limit 스크립트가 있어야 합니다. 예산 임계값은 .size-limit.json(또는 size-limit 설정)에서 정합니다.

팁 / 변형

• 체크 명령 교체: size-limit 외에도 생태계에 맞게 바꾸세요. Next.js는 @next/bundle-analyzer, Vite는 npx vite-bundle-visualizer, 범용으로는 npx bundlesize, npx source-map-explorer dist/**/*.js로 어떤 청크가 큰지 시각화할 수 있습니다.
• 무엇부터 줄일까: 측정 결과에서 가장 큰 의존성부터 봅니다. 무거운 차트·에디터·아이콘 세트는 라우트 단위 dynamic import로 미루고, moment→date-fns처럼 가벼운 대안으로 교체하고, tree-shaking이 안 되던 default import를 named import로 바꾸세요.
• 막힐 때: 단일 의존성 하나가 예산의 대부분을 차지해 기능을 줄이지 않고는 못 빼는 상황이면, 가드레일대로 멈추고 "이 의존성 때문에 막혔다"고 원인과 함께 사람에게 보고하게 하세요.
• 연관 루프: 빌드 자체가 깨질 때는 looping:build-until-green, 죽은 코드·미사용 의존성 정리는 looping:knip-until-clean, 의존성을 한 번에 하나씩 올리는 건 looping:dependency-upgrade-one-by-one.

Start the "Bundle Size Budget" loop.

Goal: client bundle stays under the size-limit budget
Max iterations: 6
Between iterations run: npm run build && npm run size-limit
Exit when: size-limit exits 0

Step 1: Build and measure bundle size. If over budget, lazy-load or trim deps until size-limit passes.

Self-pace this loop. After each iteration, run the check command, read the output, and only continue if the exit condition is not met. Stop when the exit condition passes or max iterations is reached. Give a short status update each pass.