Files
clean-architecture-frontend…/docs/operations/performance-evidence.md
T
DongHyeonka c9e7bab2d7 test(scale): 기능·context 비용을 따로 재고 초기 JS 기준선을 빌드와 대조한다
문제: (1) 기능당 1 KiB 상한 테스트는 복사본 0개와 1개만 쟀다. 첫
복사본은 새 context(shape-context-0)도 만들어서, 잰 값에 context 비용이
섞였고 상한까지 40 B만 남았다. 넘으면 기능이 커졌는지 context가
비싸졌는지 알 수 없었다. (2) 성능 기준선 숫자는 performance-evidence.md,
static-delivery.md, feature-shape-ceilings.json에 손으로 적혀 있었고
현재 빌드와도, 같은 파일 안에서도 서로 달랐다(1101/15-02 재발).
(3) 이 테스트는 vitest 안에서 돌아 NODE_ENV=test를 물려받았다. 그래서
픽스처 vite build가 React 개발 빌드를 묶었고, 잰 합계가 운영 빌드
(약 201 KB)가 아니라 약 264 KB였다.

고른 방법: 복사본 0·1·2개를 잰다. 둘째 복사본은 같은 context에 들어가
기능 하나의 비용이고, 첫 복사본에서 그것을 뺀 나머지가 context 하나의
비용이다. 기능은 1 KiB, context는 512 B로 따로 막고 실패 메시지에 잰
값을 넣는다. 기준선은 feature-shape-ceilings.json의 initialJavascript
한 곳에 기계가 읽는 칸으로 두고, 같은 테스트가 빌드와 대조한다(합계
1%, 파일 수 정확히, 기능·context 비용 10%). 기록은
`measure-feature-shape-growth.ts --initial-baseline --write`로 다시 쓴다.
문서는 숫자 대신 그 칸을 가리킨다. 픽스처 명령은 NODE_ENV를 지우고
돈다.
버린 대안: 문서 숫자를 다시 손으로 고치기(두 번 낡았다), 문서에서
숫자를 지우고 bundle.json만 가리키기(예산을 정할 숫자를 보려면 빌드가
필요하다).

위험·한계: unit에 빌드가 하나 늘었다(약 3초). 초기 JS를 움직이는
변경은 기록도 다시 써야 test:unit이 통과한다. 그것이 목적이다.
`298201f` 출처별 크기 표와 `ec7435c` HTTP/1.1 측정 표는 날짜가 붙은
측정 기록으로 남겼다.

검증: 기록을 쓰기 전 새 테스트가 실패했다. 기록 gzipBytes를 2%
바꾸면 실패하고 되돌리면 통과한다. 지금 기록: 200,939 B, 파일 25개,
기능 +765 B, context +214 B. feature-shape-growth 7건 통과,
verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-02, 15-04
2026-11-04 20:34:39 +09:00

12 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, the number of initial JavaScript files (initialJsFiles), and every lazy chunk at 120 KiB gzip. A failure names each exceeded limit, the measured value and the excess (1103/15-03).
  • 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, 1103/15-02. 예산은 config/performance/budgets.json에 있고 scripts/check-bundle.ts(FE-GATE-012, merge 단계)가 강제한다. 템플릿 기본 화면만으로 초기 JS 예산의 대부분을 쓴다. 첫 기능을 추가하기 전에 아래 기록을 보고 예산을 정한다.

기준선 숫자는 이 문서에 적지 않는다. 손으로 적은 숫자는 두 번 낡았다. 기록은 config/scale/feature-shape-ceilings.json의 initialJavascript 한 곳이다.

칸 뜻
gzipBytes, files 템플릿 그대로의 초기 JS gzip bytes와 파일 수(entry 포함)
perFeatureGzipBytes 있는 context에 참조 기능 모양 기능을 하나 더할 때 느는 초기 JS. 상한 1 KiB
perContextGzipBytes 새 context를 하나 더할 때 느는 초기 JS. 상한 512 B
  • tests/unit/feature-shape-growth.test.ts(unit, merge 단계)가 매번 빌드해 이 값을 재고, 상한을 넘거나 기록과 다르면(합계 1% 초과, 파일 수 불일치, 기능· context 비용 10% 초과) 실패한다. 실패 메시지에 잰 값이 나온다.
  • 기록을 고칠 때는 node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write를 돌리고 같은 변경에 넣는다.
  • 여유는 예산에서 gzipBytes를 뺀 값이다. 그것을 perFeatureGzipBytes로 나누면 더 넣을 수 있는 기능 수다. 새 context마다 perContextGzipBytes가 더 든다.
  • 기능 실행부(feature-runtime.ts)는 라우트에 들어갈 때 받는 lazy chunk다. lazy chunk 예산은 파일마다 120 KiB(lazyChunkGzipBytes)다.

청크 이름으로 크기를 판단하지 않는다. rolldown은 공용 청크에 안에 든 모듈 하나의 이름을 붙인다. 아래는 2026-11-01(298201f)에 잰 출처별 크기다. 지금 빌드와는 조금 다르다. 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)는 예산에 들어가지 않는다.
  • 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.

초기 청크 수와 HTTP/1.1

리뷰 1101/14.4. 08-08은 초기 JS 바이트를 줄이는 대신 초기 파일 수를 늘렸다 (vite.config.ts의 moduleSideEffects 주석). HTTP/1.1에서 브라우저는 한 호스트에 연결을 6개까지만 연다. 파일이 많으면 요청이 줄을 서서 왕복이 는다. 그래서 그때 빌드와 작은 초기 청크를 하나로 묶은 빌드를 쟀다(2026-11-03, 커밋 ec7435c). 아래 두 표의 파일 수와 바이트는 그 커밋의 값이다.

빌드 초기 JS 파일(entry 포함) 초기 JS gzip(B) 첫 화면까지 JS 요청 Fast 3G 첫 화면 Fast 4G 첫 화면
ec7435c 26 202,782 27 5,887 ms 1,874 ms
(가) 08-08이 나눈 초기 primitive 청크 4개(field·button·select·page-templates)를 하나로 23 201,818 24 5,426 ms 1,764 ms
(나) 묶을 수 있는 초기 청크 14개를 하나로 13 198,673 14 4,930 ms 1,535 ms

같은 빌드를 HTTP/2로 서빙하면(node:http2, 자체 서명 인증서, gzip) 차이가 거의 없다.

빌드 Fast 3G 첫 화면 Fast 4G 첫 화면
ec7435c 4,793 ms 1,444 ms
(가) 4,769 ms 1,440 ms
(나) 4,708 ms 1,422 ms

측정 조건:

  • vite preview(HTTP/1.1, gzip 응답)로 띄우고 Chromium으로 잰다. 네트워크는 CDP Network.emulateNetworkConditions에 DevTools 프리셋 값을 넣었다. Fast 3G는 지연 562.5 ms·내려받기 180,000 B/s, Fast 4G는 165 ms·1,012,500 B/s다.
  • 매번 새 browser context에서 캐시 없이 /를 연다. 첫 화면은 boot 셸이 사라지고 #main-content h1[data-route-heading]가 DOM에 들어온 시각이다 (performance.now()).
  • 세 빌드를 번갈아 7번씩 재고 중앙값을 적었다. 7번의 범위는 ec7435c 5,8666,077 ms, (가) 5,3845,652 ms, (나) 4,8915,032 ms다(Fast 3G). loadavg는 HTTP/1.1 측정 때 620, HTTP/2 측정 때 3~6이었다. 그래서 두 표끼리는 비교하지 않는다.
  • CDP 지연은 요청마다 붙는다. 연결 수립(TCP·TLS) 비용은 따로 재지 않았다.
  • (나)에서 묶지 않은 것: entry·preload-helper·boot, 부트 실패 화면이 쓰는 모듈(render-boot-failure·react·react-dom·jsx-runtime·operation-id· diagnostics·boot-messages, 09-03), 15-01의 feature-declarations· feature-platform.

판단: 지금은 묶지 않는다.

  • HTTP/1.1에서는 묶는 편이 빠르다. Fast 3G에서 (가) 0.46초, (나) 0.96초 빨라지고 초기 JS도 조금 준다.
  • 그러나 (가)·(나)는 이 빌드의 청크 안 모듈 목록을 그대로 적어 만들었다. 규칙으로 고르는 방법은 찾지 못했다.
    • 모듈 그래프로 boot의 정적 closure를 따라가면 design-system 배럴을 지나 갤러리 전용 primitive까지 잡힌다. 그 primitive가 다시 초기 청크로 간다.
    • rolldown의 $initial 태그는 entry가 앱을 dynamic import로 읽어서(09-03) 아무것도 잡지 않는다.
    • boot.tsx를 entry로 더하면 manifest 분류가 lazy 화면까지 초기로 센다 (28개, 216,820 B로 예산 초과).
  • 고정 목록은 셸이 쓰는 primitive가 바뀔 때마다 다시 맞춰야 한다. 목록이 낡아도 실패하는 검사가 없다. 08-08이 같은 이유로 manualChunks 이름 고정을 버렸다.
  • HTTP/2에서는 (나)도 Fast 3G 85 ms, Fast 4G 22 ms 차이다(위 둘째 표).

그래서 템플릿은 HTTP/2 이상으로 서빙한다고 본다. 초기 파일 수는 config/performance/budgets.json의 initialJsFiles가 막는다(1103/15-05). 초기 파일을 늘리는 변경은 그 값을 같이 고치고, 이유를 같은 변경에 적는다. HTTP/1.1로만 서빙해야 하는 제품은 (나)처럼 초기 청크를 묶는 그룹을 vite.config.ts에 넣는다. 그 목록은 셸을 바꿀 때마다 위 방법으로 다시 잰다.

build id와 재방문 캐시

리뷰 1103/15-06(1101 O1, 0929/13-03). build id는 부트 실패 화면이 보여 주므로 그 청크에 들어간다. 해시 자산은 1년 immutable로 캐시되지만, build id가 든 청크와 그 청크를 import하는 청크는 release마다 이름이 바뀐다. react-dom이 그 청크 안에 있을 때는 코드가 같아도 release마다 초기 JS의 절반을 다시 받았다.

판단: react-dom과 scheduler를 자기 청크(vite.config.ts의 react-dom 그룹)로 뺀다. 2026-11-04 VITE_BUILD_ID만 다른 두 빌드(gitea-101-1, gitea-102-1)를 비교했다.

빌드 이름이 바뀐 초기 파일 바뀐 초기 JS gzip(B) 초기 JS gzip(B) 초기 파일
분리 전 boot, index, render-boot-failure 99,785 (49.4%) 201,857 25
분리 뒤 boot, index, render-boot-failure 44,297 (22.0%) 201,552 25
  • lazy 파일은 두 경우 모두 0 B 바뀐다.
  • 초기 파일 수는 그대로다. react-dom의 작은 진입 모듈(1.3 KB)이 같은 청크로 합쳐졌다.
  • boot는 build id로 설정 문서를 대조하므로 계속 바뀐다. build id를 JS에 넣지 않고 release-manifest.json에서만 읽으면 더 줄지만, 부트 실패 화면이 build id를 보여 주는 계약을 바꿔야 해서 하지 않았다.
  • 부트 실패 화면은 여전히 앱 그래프의 모듈 없이 그려진다(09-03, tests/e2e/boot-module-failure.spec.ts). 이름이 유지되는지는 tests/unit/build-environment-bundle.test.ts가 본다.