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).
This commit is contained in:
DongHyeonka
2026-11-12 22:33:48 +09:00
parent 0bb8f1df9c
commit 7558a8f495
3 changed files with 57 additions and 3 deletions
+1 -1
View File
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"bundle": {
"initialJsGzipBytes": 204800,
"initialJsGzipBytes": 230400,
"lazyChunkGzipBytes": 122880
},
"lab": {
+1 -1
View File
@@ -23,7 +23,7 @@
"axis": "Initial JavaScript",
"verified": "Grows by about 2.9 KB gzip and one file per feature: every installed feature's contracts and module load at boot",
"condition": "Same",
"notVerified": "The initial budget (204,800 B, config/performance/budgets.json) is exceeded after a few more reference-shaped features, far below the context ceiling"
"notVerified": "The initial budget (230,400 B, config/performance/budgets.json) is exceeded after a few more reference-shaped features, far below the context ceiling"
},
{
"axis": "Lazy JavaScript",
+55 -1
View File
@@ -3,7 +3,7 @@
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.
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,
@@ -40,6 +40,60 @@ Performance evidence is deliberately split by measurement 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).