문제: docs/operations의 release-cache-rollback.md와 adapter-remediation-ledger.md는 본문이 영어이고, 나머지 복구 문서와 ci-quality-gates.md에도 영어 문단이 남아 있다. 고른 방법: 뜻을 바꾸지 않고 옮긴다. 원장은 check:remediation-ledger가 읽으므로 같은 변경에서 스크립트를 맞춘다. - `SECTION_HEADING`을 옮긴 절 제목(`## 세 번째 재검토 (2026-08-14)`)으로 - 「모두 닫혔다」를 잡는 `BLANKET_CLOSURE`에 한국어 대안을 더한다. 영어 대안은 원장이 인용한 옛 문장을 잡도록 그대로 둔다 - 표 구조, id 칸, disposition 칸의 백틱 값, file-transfer 예산 숫자는 그대로다 - ci-quality-gates.md의 advisory 표가 복사한 zod·react-router 버전을 `package.json`·`pnpm-lock.yaml`을 가리키게 바꾼다(number 검사) 위험: check:remediation-ledger는 게이트 밖이라 CI가 돌리지 않는다. desktop에서 손으로 돌려 확인했다. 검증: dispositions.json의 id 25개가 그 절의 행과 맞는지, 예산 숫자가 있는지를 스크립트로 확인했다. 문서 검사의 language·number 줄이 0이 되어 예외 목록에서 지웠다.
18 KiB
성능 증거 계약
성능 증거는 측정 환경(context)에 따라 일부러 나눈다.
bundle.json은 production 빌드 출력을 기록한다. 초기 JavaScript gzip 202 KiB, 초기 JavaScript 파일 수(initialJsFiles), lazy chunk마다 gzip 120 KiB 상한을 강제한다. 실패하면 넘은 상한마다 측정값과 초과량을 적는다(1103/15-03).lab.json은 Chromium/runner/viewport/network/CPU/cache/build 환경을 기록한다. LCP 2.5 s, CLS 0.10, 지정한 route의 interaction 200 ms를 강제한다.field-web-vitals.json은 28일 동안의 production 표본을 기록한다. 표본은 동의한 것만 거르고, route ID별로 모으고, release별로 나눈다. p75 LCP, CLS, INP를 각각 2.5 s, 0.10, 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 한 곳이다. 측정은
create:feature <id> --with-create --keyed가 만드는 기능을 복사해 잰다
(scripts/scale/measure-feature-shape-growth.ts, 2026-11-07 전에는 참조 샘플을 복사했다).
| 칸 | 뜻 |
|---|---|
gzipBytes, files |
템플릿 그대로의 초기 JS gzip bytes와 파일 수(entry 포함) |
firstFeatureGzipBytes |
기능이 없는 템플릿에 첫 기능(과 그 context)을 더할 때 느는 초기 JS. 모든 기능이 함께 쓰는 코드가 이때 초기 청크에 들어온다. 한 번만 든다. 상한 없음(전체는 check:bundle의 예산이 막는다) |
perFeatureGzipBytes |
있는 context에 생성 기능 모양 기능을 하나 더할 때 느는 초기 JS. 상한 1 KiB |
perContextGzipBytes |
둘째 기능을 같은 context 대신 새 context에 둘 때 느는 초기 JS. 상한 512 B |
tests/unit/feature-shape-growth.test.ts(unit, merge 단계)가 매번 빌드해 이 값을 재고, 상한을 넘거나 기록과 다르면(합계 256 B 초과, 파일 수 불일치, 기능· context 비용 10% 초과) 실패한다. 실패 메시지에 잰 값이 나온다.- 합계의 허용 오차는 바이트로 둔다(1105/15-02). build id만 달라도 합계가 수십 B 움직이므로 0으로 둘 수 없다. 예전 1%(약 2 KB)는 남은 여유와 기능 하나보다 커서, 여유를 다 쓴 변경이 기록을 고치지 않고 지나갈 수 있었다.
- 기록을 고칠 때는
node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write를 돌리고 같은 변경에 넣는다. - 여유는 예산에서
gzipBytes를 뺀 값이다. 그것을perFeatureGzipBytes로 나누면 더 넣을 수 있는 기능 수다. 새 context마다perContextGzipBytes가 더 든다. - 예산 값
initialJsGzipBytes는 206,848 B(202 KiB)다. 1105 수정 라운드에서 204,800 B를 올렸다(2026-11-06). 그 라운드의 검사·진단 코드(조립 때 code 검사 1105/03-01, 홈 시작 링크 08-03, scope closer 진단 02-01 등)가 초기 JS를 1,184 B 늘려, 생성 기능 둘을 더하는 FE-GATE-020 드릴이 예산을 663 B 넘었다(그 라운드를 합친 빌드에서 잼, 기록 커밋0fee3fe). 버린 대안은 런타임 검사를 빌드 시점으로 옮겨 줄이기다. 라운드 중간의 설계 변경이라 다음 라운드 숫자를 흐린다. 다시 볼 때: 예산을 또 넘을 때, 또는 1103/13-03(zod 갱신, 약 7 KB)을 정할 때. 그때 03-01·02-01의 런타임 검사를 빌드 시점으로 옮기는 것부터 본다. 이 상향은 13-03을 정하지 않는다. 결정 기록은docs/reviews/2026-11-05-maturity-review/README.md16절이다.- 폭의 근거(1106/15-01, 결정 D9): 예산은 드릴 측정값에 기능 하나의 상한
(
perFeatureGzipBytes상한 1 KiB)을 더해 KiB 단위로 올림한 값이다. 드릴은 CI env에서 205,465 B였다(2026-11-06,bbde570, FE-GATE-020). 205,465 + 1,024 = 206,489 B를 올림하면 202 KiB = 206,848 B다. 그래서 드릴 위의 여유 1,383 B는 기능 하나(1,024 B)와 올림(359 B)이다. 이 규칙에 템플릿 자신이 더 쓸 몫은 없다. 템플릿 변경이 이 여유를 쓰면 그만큼 기능 몫이 준다. - 되돌림 규칙: 위 "다시 볼 때"마다 드릴을 다시 잰다. 드릴 측정값이 204,800 B 이하이면 같은 규칙(드릴 + 1 KiB를 KiB 단위로 올림)으로 예산을 내린다. 그때 규칙의 값은 201 KiB 이하다.
- D9(206,848 B를 그대로 둔다)는 메인 세션이 2026-11-06에 정했다. 사용자가 뒤집을
수 있다. 결정 기록은
docs/reviews/2026-11-06-maturity-review/README.md다.
- 폭의 근거(1106/15-01, 결정 D9): 예산은 드릴 측정값에 기능 하나의 상한
(
- 기능 실행부(
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에 따로 남는다. - 클릭으로 들어간 화면의 CLS는 대상 화면이 채워지며 내는 shift를 보지 못한다.
클릭 뒤 500 ms 안의 shift는 정의상 입력이 낸 것(
hadRecentInput)이라 빠진다. 그래서 run마다 대상 라우트를 새 context에서 직접 열고, heading 뒤 network idle까지의 CLS를metrics.targetDeepLinkCls(중앙값)와context.sampling.targetDeepLink에 남긴다. 예산은cls와 같다(1105/15-01). - 대상 화면(플랫폼 구성)은 기능 코드를 받지 않으므로 기능이 늘어도 수치가
거의 그대로다. 그래서 run마다 설치된 기능이 가진 첫 공개 내비게이션
라우트(
labFeatureRoute)를 같은 시계로 따로 잰다 (metrics.featureRouteInteractionMs,context.sampling.featureRoute, 1105/15-04). 그런 라우트가 없으면measured: false로 남기고 판정하지 않는다. 템플릿은 기능이 없어 재지 않는다(2026-11-07 예제 화면 삭제 뒤. 그 전에는 예제 화면/examples/ui가 이 라우트였다). 공개 내비게이션 라우트를 가진 제품 기능이 생기면 그 라우트를 잰다.- 예산
lab.featureRouteInteractionMs는 500 ms다. 근거:8a44226에서 lab 조건으로 그때의 예제 화면 라우트를 5회 재니 중앙값 406 ms(403410)였다. 그 진입은 요청 두 묶음이다(context 라우트 모듈과 기능 실행부, 그다음 페이지 청크와 공유 청크). 둘째 묶음이 약 100 ms(클릭 뒤 98204 ms)다. 500 ms는 지금 진입을 통과시키고, 같은 크기의 묶음이 하나 더 붙으면 넘는다. - 두 묶음을 하나로 줄이지는 않았다. 페이지 청크의 이름은 context 라우트
모듈 안의
lazy()에만 있어서, 첫 묶음에 같이 받으려면 라우트 선언(초기 청크)이 페이지 로더를 가져야 한다. 선언 모양과 초기 JS를 바꾸는 일이라 따로 정한다.
- 예산
- CPU 모델, 논리 CPU 수, 측정 전후 loadavg를
context.runner에 남긴다. - Chromium은 스크롤바를 보이게 띄운다(
--hide-scrollbars제외, 1105/15-05). Playwright 기본값은 스크롤바를 숨겨서, 첫 화면에 세로 스크롤바가 생기며 header가 밀리는 shift를 lab이 보지 못했다. 화면 쪽은:root의scrollbar-gutter: stable이 그 자리를 처음부터 잡는다. 다른 Playwright 게이트 (시각 골든 포함)는 여전히 스크롤바를 숨긴다. 예외는 그 자리를 modal 가림막이 덮는지 보는tests/visual/scrollbar-gutter.visual.spec.ts하나다(1106/08-03). - 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로 모두 통과했다. 한 번 측정한 판정은 호스트 부하에 따라
뒤집히고, 중앙값 판정은 두 번 모두 통과였다.
field의 최소 유효 표본 수(eligible-sample threshold)는 개인정보 검토를 통과한
telemetry 기준선이 생길 때까지 일부러 정하지 않는다. 그래서 예시 입력으로 field 명령을
돌리면 FAIL_UNVERIFIED로 실패한다(fail closed). FIELD_WEB_VITALS_INPUT과
MIN_ELIGIBLE_SAMPLES는 그 결정이 기록된 뒤에만 넣는다. 외부 입력은 production
release 하나와 정확한 28일 export 기간을 가리켜야 한다. 또 source/export 이름을 적고,
개인정보 승인과 기준값 결정의 참조를 담고, 음수가 아닌 route ID 표본만 담아야 한다. 환경
변수의 기준값은 양의 정수여야 하고, 입력에 담긴 승인된 결정과 같아야 한다. metadata가
잘못되면 FAIL_UNVERIFIED로 실패한다. 예시는 어떤 경우에도 production 증거가 될 수
없다.
초기 청크 수와 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으로 잰다. 네트워크는 CDPNetwork.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번의 범위는
ec7435c5,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). 상한 32는
정할 때 템플릿 그대로의 수에 6칸을 더한 값이다. 지금 템플릿 그대로의 수는 이 문서에
적지 않는다. 위 기록 config/scale/feature-shape-ceilings.json의
initialJavascript.files가 정본이고, 남은 칸은 32에서 그 값을 뺀 것이다. 기능의 지연 페이지가 셸과 같은 구성요소
(Button, SearchField 등)를 쓰면 그 구성요소가 별도 공유 청크로 떨어져 초기
파일이 하나 는다(1103 X2 #4). 상한을 현재 수와 같게 두면 그런 기능 하나로 게이트가
실패한다. HTTP/2에서 파일 하나는 거의 비용이 없다(위 표). 32를 넘으면 상한을 올리기
전에 vite.config.ts의 청크 그룹으로 공유 청크를 묶을지 본다. 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가 본다.