perf: 공개 첫 화면에서 MOCK·Studio 코드를 빼고 초기 JS 예산을 측정값으로 정한다 #9

Merged
donghyeon.kang merged 5 commits from perf/initial-js-budget into main 2026-11-12 21:51:04 +00:00
Owner

무엇을, 왜

FE-GATE-012(번들 예산)가 main부터 실패한다. 초기 JS가 300,869 B(gzip, CI env)이고 예산은 204,800 B다. 초기 JS를 모듈 단위로 재 보니 첫 화면에 필요 없는 코드가 많았다.

  • MOCK 공개 콘텐츠와 MOCK Studio gateway. 런타임 문서가 MOCK·HTTP를 고르므로 두 소스가 모든 빌드에 들어 있다. 운영(HTTP) 공개 화면도 이 코드를 받았다.
  • MOCK이 쓰는 content-format이 끌고 온 마크다운 파서(micromark·mdast·unified).
  • Studio 셸, StudioProvider, Studio 머리말, 문서 server state, HTTP Studio gateway.
  • 공개 셸이 쓰지 않는 design-system primitive와 폼 모듈.

이것들을 첫 사용 때 받게 해서 초기 JS를 71,645 B(24%) 줄였다. 남은 229,224 B 중 템플릿 공통 부분만 약 205 KB다. TechLog 코드를 모두 빼도 204,800 B 안에 들지 않는다. 그래서 예산을 템플릿 규칙대로 측정값에서 정했다: 225 KiB = 230,400 B.

커밋 무엇을
8e0ea60e perf(tech-log) MOCK 공개 콘텐츠와 MOCK·HTTP Studio gateway를 첫 호출 때 받는다(deferAsyncPort). Studio gateway는 Studio가 마운트될 때 바로 받기 시작한다
02cf5ed3 perf(studio) Studio 셸을 /studio에 들어갈 때 받는다(Suspense + ChunkRecoveryBoundary). 부팅 그래프 회귀 시험
0bb8f1df perf(build) design-system 모듈을 side effect 없음으로 선언한다(템플릿 1101/08-08 51941a54와 같다)
7558a8f4 build(perf) 예산 225 KiB, 근거·되돌림 규칙 문서
8422c41e fix(build) 번들 기능 소유 검사(check:app-build-input:bundle, FE-GATE-012의 셋째 명령)가 직접 조립하는 TechLog를 받아들인다. 아래 「예산 뒤에 가려져 있던 실패」

초기 JS 전후 (desktop CI env, gzip)

단계 초기 JS 초기 파일 가장 큰 lazy chunk
main e5fe335e 300,869 B 26 14,438 B
+ MOCK·Studio gateway·Studio 셸 지연(커밋 1·2) 232,337 B 27 40,038 B
+ design-system side effect 없음(커밋 3) 229,224 B 28 40,038 B
예산 204,800 → 230,400 B — 122,880 B(그대로)

main → 커밋 1·2에서 빠진 모듈은 179개다. 모듈 단독 gzip 합으로 보면 다음과 같다(따로 압축한 값이라 합계는 실제 감소보다 크다).

  • npm 약 88 KB(마크다운 파서)
  • adapters/mock 23 KB
  • adapters/static 11 KB
  • presentation/studio 10 KB
  • domain/content-format 7.6 KB
  • adapters/http(Studio) 3.7 KB

남은 초기 JS 229,224 B를 분석 빌드의 minify 바이트 비율로 나누면, 템플릿 공통 부분이 약 205 KB이고 TechLog 코드가 약 24 KB(10.5%)다. 템플릿 공통 부분은 react-dom·scheduler 청크 56.5 KB, react-router, zod, tanstack, 플랫폼 src다.

예산 뒤에 가려져 있던 실패

예산을 맞추자 FE-GATE-012의 다음 명령 check:app-build-input:bundle이 실패했다.

  • 메시지: production bundle contains feature "tech-log" not owned by app template-app.
  • 원인: 이 검사는 번들에 든 src/features/<dir>/ 모듈이 모두 생성기로 설치된(context가 소유한) 기능이라고 본다. TechLog는 조립부가 직접 붙이는 기능(src/features/tech-log/NOT_INSTALLED)이라, TechLog의 모든 production 번들이 거절된다.
  • 9-29 템플릿 동기화(af3d8e6)로 들어온 뒤, 같은 게이트의 예산 검사가 먼저 실패해 한 번도 이 단계까지 가지 않았다. main에서도 같다.
  • 고친 것: 번들 쪽 검사만 tech-log를 이름으로 허용한다. 생성 인덱스 쪽 검사는 그대로다.
  • 버린 대안: NOT_INSTALLED 표시가 있는 디렉터리를 모두 허용하기. reference-feature·local-draft-feature도 NOT_INSTALLED라서, 그 샘플이 번들에 새면 잡아야 한다. 시험이 이것을 본다.
  • 템플릿 소유 스크립트를 고쳤다. TechLog를 feature-module.ts로 옮기는 후속 작업(docs/operations/template-sync-2026-09-29.md)을 하면 이 목록을 지운다.

고른 방법과 버린 대안

  • 포트 지연(deferAsyncPort). 포트는 모든 메서드가 이미 Promise를 돌려준다. 그래서 포트를 먼저 만들고, 첫 호출에서 구현 모듈을 동적 import해 넘긴다. feature input 모양과 호출하는 쪽은 바뀌지 않는다.

    • 키 목록은 Record<keyof Port, true>라서 포트가 바뀌면 타입 검사가 실패한다.
    • 구현을 받지 못하면 잊고 다음 호출에서 다시 받는다.
  • 버린 대안: createStudioApplication을 async로 바꾸기. StudioProvider와 시험 15곳이 같이 바뀐다.

  • 버린 대안: 공개 HTTP gateway도 지연 로드. 공개 첫 화면 데이터 요청 앞에 청크 왕복이 하나 생긴다. 첫 화면에 필요한 코드라 남겼다.

  • 버린 대안: 템플릿 소유 app-router.tsx에서 레이아웃 route에 lazy를 걸기. 템플릿 파일을 고치게 된다. 화면 청크는 여전히 셸 뒤에 받는다.

  • 예산을 올린 것(마지막 수단). 템플릿 규칙(docs/operations/performance-evidence.md 1106/15-01, 결정 D9)과 같다. CI env 측정값에 기능 하나의 상한 1 KiB를 더해 KiB 단위로 올린다.

    • 계산: 229,224 + 1,024 = 230,248 B → 225 KiB = 230,400 B.
    • 여유 1,176 B는 기능 하나(1,024 B)와 올림(152 B)이다.
    • 템플릿도 같은 규칙으로 자기 예산을 206,848 B로 올렸다. 템플릿 문서는 제품이 첫 기능을 넣기 전에 자기 예산을 정하라고 한다. TechLog는 그동안 정하지 않았다.
  • 더 빼지 않은 것. 모듈 단독 gzip 기준으로 다음이 남았다.

    • 문구 catalog 약 7.5 KB
    • 공개 HTTP gateway·mapping 약 6.7 KB
    • Studio·관리·공개 계약 약 6.6 KB

    문구와 계약은 부팅 때 합쳐서 검증하는 구조다. 이것을 빼려면 템플릿 1101/15-01(298201f3, 기능 실행부를 라우트 진입 때 적재)을 옮겨야 하고, 그건 템플릿 동기화 일이다. TechLog는 템플릿 af3d8e6(2026-09-28)에 있다.

  • 되돌림 규칙(문서에 적음). 15-01을 받는 템플릿 동기화 때, 또는 예산을 다시 넘을 때 다시 잰다. 같은 규칙으로 예산을 내린다. 측정값이 203,776 B 이하이면 200 KiB로 돌아간다.

위험과 영향

  • 운영 동작이 바뀌는 것.
    • /studio 첫 진입: Studio 셸 청크를 받은 뒤 화면 청크를 받는다(직렬 왕복 하나). 셸을 받는 동안 LoadingSurface가 보인다. Studio gateway 청크는 Studio가 마운트될 때 화면 청크와 같이 받는다.
    • 공개 화면은 HTTP 소스라 바뀌지 않는다. 받는 JS만 줄었다.
  • MOCK 빌드(로컬·e2e·visual). 첫 공개 조회와 첫 Studio 조회 앞에 청크를 한 번 받는다.
  • 초기 파일 수. 26개에서 28개로 늘었다. HTTP/2에서는 진입 청크의 preload 목록으로 병렬로 받는다(템플릿과 같은 판단).
  • 예산 차이. 예산이 템플릿보다 23,552 B 크다. 되돌림 조건은 위에 적었다.
  • 운영 적용. 하지 않았다(이미지 push·rollout은 소유자 묶음).

검증

desktop 호스트, node 24.14.0, CI env(CI=true, VITE_BUILD_ID, RELEASE_ID, VITE_COMMIT_SHA, CI_RUNNER_IMAGE)다. heavy lock 아래에서 돌렸다. 매번 origin을 새로 clone하고 bundle로 브랜치를 받았다.

모든 게이트는 head 8422c41e에서 돌렸다. 012·003·002·001·004·005·011·009는 2회차(23:2323:31), 008과 단독 visual은 3회차(23:3223:49)다.

게이트·명령 rc 내용
FE-GATE-001 lockfile 0
FE-GATE-002 lint 0
FE-GATE-003 typecheck 0
FE-GATE-004 runtime schema 0
FE-GATE-005 unit·coverage 0 unit 177파일 2,389건, coverage 351파일 3,624건
FE-GATE-008 e2e 0 test:e2e 592 통과·3 skip, capability 63, storybook 1, visual 132, 증거 검사 둘
FE-GATE-009 a11y 0 90건
FE-GATE-011 build 0 build·storybook build
FE-GATE-012 bundle 0 초기 JS 229,223 / 230,400 B, 초기 파일 28개, 가장 큰 lazy 40,038 / 122,880 B. check:app-build-input:bundle·check:optional-recipes 통과
test:visual 단독 0 132건(SOURCE_DATE_EPOCH는 HEAD 커밋 시각)

1회차(head 7558a8f4, 기능 소유 검사 수정 전)는 다음과 같았다.

  • 001~005·008·009·011은 rc=0.
  • 012는 예산 검사 PASS(229,223 B) 뒤 check:app-build-input:bundle에서 rc=1이었다(위 「예산 뒤에 가려져 있던 실패」).
  • 단독 test:visual은 CI env에 SOURCE_DATE_EPOCH를 빠뜨려 서버 빌드에서 멈췄다. 시험 자체가 실패한 것이 아니다. 3회차에서 넣고 다시 돌렸다.

빠른 검사(main 위 같은 코드 patch, 21:48 lock 대기 → 22:32): check:types·lint rc=0. 관련 시험 7파일 30건 통과(boot-graph, deferred-async-port, runtime-composition, studio-shell-smoke, design-system-side-effects, router, build-environment-bundle).

하지 않은 것:

  • 운영 배포와 실제 HTTP 백엔드로 /studio에 들어가 보기. e2e는 MOCK 빌드다.
  • /studio 첫 진입 시간을 lab에서 재기(FE-GATE-026은 돌리지 않았다).

새 시험:

  • tests/features/tech-log/boot-graph.test.ts
    • 부팅 그래프를 빌드 없이 따라간다. 범위는 main.tsx, 그 정적 import, 진입점이 바로 동적으로 읽는 boot·render-boot-failure다.
    • MOCK 소스·정적 콘텐츠·Studio 화면·HTTP Studio gateway가 다시 들어오지 않는지 본다.
    • 공개 셸과 기능 입력 조립이 그래프에 있는지도 봐서, 빈 결과로 통과하지 않는다.
  • tests/features/tech-log/deferred-async-port.test.ts(6건)
    • 한 번만 받기, 동시 첫 호출, 실패 뒤 다시 받기, 키와 freeze.
    • gateway 셋의 Studio state 공유, startNow.
  • tests/unit/design-system-side-effects.test.ts: design-system에 효과만을 위한 import가 없다.
  • tests/architecture/app-build-input.test.ts(1건 추가): 번들의 TechLog 모듈은 받아들이고, 같은 번들의 reference-feature는 거절한다.

리뷰어가 볼 곳

  • src/features/tech-log/adapters/deferred-async-port.ts, deferred-tech-log-ports.ts: 지연 포트와 키 목록.
  • src/features/tech-log/adapters/create-tech-log-feature-input.ts: MOCK/HTTP 분기.
  • src/features/tech-log/presentation/tech-log-route-runtime.tsx: Studio 셸 지연과 청크 복구.
  • vite.config.ts: treeshake.moduleSideEffects.
  • config/performance/budgets.json, docs/operations/performance-evidence.md 「TechLog 예산」 절.
  • scripts/check-app-build-input.ts: DIRECTLY_COMPOSED_FEATURE_DIRECTORIES.

관련

  • W1 인계 2번(공유 노트 w1-infra-hardening.md), PR #8 남은 일.
  • 템플릿: docs/operations/performance-evidence.md(예산 규칙, 1106/15-01 결정 D9), 51941a54(1101/08-08), 298201f3(1101/15-01).
## 무엇을, 왜 FE-GATE-012(번들 예산)가 main부터 실패한다. 초기 JS가 300,869 B(gzip, CI env)이고 예산은 204,800 B다. 초기 JS를 모듈 단위로 재 보니 첫 화면에 필요 없는 코드가 많았다. - MOCK 공개 콘텐츠와 MOCK Studio gateway. 런타임 문서가 MOCK·HTTP를 고르므로 두 소스가 모든 빌드에 들어 있다. 운영(HTTP) 공개 화면도 이 코드를 받았다. - MOCK이 쓰는 content-format이 끌고 온 마크다운 파서(micromark·mdast·unified). - Studio 셸, StudioProvider, Studio 머리말, 문서 server state, HTTP Studio gateway. - 공개 셸이 쓰지 않는 design-system primitive와 폼 모듈. 이것들을 첫 사용 때 받게 해서 초기 JS를 71,645 B(24%) 줄였다. 남은 229,224 B 중 템플릿 공통 부분만 약 205 KB다. TechLog 코드를 모두 빼도 204,800 B 안에 들지 않는다. 그래서 예산을 템플릿 규칙대로 측정값에서 정했다: 225 KiB = 230,400 B. | 커밋 | 무엇을 | | --- | --- | | `8e0ea60e` perf(tech-log) | MOCK 공개 콘텐츠와 MOCK·HTTP Studio gateway를 첫 호출 때 받는다(`deferAsyncPort`). Studio gateway는 Studio가 마운트될 때 바로 받기 시작한다 | | `02cf5ed3` perf(studio) | Studio 셸을 `/studio`에 들어갈 때 받는다(Suspense + ChunkRecoveryBoundary). 부팅 그래프 회귀 시험 | | `0bb8f1df` perf(build) | design-system 모듈을 side effect 없음으로 선언한다(템플릿 1101/08-08 `51941a54`와 같다) | | `7558a8f4` build(perf) | 예산 225 KiB, 근거·되돌림 규칙 문서 | | `8422c41e` fix(build) | 번들 기능 소유 검사(`check:app-build-input:bundle`, FE-GATE-012의 셋째 명령)가 직접 조립하는 TechLog를 받아들인다. 아래 「예산 뒤에 가려져 있던 실패」 | ## 초기 JS 전후 (desktop CI env, gzip) | 단계 | 초기 JS | 초기 파일 | 가장 큰 lazy chunk | | --- | ---: | ---: | ---: | | main `e5fe335e` | 300,869 B | 26 | 14,438 B | | + MOCK·Studio gateway·Studio 셸 지연(커밋 1·2) | 232,337 B | 27 | 40,038 B | | + design-system side effect 없음(커밋 3) | 229,224 B | 28 | 40,038 B | | 예산 | 204,800 → 230,400 B | — | 122,880 B(그대로) | main → 커밋 1·2에서 빠진 모듈은 179개다. 모듈 단독 gzip 합으로 보면 다음과 같다(따로 압축한 값이라 합계는 실제 감소보다 크다). - npm 약 88 KB(마크다운 파서) - `adapters/mock` 23 KB - `adapters/static` 11 KB - `presentation/studio` 10 KB - `domain/content-format` 7.6 KB - `adapters/http`(Studio) 3.7 KB 남은 초기 JS 229,224 B를 분석 빌드의 minify 바이트 비율로 나누면, 템플릿 공통 부분이 약 205 KB이고 TechLog 코드가 약 24 KB(10.5%)다. 템플릿 공통 부분은 react-dom·scheduler 청크 56.5 KB, react-router, zod, tanstack, 플랫폼 `src`다. ## 예산 뒤에 가려져 있던 실패 예산을 맞추자 FE-GATE-012의 다음 명령 `check:app-build-input:bundle`이 실패했다. - 메시지: `production bundle contains feature "tech-log" not owned by app template-app`. - 원인: 이 검사는 번들에 든 `src/features/<dir>/` 모듈이 모두 생성기로 설치된(context가 소유한) 기능이라고 본다. TechLog는 조립부가 직접 붙이는 기능(`src/features/tech-log/NOT_INSTALLED`)이라, TechLog의 모든 production 번들이 거절된다. - 9-29 템플릿 동기화(af3d8e6)로 들어온 뒤, 같은 게이트의 예산 검사가 먼저 실패해 한 번도 이 단계까지 가지 않았다. main에서도 같다. - 고친 것: 번들 쪽 검사만 `tech-log`를 이름으로 허용한다. 생성 인덱스 쪽 검사는 그대로다. - 버린 대안: NOT_INSTALLED 표시가 있는 디렉터리를 모두 허용하기. reference-feature·local-draft-feature도 NOT_INSTALLED라서, 그 샘플이 번들에 새면 잡아야 한다. 시험이 이것을 본다. - 템플릿 소유 스크립트를 고쳤다. TechLog를 feature-module.ts로 옮기는 후속 작업(`docs/operations/template-sync-2026-09-29.md`)을 하면 이 목록을 지운다. ## 고른 방법과 버린 대안 - **포트 지연(`deferAsyncPort`).** 포트는 모든 메서드가 이미 Promise를 돌려준다. 그래서 포트를 먼저 만들고, 첫 호출에서 구현 모듈을 동적 import해 넘긴다. feature input 모양과 호출하는 쪽은 바뀌지 않는다. - 키 목록은 `Record<keyof Port, true>`라서 포트가 바뀌면 타입 검사가 실패한다. - 구현을 받지 못하면 잊고 다음 호출에서 다시 받는다. - **버린 대안: `createStudioApplication`을 async로 바꾸기.** StudioProvider와 시험 15곳이 같이 바뀐다. - **버린 대안: 공개 HTTP gateway도 지연 로드.** 공개 첫 화면 데이터 요청 앞에 청크 왕복이 하나 생긴다. 첫 화면에 필요한 코드라 남겼다. - **버린 대안: 템플릿 소유 `app-router.tsx`에서 레이아웃 route에 lazy를 걸기.** 템플릿 파일을 고치게 된다. 화면 청크는 여전히 셸 뒤에 받는다. - **예산을 올린 것(마지막 수단).** 템플릿 규칙(`docs/operations/performance-evidence.md` 1106/15-01, 결정 D9)과 같다. CI env 측정값에 기능 하나의 상한 1 KiB를 더해 KiB 단위로 올린다. - 계산: 229,224 + 1,024 = 230,248 B → 225 KiB = 230,400 B. - 여유 1,176 B는 기능 하나(1,024 B)와 올림(152 B)이다. - 템플릿도 같은 규칙으로 자기 예산을 206,848 B로 올렸다. 템플릿 문서는 제품이 첫 기능을 넣기 전에 자기 예산을 정하라고 한다. TechLog는 그동안 정하지 않았다. - **더 빼지 않은 것.** 모듈 단독 gzip 기준으로 다음이 남았다. - 문구 catalog 약 7.5 KB - 공개 HTTP gateway·mapping 약 6.7 KB - Studio·관리·공개 계약 약 6.6 KB 문구와 계약은 부팅 때 합쳐서 검증하는 구조다. 이것을 빼려면 템플릿 1101/15-01(`298201f3`, 기능 실행부를 라우트 진입 때 적재)을 옮겨야 하고, 그건 템플릿 동기화 일이다. TechLog는 템플릿 `af3d8e6`(2026-09-28)에 있다. - **되돌림 규칙(문서에 적음).** 15-01을 받는 템플릿 동기화 때, 또는 예산을 다시 넘을 때 다시 잰다. 같은 규칙으로 예산을 내린다. 측정값이 203,776 B 이하이면 200 KiB로 돌아간다. ## 위험과 영향 - **운영 동작이 바뀌는 것.** - `/studio` 첫 진입: Studio 셸 청크를 받은 뒤 화면 청크를 받는다(직렬 왕복 하나). 셸을 받는 동안 LoadingSurface가 보인다. Studio gateway 청크는 Studio가 마운트될 때 화면 청크와 같이 받는다. - 공개 화면은 HTTP 소스라 바뀌지 않는다. 받는 JS만 줄었다. - **MOCK 빌드(로컬·e2e·visual).** 첫 공개 조회와 첫 Studio 조회 앞에 청크를 한 번 받는다. - **초기 파일 수.** 26개에서 28개로 늘었다. HTTP/2에서는 진입 청크의 preload 목록으로 병렬로 받는다(템플릿과 같은 판단). - **예산 차이.** 예산이 템플릿보다 23,552 B 크다. 되돌림 조건은 위에 적었다. - **운영 적용.** 하지 않았다(이미지 push·rollout은 소유자 묶음). ## 검증 desktop 호스트, node 24.14.0, CI env(`CI=true`, `VITE_BUILD_ID`, `RELEASE_ID`, `VITE_COMMIT_SHA`, `CI_RUNNER_IMAGE`)다. heavy lock 아래에서 돌렸다. 매번 origin을 새로 clone하고 bundle로 브랜치를 받았다. 모든 게이트는 head `8422c41e`에서 돌렸다. 012·003·002·001·004·005·011·009는 2회차(23:23~23:31), 008과 단독 visual은 3회차(23:32~23:49)다. | 게이트·명령 | rc | 내용 | | --- | --- | --- | | FE-GATE-001 lockfile | 0 | | | FE-GATE-002 lint | 0 | | | FE-GATE-003 typecheck | 0 | | | FE-GATE-004 runtime schema | 0 | | | FE-GATE-005 unit·coverage | 0 | unit 177파일 2,389건, coverage 351파일 3,624건 | | FE-GATE-008 e2e | 0 | test:e2e 592 통과·3 skip, capability 63, storybook 1, visual 132, 증거 검사 둘 | | FE-GATE-009 a11y | 0 | 90건 | | FE-GATE-011 build | 0 | build·storybook build | | FE-GATE-012 bundle | 0 | 초기 JS 229,223 / 230,400 B, 초기 파일 28개, 가장 큰 lazy 40,038 / 122,880 B. check:app-build-input:bundle·check:optional-recipes 통과 | | test:visual 단독 | 0 | 132건(`SOURCE_DATE_EPOCH`는 HEAD 커밋 시각) | 1회차(head `7558a8f4`, 기능 소유 검사 수정 전)는 다음과 같았다. - 001~005·008·009·011은 rc=0. - 012는 예산 검사 PASS(229,223 B) 뒤 `check:app-build-input:bundle`에서 rc=1이었다(위 「예산 뒤에 가려져 있던 실패」). - 단독 test:visual은 CI env에 `SOURCE_DATE_EPOCH`를 빠뜨려 서버 빌드에서 멈췄다. 시험 자체가 실패한 것이 아니다. 3회차에서 넣고 다시 돌렸다. 빠른 검사(main 위 같은 코드 patch, 21:48 lock 대기 → 22:32): check:types·lint rc=0. 관련 시험 7파일 30건 통과(boot-graph, deferred-async-port, runtime-composition, studio-shell-smoke, design-system-side-effects, router, build-environment-bundle). 하지 않은 것: - 운영 배포와 실제 HTTP 백엔드로 `/studio`에 들어가 보기. e2e는 MOCK 빌드다. - `/studio` 첫 진입 시간을 lab에서 재기(FE-GATE-026은 돌리지 않았다). 새 시험: - `tests/features/tech-log/boot-graph.test.ts` - 부팅 그래프를 빌드 없이 따라간다. 범위는 main.tsx, 그 정적 import, 진입점이 바로 동적으로 읽는 boot·render-boot-failure다. - MOCK 소스·정적 콘텐츠·Studio 화면·HTTP Studio gateway가 다시 들어오지 않는지 본다. - 공개 셸과 기능 입력 조립이 그래프에 있는지도 봐서, 빈 결과로 통과하지 않는다. - `tests/features/tech-log/deferred-async-port.test.ts`(6건) - 한 번만 받기, 동시 첫 호출, 실패 뒤 다시 받기, 키와 freeze. - gateway 셋의 Studio state 공유, startNow. - `tests/unit/design-system-side-effects.test.ts`: design-system에 효과만을 위한 import가 없다. - `tests/architecture/app-build-input.test.ts`(1건 추가): 번들의 TechLog 모듈은 받아들이고, 같은 번들의 reference-feature는 거절한다. ## 리뷰어가 볼 곳 - `src/features/tech-log/adapters/deferred-async-port.ts`, `deferred-tech-log-ports.ts`: 지연 포트와 키 목록. - `src/features/tech-log/adapters/create-tech-log-feature-input.ts`: MOCK/HTTP 분기. - `src/features/tech-log/presentation/tech-log-route-runtime.tsx`: Studio 셸 지연과 청크 복구. - `vite.config.ts`: `treeshake.moduleSideEffects`. - `config/performance/budgets.json`, `docs/operations/performance-evidence.md` 「TechLog 예산」 절. - `scripts/check-app-build-input.ts`: `DIRECTLY_COMPOSED_FEATURE_DIRECTORIES`. ## 관련 - W1 인계 2번(공유 노트 `w1-infra-hardening.md`), PR #8 남은 일. - 템플릿: `docs/operations/performance-evidence.md`(예산 규칙, 1106/15-01 결정 D9), `51941a54`(1101/08-08), `298201f3`(1101/15-01).
donghyeon.kang added 5 commits 2026-11-12 21:50:58 +00:00
문제
런타임 문서가 MOCK·HTTP를 고르므로 두 소스가 모든 빌드에 들어간다.
기능 입력 조립(create-tech-log-feature-input.ts)이 MOCK 공개 콘텐츠,
MOCK·HTTP Studio gateway를 정적으로 가져와, 운영(HTTP) 공개 화면을
여는 사람도 그 코드를 초기 JS로 받았다. MOCK이 쓰는 content-format은
마크다운 파서(micromark·mdast·unified)까지 끌고 왔다. 초기 JS는 main
에서 300,869 B(gzip)로 예산 204,800 B를 넘는다(FE-GATE-012).

고른 방법
- 포트는 이미 모두 Promise를 돌려준다. deferAsyncPort가 포트를 먼저
  만들고 첫 호출에서 구현 모듈을 동적 import해 넘긴다. 호출하는 쪽과
  feature input의 모양(publicContent, createStudioApplication)은 그대로다.
  - 포트 키 목록은 `Record<keyof Port, true>`로 적어, 포트에 메서드가
    늘거나 줄면 타입 검사가 실패한다.
  - 구현 받기에 실패하면 잊고 다음 호출에서 다시 받는다.
- MOCK 공개 콘텐츠는 첫 조회 때 받는다. HTTP 공개 gateway는 공개 첫
  화면의 데이터 요청에 쓰이므로 그대로 둔다.
- Studio gateway 셋(MOCK이면 Studio state 하나를 나눠 씀)은 묶음 하나로
  받는다(mock-studio-gateways.ts, http-studio-gateways.ts).
  createStudioApplication은 Studio가 마운트될 때 불리므로 그때 바로 받기
  시작한다(startNow). 첫 조회 때 받으면 화면 청크 → 조회 → gateway 청크
  → 요청으로 한 번 더 기다린다.

버린 대안
- createStudioApplication을 async로 바꾸기: StudioProvider와 시험 15곳이
  함께 바뀐다. 포트가 이미 비동기라 필요 없다.
- 공개 HTTP gateway도 지연 로드: 첫 화면 데이터 요청 앞에 청크 왕복이
  하나 생긴다.

위험·한계
- MOCK 빌드(로컬·e2e·visual)는 첫 공개 조회와 첫 Studio 조회 앞에 청크를
  한 번 받는다.
- 포트 메서드가 동기 값을 돌려주게 바뀌면 이 방식은 맞지 않는다. 타입
  제약(모든 멤버가 Promise를 돌려줌)이 그때 컴파일에서 막는다.

검증
- desktop CI env 빌드: 초기 JS 300,869 → 232,337 B(Studio 셸 지연을
  포함한 측정, 다음 커밋). 빠진 모듈 179개 중 npm(마크다운 파서) 약
  88 KB, mock 23 KB, static 11 KB(모듈 단독 gzip 합).
- tests/features/tech-log/deferred-async-port.test.ts: 한 번만 받기, 동시
  첫 호출, 실패 뒤 다시 받기, 키·freeze, gateway 셋의 state 공유, startNow.
문제
라우트 레이아웃 표(tech-log-route-runtime.tsx)가 StudioShell을 정적으로
가져와, 공개 화면의 초기 JS에 StudioProvider·Studio 머리말·문서 server
state가 들어갔다.

고른 방법
- STUDIO 레이아웃은 lazy StudioShell을 Suspense와 ChunkRecoveryBoundary로
  감싼다. 청크를 못 받으면 라우트 청크와 같은 recoverChunk가 한 번 새로
  읽기를 정한다(chunkId `tech-log-studio-shell`).
- tests/features/tech-log/boot-graph.test.ts가 부팅 그래프(main.tsx, 그
  정적 import, 진입점이 바로 동적으로 읽는 boot·render-boot-failure)를
  빌드 없이 따라가, MOCK 소스·정적 콘텐츠·Studio 화면·HTTP Studio
  gateway가 다시 들어오지 않는지 본다. 공개 셸과 기능 입력 조립이
  그래프에 있는지도 봐서 빈 결과로 통과하지 않는다.

버린 대안
- 템플릿 소유 app-router.tsx에서 레이아웃 route에 lazy를 거는 것: 템플릿
  파일을 고치게 되고, 자식 화면 청크는 여전히 셸 뒤에 받는다.

위험·한계
- /studio 첫 진입은 셸 청크를 받은 뒤 화면 청크를 받는다(직렬 왕복 하나).
  Studio는 작성자 한 사람이 쓰는 화면이다.
- 셸을 받는 동안 LoadingSurface가 보인다.

검증
- desktop CI env 빌드: 앞 커밋과 함께 초기 JS 300,869 → 232,337 B.
- boot-graph.test.ts 통과.
문제
공개 셸은 design-system/index.ts 배럴에서 Button 몇 개를 가져온다.
번들러는 배럴이 다시 내보내는 모듈을 side effect가 있다고 보고 모두
싣는다. 그래서 공개 첫 화면이 쓰지 않는 navigation·overlays·patterns
primitive와 폼 모듈(use-app-form 등)이 초기 JS에 있었다.

고른 방법
- 템플릿 1101/08-08(51941a54)과 같은 treeshake.moduleSideEffects 규칙을
  vite.config.ts에 둔다. 같은 vite 8.1.5다.
- design-system 파일은 선언만 하고 top-level 효과가 없다. 효과만을 위한
  import(`import "x"`)는 이 선언 아래에서 모듈과 같이 사라지므로,
  tests/unit/design-system-side-effects.test.ts가 그런 import가 없는지
  본다. CSS는 bootstrap/main.tsx에서 읽는다.
- 배럴을 통해서만 닿던 폼 모듈도 같이 빠진다. 폼 모듈에도 top-level
  효과가 없는 것을 확인했다.

위험·한계
- 초기 파일 수가 27개에서 28개로 는다. HTTP/2에서는 진입 청크의
  preload 목록으로 병렬로 받는다(템플릿 같은 판단).

검증
- desktop CI env 분석 빌드: 초기 JS 229,765 → 226,554 B(-3,211 B,
  분석 빌드 기준. 공식 수치는 예산 커밋).
문제
예산 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).
문제
FE-GATE-012의 check:app-build-input:bundle은 production 번들에 든
`src/features/<dir>/` 모듈이 모두 앱의 context가 소유한(생성기로 설치한)
기능이어야 한다고 본다. TechLog는 조립부가 직접 붙이는 기능이라
(`src/features/tech-log/NOT_INSTALLED`) 어떤 context도 소유하지 않는다.
그래서 이 검사는 TechLog의 모든 production 번들을 거절한다. 9-29 템플릿
동기화(af3d8e6)로 들어온 뒤, 같은 게이트의 번들 예산 검사가 먼저 실패해
한 번도 이 단계까지 가지 않았다. 예산을 맞추자 드러났다.

고른 방법
- DIRECTLY_COMPOSED_FEATURE_DIRECTORIES(["tech-log"])를 두고, 번들 쪽
  검사에서만 이름으로 허용한다.
- 생성 인덱스 쪽 검사는 그대로다. 생성기가 TechLog를 import하면 여전히
  실패한다.

버린 대안
- NOT_INSTALLED 표시가 있는 디렉터리를 모두 허용: reference-feature와
  local-draft-feature도 NOT_INSTALLED다. 그 샘플이 번들에 새면 이 검사가
  잡아야 한다.

위험·한계
- 템플릿 소유 스크립트를 고친다. TechLog를 feature-module.ts로 옮기는
  후속 작업(docs/operations/template-sync-2026-09-29.md)을 하면 이 목록을
  지운다.

검증
- tests/architecture/app-build-input.test.ts: TechLog 모듈은 받아들이고,
  같은 번들의 reference-feature는 거절한다.
- desktop CI env에서 이 커밋 전 head로 돌린 FE-GATE-012: 번들 예산은 PASS
  (229,223 / 230,400 B), check:app-build-input:bundle이 "production bundle
  contains feature \"tech-log\" not owned by app template-app"으로 실패.
donghyeon.kang merged commit c7649c7fea into main 2026-11-12 21:51:04 +00:00
donghyeon.kang deleted branch perf/initial-js-budget 2026-11-12 21:51:04 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/tech-log-frontend#9