문제 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
99 lines
6.2 KiB
Markdown
99 lines
6.2 KiB
Markdown
# 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,509~202,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 11~17): 중앙값
|
|
LCP 2,386ms, interaction 184.5ms로 통과했다. 한 번씩 판정했다면 interaction
|
|
10회 중 4회(최대 274ms), LCP 10회 중 2회(최대 2,644ms)가 실패였다. 같은
|
|
빌드를 loadavg 7~9에서 다시 10회 재면 interaction 120~148ms, LCP
|
|
1,968~2,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.
|