Files
tech-log-frontend/docs/operations/performance-evidence.md
T
DongHyeonka 7558a8f495 build(perf): 초기 JS 예산을 TechLog 측정값으로 225 KiB에 둔다
문제
예산 204,800 B는 템플릿을 받을 때의 기본값이다. TechLog는 기능을
붙인 뒤 예산을 다시 정하지 않았다(템플릿 문서는 첫 기능을 추가하기
전에 정하라고 한다). 앞 커밋들로 초기 JS를 300,869 B에서 229,224 B로
줄였지만, 템플릿 공통 부분(react-dom·react-router·zod·tanstack·플랫폼
src)만 약 205 KB여서 TechLog 코드를 모두 빼도 204,800 B 안에 들지
않는다.

고른 방법
- 템플릿 규칙(1106/15-01, 결정 D9)을 그대로 쓴다. CI env 측정값에
  기능 하나의 상한 1 KiB를 더해 KiB 단위로 올린다. 229,224 + 1,024 =
  230,248 B → 225 KiB = 230,400 B. 여유 1,176 B는 기능 하나와 올림
  몫이다.
- docs/operations/performance-evidence.md에 전후 수치, 뺀 것, 204,800 B로
  돌아가지 못한 이유, 다시 볼 조건과 되돌림 규칙을 적는다.
  feature-shape-ceilings.json의 예산 언급도 맞춘다.

버린 대안
- 남은 TechLog 몫(문구 catalog 약 7.5 KB, 공개 HTTP gateway·mapping 약
  6.7 KB, Studio·관리·공개 계약 약 6.6 KB, 모듈 단독 gzip)을 더 빼기.
  문구와 계약은 부팅 때 합쳐 검증하는 구조라, 템플릿 15-01(기능 실행부를
  라우트 진입 때 적재)을 옮기는 템플릿 동기화 일이다. 공개 gateway는
  첫 화면 데이터 요청에 쓰인다.

위험·한계
- 예산이 템플릿보다 23,552 B 크다. 템플릿 동기화로 15-01을 받으면 다시
  재고 같은 규칙으로 내린다. 측정값이 203,776 B 이하이면 200 KiB로
  돌아간다.

검증
- desktop CI env(CI=true, VITE_BUILD_ID, RELEASE_ID, VITE_COMMIT_SHA,
  CI_RUNNER_IMAGE): 초기 JS 229,224 B, 초기 파일 28개, 가장 큰 lazy
  chunk 40,038 B(예산 122,880 B).
2026-11-12 22:33:48 +09:00

7.9 KiB

Performance evidence contract

Performance evidence is deliberately split by measurement context:

  • bundle.json records production build output and enforces initial JavaScript at 225 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에 기록된다.

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

TechLog 예산 (2026-11-12, FE-GATE-012)

위 표는 템플릿을 받을 때의 기록이다. TechLog는 기능을 붙인 뒤 예산을 다시 정하지 않았고, 초기 JS가 main(e5fe335e)에서 300,869 B로 예산을 96,069 B 넘었다.

항목 값
초기 JS 예산 230,400 gzip bytes(225 KiB)
바꾸기 전(main e5fe335e, CI env) 300,869 B, 초기 파일 26개
바꾼 뒤(CI env) 229,224 B, 초기 파일 28개
그중 템플릿 공통 부분 약 205 KB. react-dom·scheduler 56.5 KB 청크, react-router, zod, tanstack, 플랫폼 src
그중 TechLog 코드 약 24 KB. 문구 카탈로그, 공개 HTTP gateway와 mapping, Studio·관리·공개 계약, 라우트 표, 공개 셸
가장 큰 lazy chunk 40,038 B(마크다운 파서와 content-format). 예산 122,880 B

두 몫은 분석 빌드의 모듈별 minify 바이트 비율(TechLog 10.5%)로 나눈 추정이다.

이번에 초기 JS에서 뺀 것(바꾸기 전 대비 -71,645 B):

  • MOCK 소스. 런타임 문서가 MOCK·HTTP를 고르므로 두 소스가 모든 빌드에 들어 있다. MOCK 공개 콘텐츠와 MOCK Studio gateway가 운영(HTTP) 공개 화면의 초기 JS에 있었고, MOCK이 쓰는 content-format이 마크다운 파서(micromark·mdast·unified)를 끌고 왔다. 지금은 첫 조회 때 받는다(adapters/deferred-async-port.ts).
  • Studio. Studio 셸(StudioProvider, Studio 머리말, 문서 server state)과 MOCK·HTTP Studio gateway를 /studio에 들어갈 때 받는다. gateway는 Studio가 마운트될 때 바로 받기 시작한다.
  • 쓰이지 않는 design-system·폼 모듈. 템플릿 1101/08-08(51941a54)처럼 design-system 모듈을 side effect 없음으로 선언했다.

tests/features/tech-log/boot-graph.test.ts가 MOCK 소스와 Studio 코드가 부팅 그래프에 다시 들어오지 않는지 빌드 없이 본다.

예산 값을 정한 규칙은 템플릿과 같다(템플릿 docs/operations/performance-evidence.md 1106/15-01, 결정 D9). 측정값에 기능 하나의 상한 1 KiB를 더해 KiB 단위로 올린다. 229,224 + 1,024 = 230,248 B를 올리면 225 KiB = 230,400 B다. 여유 1,176 B는 기능 하나(1,024 B)와 올림(152 B) 몫이다. 빌드 id에 따라 합계가 수백 B 움직인다.

204,800 B로 되돌리지 못한 이유:

  • 템플릿 공통 부분만 약 205 KB다. TechLog 코드를 초기 JS에서 모두 빼도 예산 안에 남는 여유가 없다.
  • 남은 TechLog 몫(문구, 공개 gateway, 계약)은 공개 첫 화면이 실제로 쓴다. 공개 gateway를 지연 로드하면 첫 화면 데이터 요청 앞에 청크 왕복이 하나 더 생긴다.
  • 템플릿은 1101/15-01(298201f3)에서 기능 실행부(계약 contribution, adapter)를 라우트 진입 때 받게 바꿨다. TechLog는 템플릿 af3d8e6(2026-09-28)에 머물러 있고, 계약·문구 catalog를 부팅 때 합친다. 그 구조를 옮기는 것은 템플릿 동기화 일이다.

다시 볼 때:

  • 예산을 다시 넘을 때. 늘린 변경이 무엇을 초기 그래프에 넣었는지 먼저 본다.
  • 템플릿 동기화로 15-01(기능 실행부 지연 적재)을 받을 때. 그때 다시 재고 같은 규칙으로 예산을 내린다. 측정값이 203,776 B 이하이면 규칙의 값이 200 KiB 이하가 되어 원래 예산으로 돌아간다.

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.