chore(layout): 정리 2단계로 샘플 역할을 옮기고 샘플을 지운다 #12

Merged
donghyeon.kang merged 12 commits from chore/layout-2-sample-removal into main 2026-11-08 07:52:57 +00:00
Owner

무엇을, 왜

템플릿의 참조 기능과 예제 화면(샘플)이 게이트 9개의 시험 대상을 겸하고 있었다. 그래서 샘플만 지우면 visual·e2e·규모 측정·매뉴얼 예제 검사가 함께 깨진다. 이 PR은 정리 2단계다(design-docs repo-structure/04-frontend-layout.md 9.2절). 샘플이 맡던 역할을 먼저 옮기고, 그다음 샘플 폴더를 지운다.

  • (1) 갤러리를 Storybook story로 옮기고 visual 골든 대상을 바꾼다. 예제 화면 대신 플랫폼 라우트에서 셸 동작을 본다.
  • (2) local-draft 샘플을 tests/fixtures/indexeddb-consumer/ 소비자 fixture로 옮긴다.
  • (3) 매뉴얼 예제를 생성기 출력과 시험하는 코드 조각으로 바꾼다. problem details 예는 02 결정표의 코드 조각으로 둔다(D1).
  • (4) 참조 기능 e2e 3개의 역할을 생성 기능을 넣은 빌드의 e2e가 맡는다.
  • (5) 규모 측정을 생성 기능 사본으로 잰다.
  • (6) 참조 기능과 예제 화면을 지우고 registry를 다시 승인한다. /examples/platform 개요 화면은 남긴다(D2).

고른 방법과 버린 대안

  • e2e 기능 경로는 생성 기능을 넣은 빌드로 확인한다(S4 9.1절 (가)). component 시험으로 내리는 (나)는 싸지만 실제 브라우저 확인을 잃어서 버렸다. 새 webServer를 두지 않고 기존 prepareFixtureBuilds 방식으로 사본을 빌드한다.
  • 기능이 없는 템플릿에서는 초기 JS의 "새 context 비용" 정의가 첫 기능의 공용 코드까지 셌다. 그래서 정의를 첫 기능 비용과 context 비용 둘로 나눴다.

위험과 영향

  • 다운스트림 두 제품은 CHANGELOG 새 미출시 절의 「먼저 할 일」대로 지운 샘플 폴더를 정리해야 한다. 동기화 순서는 D6(태그 pre-layout-2026-11-07)를 따른다. 다운스트림 시험 병합은 하지 않았다.
  • tests/unit/manual-code-blocks.test.ts는 사본에 invoice-feature를 만든다. 같은 ID의 기능을 가진 다운스트림에서는 실패한다.
  • 날짜 붙은 기록 문서 4개에 샘플 ID 문자열이 남아 있다. 문서 결정대로 기록 본문은 고치지 않았다.
  • 커버리지가 84.30%에서 83.91%로 내렸다(문장 기준). 지운 참조 gateway 한 모듈의 문턱 행 4개만 정책에서 뺐고, 나머지 문턱은 그대로 통과한다.

검증

desktop에서 돌렸다. 로그는 /tmp/claude-gates/l2-*에 있다.

  • 커밋 12개 각각을 checkout해 test:unit을 돌렸고 모두 rc=0이다.
  • merge 게이트 2차(ad3a071f): FE-GATE-020과 001~012는 rc=0이다. FE-GATE-013은 rc=1(1초)인데, desktop 호스트의 bwrap user namespace 조건 때문이다. 부분 실행에서는 provider 경계 시험 18개만 실패했고 나머지 명령 7개는 rc=0이다. 실제 CI runner에서는 아직 확인하지 않았다.
  • visual 변이: 액션 토큰을 바꾸면 새 골든도 옛 골든처럼 실패하고, 되돌리면 통과한다.
  • test:coverage를 지우기 전과 뒤로 비교했다. 뒤는 Risk coverage PASS 378/378이다.

리뷰어가 볼 곳

  • tests/e2e/generated-feature.spec.ts, tests/unit/manual-code-blocks.test.ts
  • scripts/lib/ 생성 기능 사본 도우미, 규모 측정 planShapeFeatures
  • registry 재승인 파일과 성장 기준선(source.commit e3c8db48)

관련

## 무엇을, 왜 템플릿의 참조 기능과 예제 화면(샘플)이 게이트 9개의 시험 대상을 겸하고 있었다. 그래서 샘플만 지우면 visual·e2e·규모 측정·매뉴얼 예제 검사가 함께 깨진다. 이 PR은 정리 2단계다(design-docs `repo-structure/04-frontend-layout.md` 9.2절). 샘플이 맡던 역할을 먼저 옮기고, 그다음 샘플 폴더를 지운다. - (1) 갤러리를 Storybook story로 옮기고 visual 골든 대상을 바꾼다. 예제 화면 대신 플랫폼 라우트에서 셸 동작을 본다. - (2) local-draft 샘플을 `tests/fixtures/indexeddb-consumer/` 소비자 fixture로 옮긴다. - (3) 매뉴얼 예제를 생성기 출력과 시험하는 코드 조각으로 바꾼다. problem details 예는 02 결정표의 코드 조각으로 둔다(D1). - (4) 참조 기능 e2e 3개의 역할을 생성 기능을 넣은 빌드의 e2e가 맡는다. - (5) 규모 측정을 생성 기능 사본으로 잰다. - (6) 참조 기능과 예제 화면을 지우고 registry를 다시 승인한다. `/examples/platform` 개요 화면은 남긴다(D2). ## 고른 방법과 버린 대안 - e2e 기능 경로는 생성 기능을 넣은 빌드로 확인한다(S4 9.1절 (가)). component 시험으로 내리는 (나)는 싸지만 실제 브라우저 확인을 잃어서 버렸다. 새 webServer를 두지 않고 기존 `prepareFixtureBuilds` 방식으로 사본을 빌드한다. - 기능이 없는 템플릿에서는 초기 JS의 "새 context 비용" 정의가 첫 기능의 공용 코드까지 셌다. 그래서 정의를 첫 기능 비용과 context 비용 둘로 나눴다. ## 위험과 영향 - 다운스트림 두 제품은 CHANGELOG 새 미출시 절의 「먼저 할 일」대로 지운 샘플 폴더를 정리해야 한다. 동기화 순서는 D6(태그 `pre-layout-2026-11-07`)를 따른다. 다운스트림 시험 병합은 하지 않았다. - `tests/unit/manual-code-blocks.test.ts`는 사본에 `invoice-feature`를 만든다. 같은 ID의 기능을 가진 다운스트림에서는 실패한다. - 날짜 붙은 기록 문서 4개에 샘플 ID 문자열이 남아 있다. 문서 결정대로 기록 본문은 고치지 않았다. - 커버리지가 84.30%에서 83.91%로 내렸다(문장 기준). 지운 참조 gateway 한 모듈의 문턱 행 4개만 정책에서 뺐고, 나머지 문턱은 그대로 통과한다. ## 검증 desktop에서 돌렸다. 로그는 `/tmp/claude-gates/l2-*`에 있다. - 커밋 12개 각각을 checkout해 `test:unit`을 돌렸고 모두 rc=0이다. - merge 게이트 2차(`ad3a071f`): FE-GATE-020과 001~012는 rc=0이다. FE-GATE-013은 rc=1(1초)인데, desktop 호스트의 bwrap user namespace 조건 때문이다. 부분 실행에서는 provider 경계 시험 18개만 실패했고 나머지 명령 7개는 rc=0이다. 실제 CI runner에서는 아직 확인하지 않았다. - visual 변이: 액션 토큰을 바꾸면 새 골든도 옛 골든처럼 실패하고, 되돌리면 통과한다. - `test:coverage`를 지우기 전과 뒤로 비교했다. 뒤는 Risk coverage PASS 378/378이다. ## 리뷰어가 볼 곳 - `tests/e2e/generated-feature.spec.ts`, `tests/unit/manual-code-blocks.test.ts` - `scripts/lib/` 생성 기능 사본 도우미, 규모 측정 `planShapeFeatures` - registry 재승인 파일과 성장 기준선(`source.commit` `e3c8db48`) ## 관련 - design-docs `repo-structure/04-frontend-layout.md` 9.2절 2단계, `repo-structure/README.md` 3.4절(D1·D2·D6) - 1단계 PR #11
donghyeon.kang added 12 commits 2026-11-08 07:40:00 +00:00
예제 화면 /examples/ui·/examples/states가 visual 골든 2장과 갤러리
브라우저 시험의 대상이다. 2026-11-07 소유자 결정으로 예제 화면을
지우므로 그 역할을 먼저 옮긴다(design-docs repo-structure/
04-frontend-layout.md 9.2절 2단계 (1)).

두 갤러리 화면을 그대로 src/presentation/design-system/
galleries.stories.tsx로 옮겼다. 화면 단위 story(parameters.page)는
preview가 여백을 더하지 않아 앱 안과 같은 폭으로 그려진다. visual
설정은 Storybook 정적 빌드를 두 번째 web server로 띄우고
(TEST_VISUAL_WORKSHOP_PORT, 빌드 명령은 workshop 설정과 같은
scripts/lib/storybook-static.ts), 골든 2장은 그 story를 찍는다. 어두운
골든은 테마 선택기가 없어 시스템 dark(colorScheme)로 그린다. e2e의
갤러리 상호작용(텍스트 필드, 모달 포커스, 메뉴·탭·토스트, 열린 대화
상자 axe, 320px 리플로)은 tests/storybook/galleries.spec.ts로 옮겼다.

위험: 골든의 픽셀 색 허용치(threshold 0.2)는 그대로다. 미세한 토큰
변화는 옛 골든처럼 새 골든도 잡지 못한다.

검증(desktop): test:storybook 6 passed, test:visual 7 passed,
playwright-run-isolation 단위 시험 통과. 변이 확인: --color-action을
파랑→빨강으로 바꾸면 새 골든이 어두운 쪽 42,313px, 밝은 쪽 22,359px
차이로 실패했다. 옛 골든(main f33e4778)도 40,238px, 22,511px로 실패했다.
미세 변이(어두운 --color-danger red-500→600, 밝은 --color-danger-surface
색상각 25→145)는 옛·새 골든 모두 통과했다. 변이는 되돌렸다.
셸 동작을 보는 e2e(반응형, 스크롤 복원, 해시 링크, 타이포그래피,
건너뛰기 링크, 메뉴 이동, 운영 CSP, compact, en-US의 lang)가 지울 예제
화면을 열거나 그 메뉴를 누른다.

홈과 /examples/platform으로 옮겼다. 스크롤 복원은 계약 표가 그려진 뒤
스크롤하고, 해시 링크는 비동기 표보다 위에 있는 첫 절을 대상으로
한다. WebKit은 scroll anchoring이 없어 표 아래 대상이 1px 밀렸다.
갤러리 자체의 320px 리플로는 앞 커밋의 workshop 시험이 맡는다.

위험: 홈과 플랫폼 개요의 모양이 바뀌면 이 시험들의 대상도 바뀐다.

검증(desktop): 샘플을 지운 최종 트리에서 test:e2e 183 passed.
src/features/local-draft-feature는 기능이 아니라 IndexedDB recipe의
소비자다. 시험 5개와 recipe가 쓰고, 그래서 생성기에 NOT_A_FEATURE
예외가 있었다(S4 3.1절 S-3).

코드를 tests/fixtures/indexeddb-consumer/로 옮기고 import만 고쳤다.
NOT_A_FEATURE 표식은 이 폴더만 썼고 다운스트림 둘에도 없어 생성기에서
지웠다. 선언 없는 폴더는 밖으로 옮기라는 메시지로 실패한다. 매뉴얼
오류표, README, starter-experience, capability-consumer-experience,
patterns를 고쳤다.

위험: fixture는 기능 폴더 밖이라 기능 계층 규칙(dependency-cruiser)이
걸리지 않는다. recipe가 tests/ 아래 파일을 type import한다.

검증(desktop): test:contract, test:recipes, test:browser-capabilities,
test:unit 통과.
매뉴얼 예제 칸 14곳(S4 3.3절)과 산문 30여 곳이 참조 기능을
가리킨다. problem details(Envelope가 아닌 백엔드) 응답 매핑의 예는
참조 기능에만 있다.

생성기 출력이 그 모양을 만들면 그 경로로 바꿨다. 없으면 매뉴얼 안
코드 조각으로 썼다: problem details의 분류와 매핑(02 결정표 4절,
소유자 결정 D1), 도메인 모델, 검색값 스키마와 hook, 실패 행동 hook,
403 페이지 시험. 조각마다 manual-code-block 표식에 둘 경로를 적는다.
tests/unit/manual-code-blocks.test.ts가 저장소 사본에 create:feature
invoice-feature --with-create를 만들고 조각을 그 경로에 그대로 넣어
tsc(app, test), eslint, check:architecture, 그 기능 폴더의 vitest를
돈다. 조각의 동작은 tests/fixtures/manual-code-blocks/가 본다.

위험: 403 조각은 본문 없는 403으로 답한다. 공유 시나리오
forbidden-403(JSON 본문)은 jsdom + MSW에서 실행기의 본문 cancel이
끝나지 않아 화면이 로딩에 머물렀다. 실행기는 고치지 않았다. 사본에
이미 invoice-feature가 있는 프로젝트에서는 이 시험이 생성 단계에서
실패한다.

검증(desktop): test:unit 213 files 3096 passed(이 커밋까지),
verify:documentation PASS_SCOPED, lint 통과.
참조 기능 e2e 3개가 "기능 하나가 실제 브라우저에서 라우트·폼·
저장까지 된다"를 맡는다. 청크 복구, 부트 실패, preload 시험도 설치된
기능에 기댄다.

S4 9.1절 (가)대로 한다. scripts/lib/generated-feature.ts가 저장소
사본에 create:feature order-feature --with-create --keyed를 만들고,
spec은 그 사본의 빌드를 띄워 돈다. 참조 e2e의 검사(로그인, 목록, 폼
검증·이탈 확인·320px, en-US, 저장과 멱등 키, 429 뒤 다시 시도, 결과
불명과 같은 키 재전송, 키보드 포커스, 상태별 axe)를 생성 기능에
옮겼다. 오래된 탭의 청크 복구는 생성 기능 목록 라우트를, 부트 실패는
생성 기능을 넣은 사본을, preload 시험은 생성 기능 실행부 청크를 쓴다.

위험: 생성 기능의 동작만 본다. 제품 기능은 자기 spec이 필요하다.
사본 빌드가 spec과 브라우저마다 돈다(빌드 1초 안팎).

검증(desktop): 샘플을 지운 최종 트리에서 test:e2e 183 passed,
test:a11y 통과.
규모 측정(S4 3.1절 S-6)은 참조 기능을 복사해 이름을 바꿔 잰다.

create:feature의 planFeature로 사본마다 --with-create --keyed 기능
파일을 만든다(자기 계약 패키지와 topic, context당 200개). 초기 JS
기록에 firstFeatureGzipBytes를 더하고, context 비용은 둘째 기능을 새
context에 둘 때와 같은 context에 둘 때의 차이로 잰다. 옛 정의는 기능이
없는 템플릿에서 첫 기능의 공용 코드까지 context 비용으로 세어 5,788B로
상한 512B를 넘었다. 몇 바이트짜리 비용에는 기록 허용치 하한 16B를
둔다(빌드 ID에 따라 gzip이 1~2B 흔들린다). 이 트리(샘플이 아직 있는
상태)의 기록: 204,266B, 27파일, 첫 기능 797B, 기능 521B, context 12B.

위험: 성장 기준선(0·25·100개)은 샘플을 지운 트리에서 뒤 커밋이 다시
잰다. 이 커밋의 기준선 파일은 아직 참조 사본으로 잰 값이다.

검증(desktop): feature-shape-growth 등 4파일 57 passed, test:unit 통과.
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로
템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다.

참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록
7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트
참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은
비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을
하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다.
기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로
옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플
경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다.
레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약
기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능
539B, context 4B)을 다시 받았다.

위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은
수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에
공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는
플랫폼 코드에 남았다.

검증(desktop): check:types, lint, check:architecture, check:registries,
check:ci, verify:documentation, test:unit, test:component,
test:contract, test:integration, test:recipes, test:coverage(Risk
coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual,
test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76
checks), test:sample-removal SKIP, build, check:bundle.
config/scale/feature-shape-growth.json은 참조 기능 사본으로 잰 값이고,
기준 근거(feature-shape-ceilings.json의 axes)도 그 수치를 쓴다. 앞
커밋들이 측정 대상을 생성 기능으로 바꾸고 샘플을 지웠다.

샘플을 지운 트리(8c4b09b7, 수정 파일 없음)에서 node
scripts/scale/measure-feature-shape-growth.ts --sizes=0,25,100
--repeats=2 --write로 다시 쟀다. 기능당 tsc instantiation 약 10.1만,
tsc 메모리 약 31MB, 지연 JS 약 6.7KB와 9파일, 라우트 3개다. axes의
문장을 이 값과 firstFeatureGzipBytes에 맞췄다. 기준선 시험이 측정
대상(sourceFeature)도 본다.

위험: 시간 값은 desktop(i5-10400F, 부하 기록 포함)의 것이다. 400개 이상은
재지 않았다(D-18 선택).

검증(desktop): 같은 크기의 두 반복에서 컴파일러 수치가 같다.
tests/unit/feature-shape-growth.test.ts 통과.
정리 1단계(PR #11)와 2단계(샘플 역할 이전과 삭제)가 CHANGELOG에 없다.
다운스트림은 이 절을 보고 샘플 사본 처리와 기준선 재승인을 한다.

미출시 절 「48c7695b → 정리 단계」를 맨 위에 더했다. 「먼저 할 일」에
샘플 사본을 지우거나 자기 기능으로 옮기는 법, 레지스트리·CI 계약
기준선과 초기 JS 기록을 다시 받는 법, NOT_A_FEATURE 폴더 처리를 적고,
보안·계약 변경 표와 알려진 제한을 적었다. 절의 해시는 모두 이 브랜치
조상이다(git merge-base --is-ancestor로 확인).

위험: 두 다운스트림에 시험 병합을 하지 않아 충돌 수를 모른다.

검증: tests/unit/changelog-review-ids.test.ts 통과(desktop test:unit).
샘플 라우트를 지워 라우트가 3개가 되자 FE-GATE-003의 route-runtime 음성 fixture가
TS2740 대신 TS2739를 내 기대 진단과 어긋났다. tsc는 빠진 키가 많으면 TS2740,
적으면 TS2739를 낸다. fixture가 정확히 한 라우트만 빼도록 바꿔 어느 라우트 수에서나
TS2741이 나오게 하고 기대 진단을 맞췄다.
removal-fixture.test.ts는 선택 recipe 제거 사본 안에서도 돈다. 정리 대상으로 고른
test:recipes가 그 사본에는 이미 없어 FE-GATE-020이 실패했다. 어느 제거 사본에도
남는 test:integration과 그 산출물로 바꿨다.
donghyeon.kang merged commit 8327e22108 into main 2026-11-08 07:52:57 +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/clean-architecture-frontend-template#12