From 8c7bcdaba5a2d3273dbba7dba234041ddc006356 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:30:09 +0900 Subject: [PATCH] =?UTF-8?q?docs(performance):=20=EB=B2=88=EB=93=A4=20?= =?UTF-8?q?=EA=B8=B0=EC=A4=80=EC=84=A0=EA=B3=BC=20=EB=B6=84=EB=A5=98=20?= =?UTF-8?q?=EA=B7=9C=EC=B9=99=EC=9D=84=2015-01=20=EB=92=A4=20=EB=B9=8C?= =?UTF-8?q?=EB=93=9C=EC=97=90=20=EB=A7=9E=EC=B6=98=EB=8B=A4=20(1101/15-02)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 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 --- docs/operations/performance-evidence.md | 44 ++++++++++++++++++------- 1 file changed, 33 insertions(+), 11 deletions(-) diff --git a/docs/operations/performance-evidence.md b/docs/operations/performance-evidence.md index 9faa1659..be7cf23e 100644 --- a/docs/operations/performance-evidence.md +++ b/docs/operations/performance-evidence.md @@ -12,25 +12,47 @@ Performance evidence is deliberately split by measurement context: ## 번들 예산의 기준선과 여유 -리뷰 13-14. 예산은 `config/performance/budgets.json`에 있고 -`scripts/check-bundle.ts`가 강제한다. 템플릿 기본 화면만으로 초기 JS 예산의 -96%를 쓴다. 첫 기능을 추가하기 전에 아래 숫자를 보고 예산을 정한다. +리뷰 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-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 | +| 템플릿 기준선(2026-11-01, 커밋 `298201f`) | 202,509~202,522 gzip bytes, 16개 파일. local 프로필, `VITE_BUILD_ID`가 `local-build`일 때와 CI 모양(`gitea--`)일 때다. 빌드 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다 | -초기 JS 9개 파일 중 세 개가 대부분이다. `index` 93.5 KB, `design-system` -65.6 KB, `preload-helper` 28.5 KB(zod 포함). 나머지 여섯은 합쳐 9 KB 정도다. +청크 이름으로 크기를 판단하지 않는다. 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다 - (`scripts/lib/classify-vite-bundle.ts`). dynamic import chunk는 lazy다. -- 합계는 JavaScript만 센다. CSS(`index-*.css`, 8.5 KB gzip)는 예산에 들어가지 +- 초기 파일은 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로 보내면 전송 크기는 더