Files
clean-architecture-frontend…/docs/operations/performance-evidence.md
T
DongHyeonkaandClaude Opus 5.5 a55a15861e docs(performance): record the bundle budget baseline, headroom and conditions (13-14)
The template's default screens use 96% of the initial JS budget, and nothing
said so, nor that CSS is excluded, which gzip level applies, or that the lab
interaction is one run including the Playwright round trip.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 23:21:36 +09:00

3.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.

번들 예산의 기준선과 여유

리뷰 13-14. 예산은 config/performance/budgets.json에 있고 scripts/check-bundle.ts가 강제한다. 템플릿 기본 화면만으로 초기 JS 예산의 96%를 쓴다. 첫 기능을 추가하기 전에 아래 숫자를 보고 예산을 정한다.

항목 값
초기 JS 예산 204,800 gzip bytes(200 KiB)
템플릿 기준선(2026-09-25 측정) 196,573 gzip bytes. 빌드 ID가 번들에 들어가므로 빌드마다 수백 바이트 달라진다(196,386~196,623 관측)
여유 약 8,200 bytes(4%)
lazy chunk 예산 파일마다 122,880 gzip bytes(120 KiB). 기준선의 가장 큰 lazy chunk는 약 8 KB

초기 JS 9개 파일 중 세 개가 대부분이다. index 93.5 KB, design-system 65.6 KB, preload-helper 28.5 KB(zod 포함). 나머지 여섯은 합쳐 9 KB 정도다.

측정 조건:

  • 초기 파일은 Vite manifest의 entry와 그 static import다 (scripts/lib/classify-vite-bundle.ts). dynamic import chunk는 lazy다.
  • 합계는 JavaScript만 센다. CSS(index-*.css, 8.5 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로 띄워 한 번만 잰다. named interaction 시간은 Node의 performance.now()로 Playwright 클릭부터 heading 대기까지 재므로 Playwright 왕복 시간이 들어간다. 한 번 측정한 값은 흔들린다. 경계 근처 값으로 판단할 때는 여러 번 돌려 중앙값을 본다.

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.