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가 다시 들어오지 않는지 본다.
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).
문제
런타임 문서가 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"으로 실패.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
무엇을, 왜
FE-GATE-012(번들 예산)가 main부터 실패한다. 초기 JS가 300,869 B(gzip, CI env)이고 예산은 204,800 B다. 초기 JS를 모듈 단위로 재 보니 첫 화면에 필요 없는 코드가 많았다.
이것들을 첫 사용 때 받게 해서 초기 JS를 71,645 B(24%) 줄였다. 남은 229,224 B 중 템플릿 공통 부분만 약 205 KB다. TechLog 코드를 모두 빼도 204,800 B 안에 들지 않는다. 그래서 예산을 템플릿 규칙대로 측정값에서 정했다: 225 KiB = 230,400 B.
8e0ea60eperf(tech-log)deferAsyncPort). Studio gateway는 Studio가 마운트될 때 바로 받기 시작한다02cf5ed3perf(studio)/studio에 들어갈 때 받는다(Suspense + ChunkRecoveryBoundary). 부팅 그래프 회귀 시험0bb8f1dfperf(build)51941a54와 같다)7558a8f4build(perf)8422c41efix(build)check:app-build-input:bundle, FE-GATE-012의 셋째 명령)가 직접 조립하는 TechLog를 받아들인다. 아래 「예산 뒤에 가려져 있던 실패」초기 JS 전후 (desktop CI env, gzip)
e5fe335emain → 커밋 1·2에서 빠진 모듈은 179개다. 모듈 단독 gzip 합으로 보면 다음과 같다(따로 압축한 값이라 합계는 실제 감소보다 크다).
adapters/mock23 KBadapters/static11 KBpresentation/studio10 KBdomain/content-format7.6 KBadapters/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 번들이 거절된다.tech-log를 이름으로 허용한다. 생성 인덱스 쪽 검사는 그대로다.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.md1106/15-01, 결정 D9)과 같다. CI env 측정값에 기능 하나의 상한 1 KiB를 더해 KiB 단위로 올린다.더 빼지 않은 것. 모듈 단독 gzip 기준으로 다음이 남았다.
문구와 계약은 부팅 때 합쳐서 검증하는 구조다. 이것을 빼려면 템플릿 1101/15-01(
298201f3, 기능 실행부를 라우트 진입 때 적재)을 옮겨야 하고, 그건 템플릿 동기화 일이다. TechLog는 템플릿af3d8e6(2026-09-28)에 있다.되돌림 규칙(문서에 적음). 15-01을 받는 템플릿 동기화 때, 또는 예산을 다시 넘을 때 다시 잰다. 같은 규칙으로 예산을 내린다. 측정값이 203,776 B 이하이면 200 KiB로 돌아간다.
위험과 영향
/studio첫 진입: Studio 셸 청크를 받은 뒤 화면 청크를 받는다(직렬 왕복 하나). 셸을 받는 동안 LoadingSurface가 보인다. Studio gateway 청크는 Studio가 마운트될 때 화면 청크와 같이 받는다.검증
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)다.SOURCE_DATE_EPOCH는 HEAD 커밋 시각)1회차(head
7558a8f4, 기능 소유 검사 수정 전)는 다음과 같았다.check:app-build-input:bundle에서 rc=1이었다(위 「예산 뒤에 가려져 있던 실패」).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).
하지 않은 것:
/studio에 들어가 보기. e2e는 MOCK 빌드다./studio첫 진입 시간을 lab에서 재기(FE-GATE-026은 돌리지 않았다).새 시험:
tests/features/tech-log/boot-graph.test.tstests/features/tech-log/deferred-async-port.test.ts(6건)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-infra-hardening.md), PR #8 남은 일.docs/operations/performance-evidence.md(예산 규칙, 1106/15-01 결정 D9),51941a54(1101/08-08),298201f3(1101/15-01).문제 런타임 문서가 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.