Files
clean-architecture-frontend…/docs/operations/performance-evidence.md
T
DongHyeonka 8c7bcdaba5 docs(performance): 번들 기준선과 분류 규칙을 15-01 뒤 빌드에 맞춘다 (1101/15-02)
문제
docs/operations/performance-evidence.md는 다운스트림이 첫 기능 전에 예산을
정할 때 보는 유일한 자료다. 그런데 2026-09-25 측정을 그대로 적고 있다.
기준선 196,573 B(예산의 96%, 여유 약 8,200 B), "`index` 93.5 KB,
`preload-helper` 28.5 KB(zod 포함)", "dynamic import chunk는 lazy다".
verify:documentation은 수치를 보지 않아 통과한다.

문서와 코드 대조 (RED 대신)
- 298201f 빌드(build-frontend.ts, classifyViteJavascript + gzipSync 기본
  수준, check:bundle과 같은 계산): 초기 JS 16개 파일 202,509 B
  (VITE_BUILD_ID=local-build), 202,522 B(gitea-123456-1). 여유 약 2,280 B
- `index` 864 B, `preload-helper` 675 B. 문서의 청크 이름별 크기가 모두
  틀렸다
- 분류기(scripts/lib/classify-vite-bundle.ts)는 entry가 직접 dynamic
  import하는 boot·render-boot-failure도 초기로 센다. 문서 문장과 반대다

고른 방법
- 표를 현재 측정으로 바꾸고 측정 커밋(298201f)과 빌드 ID 조건을 적는다.
- 청크 이름 대신 출처별(react-dom·react-router·zod·@tanstack·react·
  템플릿 src) 크기를 적는다. sourcemap 빌드에서 minify 바이트를 원래 모듈에
  나눠 붙이고 묶음마다 gzip했다. rolldown이 공용 청크에 모듈 하나의 이름을
  붙여서 청크 이름으로 판단하면 엉뚱한 곳을 줄이게 된다는 설명을 둔다.
- 15-01 뒤 기능 하나의 증가량(참조 모양 +650~750 B, 298201f 커밋 측정)과
  그 상한 테스트를 적는다. 다운스트림이 "몇 개 더 들어가나"를 바로 본다.
- 분류 규칙 문장을 분류기와 맞춘다.

버린 대안
- check:bundle이 bundle.json에 출처별 합계를 남기게 자동화: 빌드마다
  sourcemap 빌드가 한 번 더 필요하다. 리뷰도 "가능하면"으로 적었고, 문서
  수치를 맞추는 이번 범위를 넘는다.

위험·한계
- 15-01 커밋 본문의 202,361 B와 이번 측정이 148 B 다르다. 같은 커밋의 빌드
  차이(빌드 정보·ID)로 보이나 원인은 확인하지 않았다.
- 출처별 표는 sourcemap 빌드(VITE_BUILD_ID=gitea-123456-1)에서 쟀다.
  sourceMappingURL 주석은 빼고 셌다.
- production 프로필 빌드와 pnpm 경로의 check:bundle(generate-supply-chain이
  pnpm list를 부른다)은 돌리지 않았다.

검증
- verify-documentation-readiness: PASS_SCOPED
- 다른 문서에 옛 수치(196,573, 96%, 8,200) 없음(git grep)

Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-02
2026-11-01 22:49:13 +09:00

6.2 KiB

Performance evidence contract

Performance evidence is deliberately split by measurement context:

  • bundle.json records production build output and enforces initial JavaScript at 200 KiB gzip and every lazy chunk at 120 KiB gzip.
  • lab.json records Chromium/runner/viewport/network/CPU/cache/build context and enforces LCP 2.5 s, CLS 0.10, and the named route interaction at 200 ms.
  • field-web-vitals.json records consent-filtered, route-ID aggregated, release-specific production samples over 28 days and evaluates p75 LCP, CLS, and INP against 2.5 s, 0.10, and 200 ms.

번들 예산의 기준선과 여유

리뷰 0925/13-14, 1101/15-02. 예산은 config/performance/budgets.json에 있고 scripts/check-bundle.ts(FE-GATE-012, merge 단계)가 강제한다. 템플릿 기본 화면만으로 초기 JS 예산의 98.9%를 쓴다. 첫 기능을 추가하기 전에 아래 숫자를 보고 예산을 정한다.

항목 값
초기 JS 예산 204,800 gzip bytes(200 KiB)
템플릿 기준선(2026-11-01, 커밋 298201f) 202,509202,522 gzip bytes, 16개 파일. local 프로필, VITE_BUILD_ID가 local-build일 때와 CI 모양(gitea-<run>-<attempt>)일 때다. 빌드 ID가 번들에 들어가므로 빌드마다 수십수백 바이트 다르다
여유 약 2,280 bytes(1.1%)
기능 하나를 더할 때 참조 기능 모양 복사본 하나에 약 +650~750 bytes(298201f 측정, 상한은 tests/unit/feature-shape-growth.test.ts의 1 KiB). 기능 실행부(feature-runtime.ts)는 라우트에 들어갈 때 받는 lazy chunk다
lazy chunk 예산 파일마다 122,880 gzip bytes(120 KiB). 기준선의 lazy JS는 17개, 합계 28,204 bytes이고 가장 큰 것은 use-reference-feature 8,386 bytes다

청크 이름으로 크기를 판단하지 않는다. rolldown은 공용 청크에 안에 든 모듈 하나의 이름을 붙인다. 예를 들어 render-boot-failure 청크(58.6 KB)의 대부분은 react-dom이고, design-system 청크(48.2 KB)에는 react-router가 들어 있다. 아래는 출처별 크기다. sourcemap 빌드에서 minify된 바이트를 원래 모듈에 나눠 붙이고 묶음마다 따로 gzip했다. 따로 압축하므로 합은 실제 합계와 조금 다르다.

출처 minify bytes 단독 gzip bytes
react-dom + scheduler 181,673 56,545
react-router 94,271 30,697
zod 70,512 18,607
@tanstack/* 24,751 7,286
react 7,869 2,961
그 밖의 npm(lucide-react) 2,329 1,142
템플릿 src 265,529 78,883

템플릿 src 중 큰 것은 src/contracts 17.8 KB, src/adapters/http 8.0 KB, src/presentation/i18n(문구 카탈로그) 7.6 KB, src/bootstrap 7.4 KB, src/presentation/design-system 5.1 KB다.

측정 조건:

  • 초기 파일은 Vite manifest의 entry, 그 static import, entry가 직접 dynamic import하는 chunk(boot, render-boot-failure)와 그 static import다 (scripts/lib/classify-vite-bundle.ts). entry는 앱 그래프의 평가 실패를 보고하려고 그 둘을 dynamic import로 읽을 뿐이고, 첫 화면에 항상 필요하다 (0925/09-03). 그 밖의 dynamic import chunk는 lazy다.
  • 합계는 JavaScript만 센다. CSS(index-*.css, 8.6 KB gzip)는 예산에 들어가지 않는다.
  • gzip은 Node zlib.gzipSync 기본 수준(6)으로 잰다 (scripts/lib/release-candidate.ts). 호스팅이 brotli로 보내면 전송 크기는 더 작다. 예산은 gzip 기준 그대로 둔다.
  • Node·pnpm·runner 이미지는 artifacts/performance/bundle.json의 context에 기록된다.

예산을 올릴 때는 이 표의 기준선과 새 측정값, 이유를 같은 변경에 적는다.

lab 측정(scripts/test-performance.ts, FE-GATE-026)은 local 프로필 build를 vite preview --strictPort로 띄워 잰다(리뷰 11-07).

  • 포트는 LAB_PERFORMANCE_PORT(기본 4173)다. 서버를 띄우기 전에 그 포트가 이미 응답하면 실패하고, 응답하는 /release-manifest.json의 build·release가 로컬 dist/release-manifest.json과 다르면 실패한다 (scripts/lib/lab-performance.ts, tests/unit/lab-performance.test.ts).
  • 새 브라우저 context에서 --runs=N(기본 5)번 재고, 예산은 중앙값으로 판정한다. 모든 측정값과 최소·최대는 lab.json의 context.sampling에 남는다.
  • named interaction은 페이지 안의 시계로 잰다. 클릭 이벤트의 timeStamp부터 대상 heading이 DOM에 들어온 시각까지다. Playwright 왕복 시간은 들어가지 않고, lazy chunk 다운로드(200 KB/s 제한)는 들어간다. 클릭의 Event Timing entry 길이(INP의 입력값)는 context.sampling.clickEventDurationMs에 따로 남는다.
  • CPU 모델, 논리 CPU 수, 측정 전후 loadavg를 context.runner에 남긴다.
  • preview 서버는 자기 프로세스 그룹으로 띄우고 끝날 때 그룹 전체를 멈춘다. corepack에만 신호를 보내던 때는 vite가 포트를 계속 잡고 있었다.

2026-09-27 한 빌드를 10회 잰 결과(i5-10400F 12 CPU, loadavg 1117): 중앙값 LCP 2,386ms, interaction 184.5ms로 통과했다. 한 번씩 판정했다면 interaction 10회 중 4회(최대 274ms), LCP 10회 중 2회(최대 2,644ms)가 실패였다. 같은 빌드를 loadavg 79에서 다시 10회 재면 interaction 120148ms, LCP 1,9682,072ms로 모두 통과했다. 한 번 측정한 판정은 호스트 부하에 따라 뒤집히고, 중앙값 판정은 두 번 모두 통과였다.

The field minimum eligible-sample threshold is intentionally unresolved until a privacy-approved telemetry baseline exists. Therefore the field command fails closed with FAIL_UNVERIFIED when run against the example input. Provide FIELD_WEB_VITALS_INPUT and MIN_ELIGIBLE_SAMPLES only after that decision is recorded. The external input must identify a production release and an exact 28-day export window, name the source/export, carry privacy-approval and threshold-decision references, and contain only non-negative route-ID samples. The environment threshold must be a positive integer equal to the approved decision embedded in the input. Invalid metadata fails as FAIL_UNVERIFIED; the example can never serve as production evidence.