이정호

경력기술서 · Frontend Engineer / 프론트엔드 팀 리더

Emailljhmoa@gmail.com GitHubhttps://github.com/wjdgh4058 Phone010-8869-4058

경력 요약

※ 로워드 키워드 분석 플랫폼과 레듀 LMS는 더블티 재직 시 착수해 2025.01 로워드 이직 후 연속 수행한 프로젝트로, 아래 프로젝트 단위로 통합 기술합니다.

프로젝트 요약

1. Studio — 노코드 페이지 빌더 (2차)

Phase 1 — 표현 모델 재설계와 편집기 구축

배경 및 문제

블록 조립형이었던 1차 빌더는 2024.11 완성 이후 실제 하위몰 운영에 투입되었고, 약 1년간의 운영에서 구조적 한계가 드러났습니다. 특히 몰마다 성격이 달라 하위몰이 늘 때마다 그 몰에 맞는 블록을 새로 만들어 줘야 하는 상황이 반복되면서, "개발자를 빼기 위해 만든 도구가 다시 개발자를 부르는" 상태가 된 것이 2차 착수의 직접적 계기였습니다.

설계 목표

• 표현력 — 새 디자인 요구의 다수가 빌더 기능 추가 없이 조합으로 해결될 것
• WYSIWYG — 빌더에서 본 것과 실제 페이지가 일치할 것 (특히 모바일)
• SEO — 빌더 산출물이 진짜 서버 렌더 결과일 것 (랜딩은 검색 유입이 목적이므로 CSR 조립은 실격)
• 확장 프로토콜 — 팀원이 안전하게 노드/필드를 늘릴 수 있을 것
• 편집 UX — undo/redo, 복사·붙여넣기, 드래그 재정렬이 당연하게 동작할 것

① 표현 모델 — 블록에서 프리미티브로

interface ISchema { id: string; nodes: INode[] }
interface INode {
  id: string; type: NodeType; name: string;
  styles: Partial<Record<'basic'|'design'|'advanced', IStyleGroup>>;
  responsive?: { mobile?: Partial<Record<StyleTab, IStyleFields>> };
  children?: INode[];
}

• 노드를 3계층으로 분류 — layout(container/grid/gridCell) · default(text/button/image/video/blank) · widget(강의 캘린더, 수강 카드, 게시글, 리뷰 그리드/슬라이드, 클래스 슬라이드, 카드 캐러셀)
• 위젯을 프리미티브와 분리한 이유 — 위젯은 도메인 데이터를 스스로 가져오는 노드입니다. 같은 층위에 두면 "순수 표현 노드"와 "데이터 페칭 노드"의 경계가 흐려져 서버 렌더 경로 설계가 불가능해집니다
• 스타일을 3개 탭으로 분리한 이유 — 탭 구조가 곧 인스펙터 UI 구조가 되도록 데이터에 반영. 평평한 객체면 필드 목록만 보고 그룹핑할 수 없습니다
• 모든 스키마 변경은 불변(immutable) — undo/redo가 스냅샷 스택으로 성립하기 위한 전제

② 렌더링 아키텍처 — 하나의 렌더러, 두 개의 경로 (가장 중요한 결정)

RenderNode({ node, type: 'client' | 'server' })
   ├─ 'client' → BuilderNode(훅 사용) → *ClientWrapper → 시각 컴포넌트 + 편집 chrome
   └─ 'server' →                        *ServerWrapper(async) → 시각 컴포넌트

• 렌더러를 두 벌로 만들면 반드시 어긋납니다(1차에서 실제로 겪음). 시각 컴포넌트는 한 벌만 두고 래퍼로만 분기했습니다
• RenderNode 자체는 어떤 훅도 호출하지 않습니다. 훅을 쓰는 것은 type === 'client'일 때만 위임되는 내부 컴포넌트뿐 → 서버 컴포넌트 트리에서 그대로 사용 가능. 최상단에 훅이 하나라도 들어가면 사용자 페이지 렌더 전체가 깨지므로 아키텍처 불변식으로 문서화
• 위젯의 ServerWrapper는 async 서버 컴포넌트로 자기 데이터를 직접 fetch → 클라이언트 재요청 없는 진짜 SSR, 위젯을 몇 개 얹어도 워터폴 없음
• 편집 chrome은 ReactNode 주입으로만 전달 → 시각 컴포넌트는 chrome의 존재를 몰라도 됨(순수성 유지)
• 노드 타입 × 렌더 종류의 2차원 레지스트리로 관리, 미등록 타입은 null 반환(스키마 하위 호환)

③ 반응형 — 미디어 쿼리가 아닌 컨테이너 쿼리

문제 — 빌더의 모바일 모드는 뷰포트가 아니라 캔버스 폭을 375px로 제한합니다(브라우저 창은 그대로). 따라서 @media (max-width: 768px)는 프리뷰에서 절대 발동하지 않아 WYSIWYG이 원천적으로 불가능합니다.

해결 — 컨테이너 쿼리(@container) 채택. 375px 프레임을 컨테이너로 만들면 프리뷰에서 정확히 발동하고, 실제 페이지에서는 래퍼에 container-type: inline-size를 주면 동일하게 동작합니다.

• sparse override 모델 — node.responsive.mobile[tab][field]에 바뀐 필드만 저장, 미지정 필드는 PC 값 상속. 전체 트리를 복제하면 PC 수정이 모바일에 전파되지 않아 두 벌 유지보수가 됩니다
• 저장은 현재 device 모드에 따라 자동 분기, 표시는 병합값 → 필드 에디터 컴포넌트는 device 개념을 몰라도 됨
• buildResponsiveCss — PC 스타일과 모바일 병합 스타일을 diff해 노드별 @container (max-width:768px) 규칙을 생성·주입, 노드 루트마다 안정적인 ldn-{id} 클래스 부여
• "모바일에서 값을 지운 경우"의 비대칭 처리 — PC에만 있는 키는 지운 것이므로 initial 리셋 선언을 먼저 emit(shorthand 리셋 → longhand override 순으로 캐스케이드 정합)
• grid 예외 처리 — template이 인라인 계산되어 diff가 닿지 않고 PC의 cols × rows는 모바일 폭에서 항상 깨지므로, override 유무와 무관하게 1열 스택으로 자동 collapse(행 높이 변환은 렌더 컴포넌트와 동일 함수로 일치)
• 컨테이너 컨텍스트를 모바일 모드에서만 생성 — PC 모드에서 만들면 사이드바로 프리뷰가 좁아질 때 모바일 스타일이 새어나옴
• 전역 브레이크포인트 이원화 — 뷰포트 기준 msm은 프리뷰에서 발동하지 않으므로 동일 임계값의 컨테이너 쿼리 변형 cmsm을 정의하고 "스튜디오 렌더 노드 안에서는 cmsm, 그 외에는 msm"을 규칙화

④ unified vs device-aware — 침묵 버그의 구조적 차단

실제 겪은 버그 — 모바일 모드에서 위젯 설정을 바꿨는데 화면이 무반응. 값은 정상 저장됨. 원인은 렌더가 그 필드의 모바일 override를 읽지 않기 때문이었습니다.

이건 개별 버그가 아니라 모델의 구멍이었습니다. device-aware가 기본값인데 렌더가 지원하지 않는 필드가 그 기본값을 받으면 반드시 이 증상이 납니다. 따라서 모든 필드를 두 부류 중 하나로 명시 분류하도록 강제했습니다.

"위젯 필드 추가 시 이 분류를 의도적으로 결정할 것"을 가이드에 명문화했습니다. 기본값을 그냥 쓰면 조용히 망가지는 종류라, 코드가 아니라 프로세스로 막아야 한다고 판단했습니다.

⑤ undo/redo — "사용자의 한 동작 = 한 번의 undo"

• 모든 스키마 변경이 단일 진입점(applySchema)을 통과하도록 강제 — 히스토리는 우회 경로가 하나라도 생기면 즉시 신뢰를 잃습니다
• 최신 스키마를 useRef로 동기 추적 — useState 값은 배칭 때문에 push 시점에 직전 상태가 아닐 수 있습니다. 스냅샷 스택은 직전 상태의 정확성이 생명이라 ref로 동기 확보하고 렌더 트리거만 state로 분리
• 500ms coalesce 창 + coalesceKey — 컬러 피커 드래그는 초당 수십 번 값이 바뀌어 그대로 push하면 undo를 40번 눌러야 합니다. field:{device}:{nodeId}:{tab}:{field}를 키로 같은 필드의 연속 편집을 한 항목으로 묶고, 다른 필드로 이동하면 자동으로 끊기게 처리
• 구조 변경(생성/삭제/이동/붙여넣기)은 병합 없이 항상 1항목, 히스토리 상한 100, undo/redo 시 coalesce 상태 리셋
• 입력 중에는 단축키를 브라우저에 양보 — input/textarea/contentEditable 포커스 시 ⌘Z를 텍스트 undo에 넘김. 인라인 텍스트 편집이 있는 빌더에서 이걸 안 하면 "글자 하나 지우려다 노드가 사라지는" 최악의 UX가 됩니다

⑥ 드롭 규칙 — 스키마 정합성을 규칙으로 강제

삭제도 타입별로 의미를 다르게 정의했습니다. gridCell 삭제는 제거가 아니라 초기값 리셋 — 셀이 사라지면 그리드가 깨지므로 사용자의 "지우기" 의도를 "내용 비우기"로 번역했습니다.

⑦ 클립보드 — 복사 대상의 의미론

가장 까다로웠던 것은 "gridCell을 복사하면 무엇을 붙여넣어야 하는가"였습니다. 셀 자체를 복제하면 정합성이 깨지므로 셀의 내용(children)을 복제 대상으로 삼고, 대상 컨텍스트에 따라 셀 내부 append / 형제 삽입 / 루트 추가로 분기했습니다. 붙여넣을 때마다 서브트리 전체에 새 uuid를 재발급하고(id 충돌 = 선택·렌더 전부 오작동), 붙여넣은 노드를 자동 선택해 바로 편집 가능하도록 했습니다.

⑧ WYSIWYG 카드 템플릿 에디터 — 폭에 무관한 편집

카드 안의 슬롯(이미지/제목/부제목/설명)을 자유 배치하는 기능으로, 핵심 문제는 편집 화면과 실제 페이지의 카드 폭이 다르다는 것이었습니다.

편집기와 실제 렌더가 동일한 헬퍼 모듈을 공유하도록 모듈 경계를 강제했습니다(한쪽만 고치면 편집 결과와 출력이 갈라짐). 편집 모달은 로컬 draft + 자체 undo/redo를 갖고 저장 시에만 커밋해 취소가 무손실이며, 모달 내부 ⌘Z가 전역 undo로 새어나가지 않습니다. 히스토리 항목이 당시 보던 슬라이드 인덱스를 함께 기억해 undo 시 화면이 튀지 않도록 했습니다.

⑨ 두 개의 CSS 캐스케이드 함정 규명

(1) !important의 레이어 우선순위 역전

• 증상 — 주입한 !important 규칙이 아무 효과가 없는데, 하필 Tailwind 클래스가 붙은 요소에서만 그렇다
• 원인 — 프로젝트가 important: true라 모든 유틸이 @layer utilities 안의 !important로 나갑니다. CSS 캐스케이드에서 !important는 레이어 우선순위가 역전되어, unlayered !important는 specificity가 아무리 높아도 layered에 집니다. <style> 주입은 기본이 unlayered입니다
• 해결 — 주입 CSS를 @layer utilities { … }로 감싸 같은 레이어에서 specificity로 승부. 재현 조건이 좁아 다음 사람이 반드시 헤맬 종류라 증상 패턴까지 가이드에 기록

(2) 중첩 container-type이 측정 대상을 바꿈

• 증상 — 캐러셀의 모바일 규칙이 데스크탑에서도 발동. 카드를 여러 장 띄워 카드가 좁아지는 순간에만
• 원인 — 이름 없는 @container는 가장 가까운 조상 컨테이너를 기준으로 합니다. 폰트 cqw 스케일링을 위해 각 카드에 container-type을 부여해 둔 상태라, 위젯 내부 쿼리가 위젯이 아닌 카드를 측정하고 있었습니다
• 해결 — 노드 루트에 named container를 주고 이름으로 질의, 카드 컨테이너는 cqw 전용으로 이름 없이 유지 → 두 종류의 컨테이너가 역할별로 분리되어 간섭 없음

⑩ 확장 프로토콜 문서화

노드 추가가 여러 파일에 걸친 등록 절차라 하나라도 빠지면 조용히 실패합니다(스키마엔 들어가는데 화면/인스펙터에 안 보임). 이 실패 모드를 없애기 위해 절차를 문서로 고정했습니다.

1. nodes.tsx          노드 템플릿 정의
2. components/nodes/  시각 컴포넌트 + Client/Server 래퍼
3. RenderNode.tsx     타입 등록   ← 빠지면 렌더 안 됨
4. renderField.tsx    필드 등록   ← 빠지면 인스펙터에 안 보임
5. fields/**          필드 에디터 추가 (+ unified 여부 결정)
6. public/studio/     아이콘/썸네일

추가로 75개 필드에 반복되던 배선 보일러플레이트를 useField 훅으로 추출하면서, unified 결정 지점을 한 곳에 모아 ④의 실수를 구조적으로 줄였습니다.

Phase 1 성과

• 새 디자인 요구를 빌더 기능 추가 없이 조합으로 해결하는 비율이 크게 증가
• 편집기와 사용자 페이지가 동일 시각 컴포넌트를 공유해, 노드가 늘어도 일치 비용이 증가하지 않는 구조 확보
• 빌더 산출물이 진짜 SSR 결과물이라 랜딩페이지 SEO 요구 충족
• 노드 카탈로그·스키마 규약·드롭 규칙·반응형 모델·위젯별 불변식을 담은 상세 개발 가이드를 작성해 팀 확장 대비

Phase 2 — 재사용 컴포넌트 시스템 (커스텀 위젯)

배경 및 문제

Phase 1로 표현력 문제는 해결됐지만, 운영이 시작되자 다른 종류의 병목이 드러났습니다.

• 여러 페이지에 같은 배너/CTA/후기 섹션이 반복해서 들어갑니다
• 문구 하나를 바꾸려면 그 섹션이 들어간 모든 페이지를 하나씩 열어서 똑같이 고쳐야 합니다
• 페이지가 늘어날수록 이 비용이 선형으로 증가하고, 누락된 페이지가 반드시 생깁니다

핵심 설계 결정 — "복사가 아니라 참조"

이 기능 전체가 단 하나의 결정 위에 서 있습니다. 페이지는 위젯의 내용을 저장하지 않는다. widgetId 참조만 저장하고, 펼치는 것은 렌더 시점에만 한다.

이 결정을 코드가 지키도록 구조화했습니다.

• customWidget 노드는 styles.basic.fields.widgetId만 가진 leaf입니다
• 의도적으로 CAN_HAVE_CHILDREN_TYPES에서 제외 → 드롭 규칙(Phase 1 ⑥)이 자동으로 내부 삽입을 막아, 어떤 내용도 저장된 스키마에 들어갈 수 없습니다
• "저장 시점에 children을 채우는 순간 이건 조용히 스냅샷이 된다"를 가이드에 명문화 — 코드로 막을 수 없는 부분이라 문서로 방어했습니다

① 편집 모드 분리 — 하나의 빌더로 두 대상을 편집

• [id]가 new면 생성 — id는 첫 저장 시 발급. 생성/편집을 별도 화면으로 나누지 않아 UI가 하나로 유지됩니다
• 각 라우트는 RSC로 레코드를 로드해 Studio에 props로 내려줍니다. Studio는 자기 데이터를 절대 직접 fetch하지 않습니다 → 이 규칙이 백엔드 전환을 사소하게 만듭니다. 데이터 소스가 바뀌어도 편집기는 전혀 모릅니다
• mode는 컨텍스트로 전 편집기에 전달되어 저장 대상과 LNB 팔레트 구성을 결정합니다

② 중첩 금지 — 의존성 그래프를 1단계로 고정

커스텀 위젯 안에 커스텀 위젯을 허용하면 순환 탐지, 재귀 resolve, 다단계 캐시 무효화가 전부 필요해집니다. 운영상 요구가 없는 기능에 이 복잡도를 지불할 이유가 없다고 판단해 한 단계로 고정했습니다. 단, "금지"는 UI에서 숨기는 것만으로는 지켜지지 않아 3중 방어로 강제했습니다.

UI만 막고 끝냈다면 클립보드로 뚫렸을 것이고, 서버 검증이 없었다면 API 직접 호출로 뚫렸을 것입니다.

③ 결정적 id 재발급 — 랜덤이면 hydration이 깨진다

cloneNodeWithScopedIds(node, instanceId)  →  `${instanceId}__${originalId}`

• 왜 재발급이 필요한가 — 노드별 CSS가 .ldn-{id}로 스코프되고 buildResponsiveCss도 node.id를 키로 씁니다. 같은 위젯을 한 페이지에 두 번 넣으면 id가 겹쳐 서로의 스타일을 덮어씁니다
• 왜 uuid가 아니라 규칙인가 — 이 펼침은 서버와 클라이언트 양쪽에서 각각 일어납니다. 랜덤 id면 두 결과가 달라져 hydration이 깨집니다. 인스턴스 노드 id를 접두어로 붙이는 결정적 규칙이라야 양쪽이 동일한 결과를 냅니다

④ ReadOnlyNodeContext — "편집 불가"와 "상호작용 불가"는 다르다

펼쳐진 내부 노드는 저장된 스키마에 존재하지 않습니다. 여기에 편집 UI를 붙이면 hover 테두리가 떠서 정작 위젯 자체의 선택 테두리가 묻히고, 선택/삭제 버튼이 보이지만 눌러도 스키마에서 찾을 수 없어 아무 일도 일어나지 않습니다. 그런데 동작까지 죽이면 안 됩니다. 이건 미리보기이므로 버튼은 눌리고, 캐러셀은 넘어가고, 캘린더는 페이지가 넘어가야 합니다. 정확히 두 가지만 꺼야 합니다.

후자를 켜두면 동작하는 것처럼 보이다가 조용히 되돌아갑니다 — updateNodeField가 스키마에 없는 노드를 찾지 못하기 때문입니다. 사용자 입장에서 가장 나쁜 종류의 버그입니다.

컨텍스트를 쓴 이유 — 노드 렌더는 각 ClientWrapper가 재귀로 돌립니다. props로 내리려면 모든 wrapper를 수정해야 하지만, 컨텍스트로 흘리면 RenderNode 한 곳에서만 판단하면 됩니다.

⑤ 삭제 가드 — 참조 모델의 필연적 부작용 대응

페이지가 id만 들고 있으므로, 참조된 위젯을 지우면 그 페이지들에서 경고 없이 사라집니다.

• removeWidget이 사용처를 조회해 throw + 사용 중인 페이지 목록 반환
• 런처는 목록에 "N곳에서 사용 중"을 표시하고 확인 단계 전에 차단
• 삭제 직전에 사용처를 다시 조회 — 목록의 usageCount는 화면을 연 시점의 값이라, 그 사이 다른 사람이 페이지에 추가했을 수 있습니다

⑥ 위젯 피커 모달 — 두 개의 함정을 정면으로 해결

(1) 명령형 모달을 쓸 수 없었던 이유

디자인 시스템의 LDModal은 명령형이라 내부적으로 createRoot를 호출합니다. 즉 별도의 React 트리가 되어 App Router 컨텍스트가 닿지 않습니다. 피커는 위젯 미리보기를 렌더하는데, 위젯 7종이 전부 useRouter/Link를 사용하므로 invariant expected app router to be mounted로 크래시했습니다. → 선언형 LDModalView를 빌더 트리 안에서 렌더하도록 전환. DOM은 portal되지만 React 트리는 유지되어 모든 컨텍스트가 살아 있습니다. 각 호출부(LNB의 삽입, LIB의 교체)가 open 상태를 소유하고 결과를 onClose로 받는 구조로 정리했습니다.

(2) 썸네일 대신 라이브 미리보기

카드마다 위젯의 실제 노드를 1200px로 렌더한 뒤 카드 폭에 맞춰 scale합니다. → 썸네일이 절대 낡지 않습니다. 성립 조건 두 가지를 별도로 처리했습니다.

• no-op 스튜디오 컨텍스트 제공자(PreviewSelectionProvider) — 모든 ClientWrapper가 useStudioSelection()을 무조건 호출하므로, 실제 provider가 없는 곳에서 렌더하면 throw합니다
• 1200px 요소에 container-type: inline-size — 없으면 @container 규칙이 모달 폭을 측정해 미리보기가 모바일 레이아웃으로 렌더됩니다

여기서는 pointer-events-none이 맞습니다(④와 반대) — 썸네일은 클릭을 카드 선택으로 통과시켜야 하기 때문입니다. 같은 기법이 맥락에 따라 정답이 되기도 오답이 되기도 한다는 점을 문서에 함께 남겼습니다.

(3) 자동 스크린샷 캡처는 검토 후 기각

html2canvas 방식의 자동 캡처를 검토했으나 CORS가 걸린 CDN 이미지, 구글 호스팅 웹폰트, 컨테이너 쿼리 레이아웃, embla의 transform에서 전부 깨집니다. 무엇보다 캡처 실패는 위젯에 대해 거짓말하는 썸네일을 남깁니다. 라이브 렌더는 비용이 들지만 절대 거짓말하지 않습니다. 기각 근거를 문서에 남겨 다음 사람이 같은 검토를 반복하지 않도록 했습니다.

(4) 성능 대응

위젯이 늘어날 것을 전제로 서버 기반 이름 검색 + 페이지네이션을 적용하고, WidgetPreview에 memo를 걸어 검색어 타이핑·카드 선택 같은 목록 무관 상태 변화에 전 카드가 재렌더되지 않도록 했습니다(카드 하나가 노드 트리 전체를 그리므로 비용이 큼). 목록 화면은 nodes를 제외한 가벼운 요약 API를, 피커는 nodes 포함 API를 쓰도록 응답을 용도별로 분리했습니다.

⑦ 백엔드 부재 상황의 영속 계층 설계

백엔드 API가 아직 없는 상태에서 기능을 완성해야 했습니다.

• 함수 시그니처와 호출 방식을 최종 형태 그대로 확정하고, 몸통만 임시 파일 I/O로 구현(listDocuments / getDocument / insertDocument / updateDocument / removeDocument / listWidgets / listWidgetDetails / getWidget / insertWidget / updateWidget / removeWidget / getWidgetUsage) → 전환 시 각 함수 안쪽만 fetch로 교체되고 호출부는 손대지 않습니다
• 목록 응답을 { list, totalCount } 형태로 미리 맞춰 백엔드 페이징 계약과 어긋나지 않도록 처리
• 저장소를 os.tmpdir()에 둔 이유 — 프로젝트 안에 두면 next dev의 watcher가 매 저장마다 리빌드합니다

⑧ API 전환 체크리스트 문서화 (108줄)

"함수 몸통만 바꾸면 끝"처럼 보이지만 그때 함께 결정해야 하는 것이 있어서 별도 문서로 남겼습니다.

• 캐시 태그 설계(지금은 캐싱이 아예 없음) — 문서와 위젯에 각각 태그를 붙여야 revalidateTag('studio-widget-{id}') 한 줄로 그 위젯을 쓰는 모든 페이지가 무효화됩니다. 따라서 "문서 + 참조 위젯을 한 번에 조립해 주는 엔드포인트"를 만들면 안 된다고 명시했습니다 — 태그가 하나로 뭉개져 위젯 수정 전파라는 핵심 기능이 죽습니다. 라운드트립을 아끼려다 기능을 잃는 전형적인 함정입니다. 서버 경로에서는 CustomWidgetServerWrapper가 렌더 트리 안에서 자기 정의를 fetch하므로 태그가 해당 라우트에 자동 등록되어, 문서 응답에 widgetIds를 미리 담을 필요가 없습니다
• 중복 fetch 핫스팟 — 같은 위젯 N개 인스턴스 = getWidget N회(서버는 fetch 캐시가 완화하지만 클라이언트 빌더는 그렇지 않음), 피커 카드마다 데이터 위젯 API 호출, getWidgetUsage의 전 문서 스캔(→ 역참조 테이블로 대체)
• 현재 구현과 실제의 차이 — 인증/테넌트 분리, 동시성(파일 통째 재작성 → 두 탭 동시 저장 시 유실), 에러 전달(현재는 throw new Error(메시지)인데 프로덕션에서는 Next가 메시지를 가림 → rsltCd 기반 문구 생성 필요), 영속성, 정렬/페이징
• 깨지면 기능 자체가 무너지는 불변식 4가지를 명시

이 문서를 쓴 이유 — 전환 작업을 제가 하지 않을 수도 있고, 하더라도 몇 달 뒤입니다. "코드에 아직 없는 것"이야말로 인계에서 유실되는 부분이라고 판단했습니다.

⑨ 저장 흐름 — 작업물 유실 방지

• dirtyRef로 미저장 변경 추적(스키마 변경·undo/redo·이름 편집에서 set, 저장 시 clear) → 취소 확인 모달 + beforeunload 가드
• 저장 실패 시 편집 상태를 유지하고 실패를 화면에 알립니다. 조용히 넘기면 사용자가 저장된 줄 알고 탭을 닫아 작업물을 잃습니다. 서버가 이유를 준 경우(예: 중첩 금지)는 그 문구를 그대로 노출
• 임시저장 — 저장 후 편집 화면에 머뭅니다. 신규 문서가 이때 확정되면 window.history.replaceState로 주소만 교체합니다. router.replace를 쓰면 라우트가 다시 렌더되면서 편집 상태와 undo 히스토리가 전부 날아갑니다

⑩ code 노드 — 통제된 escape hatch

노코드 빌더에는 반드시 "여기서만은 직접 짜야 하는" 구간이 생깁니다(외부 임베드, 일회성 마크업). 이를 위해 입력한 HTML을 그대로 렌더하는 노드를 추가했습니다.

• sanitize하지 않습니다 — 레포의 기존 정책(관리자 입력 HTML을 그대로 렌더)과 일치하고, sanitize하면 escape hatch의 취지 자체가 사라집니다. 다만 이 선택의 성격을 문서에 명시
• <script>가 빌더와 실제 페이지에서 다르게 동작합니다 — 빌더는 innerHTML 주입이라 HTML 스펙상 실행되지 않고, 유저 페이지는 문서에 스트리밍되어 파싱되므로 실행됩니다. 이걸 "고쳐서" 빌더에서도 실행되게 만들면 안 됩니다 — 서드파티 임베드가 어드민 UI 안에서 실행되어 관리자 화면을 깨뜨릴 수 있습니다. 고치는 대신 에디터에 각주로 명시하는 쪽을 택했습니다
• <style>이 노드 스코프가 아니라 전역이라는 점도 저렴한 해결책이 없어 경고로 처리
• 편집은 사이드바가 아닌 모달 + 라이브 프리뷰. 에디터 모듈을 await import()로 지연 로드해 prism이 빌더 초기 번들에 들어가지 않도록 했고, prism 토큰 색상은 .studio-code-editor 스코프에 두어 Toast UI 에디터의 코드블록과 충돌하지 않도록 격리
• 빈 HTML이면 null을 렌더해 유저 페이지에 빈 패딩 박스가 남지 않게 처리

⑪ RSC 번들 오염 사고 — 유저 페이지 전체 500

• 증상 — 빌더와 무관한 모든 사용자 페이지의 서버 렌더가 500. 오류는 TypeError: Cannot read properties of undefined (reading 'call')
• 원인 — util.ts가 LNB 카탈로그(nodes.tsx)에서 그리드 셀 템플릿을 import하고 있었습니다. 그런데 nodes.tsx는 모듈 스코프에 lucide 아이콘과 JSX를 든 빌더 전용 파일입니다. RenderNode가 util.ts를 import하므로, util.ts가 import하는 모든 것이 모든 사용자 페이지의 RSC 번들에 딸려 들어가 모듈 초기화 단계에서 터진 것입니다
• 해결 — 순수 데이터 모듈(gridCellTemplate.ts, 아이콘 없음)로 분리하고, 빌더용으로만 nodes.tsx에서 재export
• 규칙화 — "렌더 경로에 있는 어떤 파일도 LNB 카탈로그를 import하지 않는다. 카탈로그의 값이 필요하면 아이콘 없는 모듈로 추출한다." 증상이 원인과 완전히 동떨어져 있어(빌더를 건드렸는데 사용자 페이지가 죽음) 다음 사람이 반드시 헤맬 종류라, 사고 경위와 함께 가이드에 남겼습니다

⑫ 타입 수준 exhaustiveness 확보

nodeRenderers를 Record<NodeType, …>로 타이핑해, NodeType에 타입을 추가하고 렌더러 등록을 빠뜨리면 컴파일 에러가 나도록 했습니다. Phase 1의 확장 프로토콜에서 "등록을 빠뜨리면 조용히 빈 노드가 된다"가 가장 흔한 실수였는데, 이 중 타입으로 막을 수 있는 절반을 타입으로 옮긴 것입니다.

Phase 2 성과

• "컴포넌트 1회 수정 → 사용 중인 모든 페이지 자동 반영"이 성립. 반복 콘텐츠의 동기화 비용과 누락 위험 제거
• 노코드 환경에 컴포넌트 개념을 도입해, 운영자가 자기만의 디자인 시스템을 축적할 수 있는 구조 확보
• 참조 모델의 실패 모드(중첩, 고아 참조, 삭제 영향, id 충돌, hydration 불일치)를 전부 사전 설계하고 코드·UI·서버 3계층으로 방어
• 백엔드 부재 상황에서 API 계약을 먼저 확정해 기능을 완성하고, 전환 시 결정해야 할 것을 별도 문서로 인계

현재 상태 및 남은 과제

• 완료 — 편집기 전체, 17종 노드, 75개 필드 에디터, undo·redo·클립보드, 드롭 규칙, 반응형 모델, 서버 렌더 경로, 편집 모드 분리, 커스텀 위젯 시스템, 런처, 저장·임시저장·이탈 가드, code 노드
• 진행 중 — 임시 파일 스토어 → 백엔드 API 전환(체크리스트 문서화 완료), 사용자 페이지 라우트 전환
• 남은 과제 — 캐시 태그 설계 적용, 클라이언트 측 getWidget 요청 dedupe, 피커 카드 lazy 렌더, getWidgetUsage 역참조 테이블화, 스키마 버전 필드 + 마이그레이션 체인, 순수 로직 테스트 도입

2. 브릿지(Bridge) — 웹호스팅 SaaS

2-1. 서비스 도메인 분리 — 장애 영향도 축소

배경 및 문제

호스팅 서비스는 결제와 서버 프로비저닝을 다루기 때문에 장애 비용이 큽니다. 단일 앱 구조에서는 랜딩 페이지 수정 배포가 실패하면 결제 콘솔과 로그인까지 함께 중단되고, 어드민의 무거운 화면 하나가 사용자 서비스 성능에 영향을 줍니다. 서비스 성격도 완전히 달랐습니다 — 랜딩은 SEO·정적 렌더링이, 콘솔은 인증·실시간성이 중요하고, 어드민은 색인되면 안 됩니다.

선택과 이유

서비스를 도메인·배포 단위까지 완전히 분리하는 방향을 택했습니다. 단일 앱 내부에서 라우트 그룹으로만 나누는 방식은 코드 경계는 만들어주지만 런타임과 배포를 공유하므로 장애 격리가 되지 않기 때문입니다. 요구사항이 "코드 정리"가 아니라 "영향도 축소"였으므로 프로세스가 분리되어야 했습니다.

구현 및 결과

• 5개 앱을 각각 독립 Next.js 애플리케이션으로 구성, output: 'standalone' 빌드
• 앱별 별도 ECR 리포지토리와 별도 컨테이너로 배포, 앱별 미들웨어에서 각자의 보호 경로·리다이렉트 정책을 독립 관리
• 앱 간 이동은 referer 파라미터 왕복 리다이렉트로 처리
• 한 서비스의 배포·장애가 다른 서비스로 전파되지 않는 구조를 확보. 부수적으로 앱별 독립 배포 주기와 번들 격리(어드민의 테이블·차트 코드가 랜딩 번들에 섞이지 않음)를 획득

2-2. Turborepo 모노레포 — 공통 컴포넌트 공유

배경 및 문제

앱을 5개로 분리하자 버튼·인풋·모달·토스트 같은 공통 UI를 서비스마다 중복 구현하게 되었습니다. 더 큰 제약은 디자인 시스템이 아직 완성되지 않은 단계였다는 점 — 컴포넌트 스펙과 디자인 토큰이 계속 바뀌는 시기였습니다.

선택과 이유

공용 컴포넌트를 별도 npm 패키지로 publish하는 방식을 먼저 검토했으나 기각했습니다. 디자인 시스템이 확정되기 전에는 publish → 버전 bump → 5개 앱 install 사이클이 매 변경마다 반복되어 변경 속도를 감당할 수 없기 때문입니다. 대신 Turborepo + pnpm workspace를 선택해 workspace:* 링크로 패키지 수정이 별도 배포 없이 즉시 전파되게 했습니다.

구현

• 2계층 단방향 의존 — 앱 → @loword/nextjs-ui(Next 의존: Provider·서버액션·훅·테이블) → @loword/ui(프레임워크 비의존: 순수 UI·디자인 토큰·Zod 스키마). 역방향 import 금지를 규약화해 UI 패키지가 Next에 종속되어 Storybook 등 타 환경에서 쓸 수 없게 되는 것을 방지
• 설정 전체를 패키지화(tailwind-config / eslint-config / typescript-config / prettier-config)해 5개 앱의 lint·타입·포맷 기준을 단일 소스로 통일
• Tailwind v4 패키지별 prefix 격리 — @loword/ui는 ui:, @loword/nextjs-ui는 nui:, 앱은 prefix 없음. 세 출처의 클래스가 서로를 덮어쓰는 문제를 규약으로 원천 차단하고 앱 레이아웃의 스타일 import 순서까지 고정
• LD* 공용 컴포넌트 33종 구축 — 폼 17종(인풋·드롭다운·체크·라디오·데이트/타임 피커·검색·숫자 포맷), 테이블/페이지네이션, 차트, 토스트, 리치 에디터, 모달, 파일 업로드. 1,086줄 디자인 토큰 CSS와 Storybook 카탈로그로 수렴
• 공용 폼 계층 — react-hook-form + Zod 스키마를 패키지로 공유. LDForm(SPA 제출) / LDNativeForm(백엔드 네이티브 POST) 2종으로 서로 다른 제출 방식을 동일 인터페이스로 처리
• DI로 앱별 차이 흡수 — 4개 앱의 SocketProvider 래퍼가 쿠키 조회 함수의 import 경로만 다르고 나머지가 동일했던 중복을, 해당 함수를 prop으로 주입받는 AuthSocketProvider로 추출하는 구조를 설계해 각 앱을 3줄 래퍼로 축소
• 타입 안전 퍼널 컴포넌트 — NonEmptyArray 제네릭으로 step 이름을 컴파일 타임에 제한, 원패스 호스팅 11스텝 구매 퍼널에 적용

결과 — 5개 앱이 동일한 UI·검증·스타일 기준을 공유하면서도 각자 독립 배포되는 구조를 유지했고, 공용 패키지 수정이 즉시 전 앱에 반영되어 디자인 시스템 형성기의 빈번한 변경을 배포 사이클 없이 흡수했습니다.

2-3. 도메인 간 캐시 무효화 아키텍처 ★

배경 및 문제

도메인을 분리해 장애 격리를 얻은 대가가 캐시에서 나타났습니다.

• 5개 앱이 각각 독립 Next 서버(standalone 컨테이너)이므로 Data Cache도 앱마다 따로 존재합니다. 한 앱에서 revalidateTag를 호출해도 다른 앱의 캐시는 그대로 남습니다
• 그런데 한 도메인에서 일어난 변경은 다른 도메인의 화면에 반영되어야 합니다. SSO에서 내 정보를 수정하면 메인 헤더와 콘솔이 함께 바뀌어야 하고, 백엔드가 프로비저닝을 완료하면 콘솔 목록·상세가 갱신되어야 하고, 어드민이 파트너를 승인하면 파트너 대시보드의 권한과 통계가 바뀝니다
• 앱마다 캐시 정책을 자율적으로 두면 "어떤 화면은 최신, 어떤 화면은 5분 전 데이터"가 되고, 결제·호스팅 상태를 다루는 서비스에서 이는 곧바로 CS로 이어집니다

선택과 이유

• 캐시를 끄는 방식(cache: 'no-store')은 기각 — 조회 성능과 서버 부하를 포기하는 선택이고, 개인화 데이터가 많은 서비스라 무캐시 전환의 비용이 컸습니다. 문제는 캐시 자체가 아니라 무효화 경로의 부재라고 판단했습니다
• 캐시 태그를 앱 경계가 아니라 데이터 경계로 정의 — 태그를 앱 단위로 나누면 "내 정보 변경"이라는 하나의 사건에 대해 호출자가 앱마다 다른 태그를 알아야 합니다. 데이터 단위(users-me, hosting-list, domain-detail …)로 정의하면 같은 태그를 여러 앱이 동시에 구독할 수 있어, 사건 하나가 여러 서비스의 캐시를 함께 무효화합니다
• 무효화 신호를 3방향으로 분리 — 변경 주체가 셋(프론트 / 백엔드 상태 변경 / 실시간 이벤트)이고 각각 도달 시점과 보장 범위가 다르기 때문입니다

① 태그 규약

• 모든 조회에 공용 태그 + <tag>-<userId> 개인 태그를 함께 부착. 개인 태그는 accessToken JWT의 sub를 읽어 생성
• 무효화는 개인 태그만 사용하도록 규약화 — 공용 태그로 무효화하면 전체 사용자 캐시가 한 번에 날아가므로, 공용 태그는 전 사용자 공통 데이터에만 사용
• 총 85종 태그 운영. users-me는 4개 앱(main·console·affiliate·sso) 전부의 허용 목록에 포함되어, 내 정보 변경 하나가 4개 서비스의 캐시를 동시에 무효화

② 무효화 3경로

③ 웹훅 규격화

• 공용 팩토리 함수 하나로 4개 앱의 라우트를 구성하는 구조를 설계. 각 앱은 자기가 책임지는 태그 접두사 목록만 선언(main 2개 / console 14개 / affiliate 4개 / sso 1개)하므로 "어느 도메인이 어느 데이터를 캐시하는가"가 코드에 선언적으로 드러남
• 접두사 매칭(tag === prefix || tag.startsWith(prefix + '-'))으로 개인 태그를 자동 허용 — 백엔드는 hosting-list-1234만 보내면 되고, 어느 앱이 그 태그를 쓰는지 알 필요 없음
• 공유 시크릿 헤더 인증(불일치 시 401), body·태그 배열 검증(400), 허용목록 밖 태그 거부
• { ok, accepted, rejected } 응답과 서버 로그로 무효화 성공/거부를 관측 가능하게 함 — 태그를 목록에 빠뜨렸을 때 조용히 stale 되지 않도록

④ 역할 분담 규약 문서화

"웹훅 = 서버 캐시를 비우는 쪽 / 소켓 = 화면을 다시 그리게 하는 쪽"으로 책임을 명시하고, 둘 중 하나만 있으면 각각 "사용자가 새로고침해야 보임" / "refresh해도 캐시된 옛 데이터가 다시 옴"이 되는 이유를 시퀀스 다이어그램으로 팀에 공유했습니다.

결과 — 독립 배포·독립 캐시 구조를 유지하면서도 한 도메인의 상태 변경이 나머지 서비스 화면에 일관되게 전파되는 경로를 확보했습니다. 전체 사용자 캐시가 무효화되는 사고를 규약으로 차단하고, 새 태그 추가 시 백엔드·프론트 양쪽에 반영하는 프로토콜을 정착시켰습니다.

2-4. Socket.IO 실시간 상태 반영

배경 및 문제

호스팅 인스턴스 생성, 도메인 연결, 워드프레스 설치는 백엔드 비동기 작업으로 수 분이 걸립니다. 사용자가 완료 여부를 알기 위해 새로고침을 반복해야 하는 상태였고, 이는 "결제했는데 아무 일도 안 일어난다"는 문의로 이어집니다.

선택과 이유

폴링이 아니라 소켓을 택한 이유는 완료 시점이 수십 초에서 수 분까지 편차가 커, 짧은 간격 폴링은 서버 부하가 크고 긴 간격은 체감이 나쁘기 때문입니다. 화면 갱신 방식으로는 RSC 구조를 유지하는 router.refresh()를 기본으로 택했습니다 — 클라이언트 페칭으로 전환하면 깜빡임이 없지만 서버 컴포넌트를 클라이언트 컴포넌트로 바꿔야 해 구조 변경 비용이 크기 때문입니다.

구현

• 이벤트 카탈로그 2단 추상화 — 32개 도메인 이벤트(hosting / domain / wordpress / storage / push / affiliate / session)를 상수화하고, 이를 화면 단위 그룹 8개(hostingListRefresh, hostingStatusRefresh, domainSettingRefresh, wordpressDetailRefresh 등)로 재조합. 화면은 개별 이벤트가 아니라 그룹을 구독하므로 새 이벤트 추가 시 화면 코드를 수정하지 않음(구독 지점 28곳)
• 훅 레이어 토큰 선갱신 — useSocketEvent이 콜백 실행 전 ensureValidToken()을 await. 소켓 이벤트로 촉발된 재조회가 만료 토큰으로 나가 401이 되는 문제를 28개 구독 지점에 일괄 적용
• 재연결 폭주 차단 — connect_error를 429(rate limit, 토스트 안내) / 401·unauthorized(재시도 없이 즉시 disconnect)로 분기
• 갱신 방식 2가지를 공식 가이드로 문서화 — ① revalidateXxx(); router.refresh();(기본) ② 클라이언트 fetch(깜빡임 없음, 구조 전환 필요). "①로 시작하고 깜빡임이 문제되면 ②로"라는 판단 기준을 규약화하고, 렌더링 없는 핸들러 컴포넌트를 서버 컴포넌트 옆에 배치하는 패턴으로 정형화
• 클레임 변경 이벤트 특수 처리 — 파트너 승인/거절/정지는 JWT 클레임 자체가 바뀌므로 토큰 재발급 → 내 정보 재조회 → 스토어 갱신 → refresh 순서로 처리. 계정 정지(session:revoked)는 안내 후 강제 로그아웃

결과 — 프로비저닝·상태 변경이 사용자 조작 없이 화면에 반영됩니다. 무효화(웹훅)와 리렌더(소켓)를 짝으로 설계했기 때문에 refresh 시점에 최신 데이터가 보장됩니다.

2-5. 크로스 서브도메인 SSO 인증

배경 및 문제

서비스를 도메인별로 분리했으므로 인증도 도메인 경계를 넘어야 했습니다. 또한 브릿지 서비스는 약관 동의와 주소 등록이 선행되어야 이용 가능한데, 이 온보딩 상태를 각 앱이 개별 판단하면 5곳에 중복 로직이 생깁니다.

선택과 이유

토큰을 localStorage가 아닌 상위 도메인 공유 쿠키에 담았습니다. localStorage는 origin 격리라 서비스 간 공유가 불가능하고, 무엇보다 미들웨어(서버)에서 읽을 수 없어 서버 사이드 가드를 만들 수 없기 때문입니다. 온보딩 상태 판단은 별도 API 조회 대신 JWT 클레임을 사용했습니다 — 미들웨어에서 추가 네트워크 왕복 없이 판정할 수 있기 때문입니다.

구현

• SSO 발급 JWT를 상위 도메인 쿠키에 저장해 5개 앱이 공유. 운영/개발 환경이 같은 쿠키 스코프를 공유하므로 쿠키 키를 환경별로 분리
• 미들웨어의 5가지 책임 정의 — ① 보호 경로 가드(토큰 없으면 SSO 로그인으로, 복귀용 referer 포함) ② jwtVerify 후 클레임 기반 온보딩 유도(약관 미동의 → 약관, 주소 미등록 → 주소, 검증 실패 → 로그아웃) ③ accessToken 부재 + refreshToken 존재 시 미들웨어에서 refresh 후 set-cookie 릴레이 ④ x-device-type·x-pathname 요청 메타 주입 ⑤ 어필리에이트 유입 추적
• fetcher 계층 이원화 — serverFetch(401 + 특정 errorCode일 때 refresh 후 1회 재시도, 새 쿠키 반영) / serverFetchNotRefresh(재시도 없음, 캐시 태그 조회용). 사용 기준을 문서화
• 서비스별 기본 복귀지 쿠키 도입 — referer가 유실되면 무조건 다른 서비스 홈으로 튕기는 문제가 잦았습니다. sessionStorage는 origin 격리로 서비스 간 공유가 불가능하고 SSO 미들웨어가 읽을 수 없어 상위 도메인 쿠키로 설계했습니다. 이미 같은 값이면 Set-Cookie를 생략해 CDN 캐시 오염을 방지하고, 쿠키 값의 percent 인코딩이 클라이언트에서 디코딩되지 않아 상대경로로 해석되던 버그를 실측으로 확인해 정규화 처리를 추가

결과 — 5개 서비스가 하나의 로그인 상태를 공유하고, 온보딩 가드가 미들웨어 한 곳에 집중되어 앱별 중복이 제거되었습니다.

2-6. 마케팅 트래킹 인프라 (GA4 · GTM · Meta Pixel)

배경 및 문제

도메인 분리에는 마케팅 측면의 대가가 따랐습니다. 유입(랜딩) → 가입(SSO) → 결제(콘솔)가 서로 다른 도메인에서 일어나므로 GA 세션이 도메인 경계에서 끊기고 전환 경로가 소실됩니다. 광고비 집행 판단의 근거가 되는 데이터가 신뢰할 수 없는 상태였고, 이커머스 전환 이벤트 규격 자체가 없었습니다.

선택과 이유

• GA4 cross-domain linker 설정으로 세션을 이어붙였습니다. 도메인 분리는 장애 격리를 위해 유지해야 하는 결정이었으므로, 구조를 되돌리는 대신 측정 레이어에서 보정하는 방향을 택했습니다
• Meta Pixel은 자체 컴포넌트로 직접 구현 — GTM 경유 설치도 가능했지만, noscript 폴백과 초기화 시점을 프론트에서 명시적으로 통제하기 위해 next/script로 직접 부트스트랩
• 모든 이벤트에 환경 게이트 적용 — GTM 컨테이너 측 분기도 가능했지만, 개발·QA 트래픽이 운영 지표를 오염시키는 것은 되돌릴 수 없는 손실이라 코드 레벨 차단을 이중 안전장치로 택했습니다

구현

• 5개 앱 전체에 GTM 컨테이너 + GA4 + Meta Pixel 설치. GA4는 afterInteractive 전략으로 직접 부트스트랩하며 linker.domains에 3개 도메인 등록
• GA4 User-ID 전송 — accessToken JWT의 sub를 서버에서 디코드해 user_id로 전송, 크로스 도메인·크로스 디바이스 사용자 단위 분석 가능. 동시에 user_id 유무를 전환 이벤트의 인증 게이트로 겸용
• 이커머스 전환 이벤트 9종 규격화 — GA4 권장 스키마(ecommerce.transaction_id / value / currency / items[])에 맞춰 purchase(도메인·호스팅), begin_checkout 4종, refund(콘솔 환불로 결제 반대편 지표 수집), signup, login, submit_form, pre-registration, Meta CompleteRegistration 2종
• page_view에 한글 페이지명 매핑 설계 — 앱 타입 × pathname → '원 패스 호스팅 도메인 설정' 형태의 page_title 생성. 동적 라우트(공지 상세 slug 디코딩)와 카테고리 쿼리 필터까지 처리해, 마케팅팀이 URL이 아닌 화면 이름으로 퍼널을 조회할 수 있게 함
• 30일 어필리에이트 어트리뷰션 — 유입 쿼리(ref/ru)를 상위 도메인 쿠키에 30일 보관해 메인에서 유입한 추천 코드가 SSO 가입 완료 시점까지 유지되게 하고, 모든 리다이렉트 분기를 쿠키 처리 래퍼로 감싸는 규약 정의
• 익명 방문자 식별자 — 미들웨어에서 1주 만료 방문자 ID를 발급. isbot으로 봇 트래픽을 제외하고 HTML 문서 요청에만 발급하며, 프록시 환경을 고려해 x-forwarded-proto/x-forwarded-host 기반으로 secure·domain 옵션을 동적 결정. 채널톡 프로필에 연결해 비회원 상담자를 식별

결과 — 도메인이 분리된 상태에서도 유입 → 가입 → 결제 전환 경로를 하나의 세션으로 측정할 수 있게 되었고, 마케팅팀이 GA4에서 화면 단위 퍼널과 이커머스 전환을 조회할 수 있는 기반을 확보했습니다.

2-7. 전환 지표 신뢰도 개선

배경 및 문제

기존 login 이벤트가 로그인 시도 직전에 status: 'success'로 발사되어 비밀번호 오류·OAuth 취소까지 전환으로 집계되고 있었습니다. 근본 원인은 구조적 제약이었습니다 — SSO는 통합 로그인이라 성공 시 백엔드가 302로 다른 서비스에 착지시키므로 SSO 프론트에는 성공 콜백이 존재하지 않습니다. 회원가입도 폼이 백엔드에 네이티브 POST를 쏘기 때문에 성공 콜백이 없어, 제출 시점에 발사하면 이메일 중복·서버 에러까지 가입으로 집계되었습니다.

선택과 이유

• 클릭 시점에 상위 도메인 쿠키를 심고 착지한 서비스에서 소비해 발사하는 방식을 택했습니다. 로그인 성공을 프론트가 확신할 수 있는 유일한 지점이 "성공했을 때만 도달하는 착지 페이지"였기 때문입니다
• 이 쿠키를 "auth 상태의 복제본이 아니라 로그인이 남긴 일회성 메시지"로 정의하고, 쓰기 = 클릭 시점 / 삭제 = 소비 시점 / 로그아웃은 미개입으로 묶었습니다. 토큰 상태와 동기화하거나 로그아웃에 리셋 지점을 두면 반드시 어긋납니다 — 토큰 만료 시 미들웨어가 로그아웃 경로를 타지 않는 경우, 보호 경로가 로그인으로 보내는 경우, 다른 탭 로그아웃, 수동 쿠키 삭제 중 하나만 새어도 해당 사용자는 이후 모든 로그인에서 이벤트가 영구 누락됩니다. 네이밍도 PENDING·IS_ 류를 피해 "값이 곧 method"임이 드러나게 해 후임자가 토큰과 동기화하려는 오해를 하지 않도록 했습니다
• 기존 page_view 컴포넌트에 얹지 않고 별도 컴포넌트로 분리 — 두 앱은 page_view를 끄고 login만 수집하는 상태여서 실제로 수명이 다르기 때문
• 익스텐션 로그인은 추적을 제거 — OAuth 콜백이 웹 앱에 착지하는지 확인되지 않아, 착지하지 않으면 쿠키가 소비되지 않고 남아 다음 방문에서 오발사합니다. 부정확한 수치보다 부재를 택했습니다

구현

• 상위 도메인 쿠키 유틸을 공용 패키지에 범용 함수로 신설(GTM 전용이 아니라 다른 크로스 서브도메인 쿠키에도 쓸 수 있게)
• 착지 앱 root layout에서 마운트 1회 쿠키를 읽고 즉시 삭제한 뒤 발사. 실패 시 되돌아오는 SSO 로그인 페이지에서는 소비하지 않음
• user_id는 앱별 서버 액션을 prop 주입받아 전달(공용 패키지가 서버 액션을 직접 호출하지 않는 기존 관례 유지). 값이 없으면 미발사하도록 해 로그인 성공 확인을 겸함
• 회원가입은 백엔드가 성공 시에만 리다이렉트하는 완료 페이지에서 발사. 이메일 가입과 소셜 가입의 리다이렉트 파라미터가 서로 달라 특정 파라미터를 게이트로 걸면 한쪽이 누락되므로, 완료 페이지 도달 자체를 신호로 삼음
• 중복 발사 차단 — sessionStorage 키로 새로고침·뒤로가기·재진입에 의한 중복 집계를 방지하고, 새 가입 시도 시작 시 키를 비워 같은 탭 재가입 누락도 방지
• 완료 페이지가 미보호 경로라 링크를 배포하면 방문자마다 가입이 집계되는 문제를 user_id 게이트로 차단
• 배포 전 영향도를 마케팅·데이터팀에 사전 공유 — "login 수치가 하락하므로 기존 지표와 연속선상에서 해석 불가", "GA4 태그에 User ID 필드 매핑 필요", "signup은 GA4 추천 이벤트명이 아니므로 GTM 트리거 별도 등록 필요"를 문서화

결과 — 로그인·가입 전환 수치가 실제 성공 건수를 반영하게 되었고, 사용자 단위 분석이 가능해졌습니다. 남은 미확인 전제(소셜 재로그인이 동일 착지 페이지를 경유하는지 등)는 오집계 가능성과 함께 문서에 명시해 후속 확인 대상으로 남겼습니다.

2-8. SEO — 색인 대상과 비대상의 분리

같은 모노레포에 색인되어야 하는 서비스(랜딩)와 색인되면 안 되는 서비스(어드민·콘솔·개인화 구매 퍼널)가 공존한다는 점이 이 프로젝트 SEO의 고유 조건이었습니다. 메타데이터는 페이지별 작성 대신 getMetadata() 팩토리 + 상수 중앙화로 구성했고(손으로 쓰면 누락이 반드시 발생), robots.txt 정적 파일 대신 환경 인지형 robots.ts를 택해 환경 전환 시 파일을 수동 교체하는 실수를 없앴습니다 — 운영이 아니면 전체 disallow로 개발·QA 색인을 차단하고, 운영에서는 개인화 경로만 선택적으로 제외합니다.

2-9. 빌드 / 배포 파이프라인

문제 — 모노레포에서 앱별 독립 배포를 하려면 각 이미지가 자기 앱과 그 의존 패키지만 포함해야 합니다. 레포 전체를 복사해 빌드하면 이미지가 커지고, 무관한 앱의 변경만으로도 매번 전체 의존성이 재설치됩니다.

선택 — turbo prune --docker로 서브그래프를 추출하는 방식을 택했습니다. 이것이 2-1의 "앱별 독립 배포"와 2-2의 "모노레포"를 동시에 성립시키는 지점입니다. 또한 의존성 메타(out/json)만 먼저 복사해 install 레이어를 캐시하고 소스는 그 뒤에 복사하도록 순서를 잡았습니다 — 소스 변경이 install 레이어를 무효화하지 않게 하기 위해서입니다.

• Docker 멀티스테이지: prune 전용 builder → installer(json 선복사 → pnpm install → full 복사 → 내부 패키지 빌드 → next build) → runner(standalone + static + public만, 비루트 유저 실행)
• 앱별 Dockerfile 5개를 동일 패턴으로 정형화, deploy.sh 하나로 ECR 로그인 → 빌드 → 태깅 → 푸시를 원커맨드화하고 dev 인자로 개발/운영 이미지 분리
• turbo.json globalEnv에 웹훅 시크릿을 등록해 환경 변수가 캐시 키에 반영되도록 처리

2-10. 렌더링 / 성능 최적화

• 정적 prerender 보존 — 루트 레이아웃의 Provider가 useSearchParams()를 호출해 정적 prerender되는 모든 페이지의 빌드가 실패하던 문제가 4개 앱에 공통으로 있었습니다. 페이지가 해당 훅을 직접 쓰는지와 무관하게 공통 조상에서 발생하는 문제였습니다. children 전체를 Suspense로 감싸면 빌드는 통과하지만 정적 렌더링이 CSR로 폴백되므로, 토큰 감지 로직만 별도 컴포넌트로 분리해 그 컴포넌트만 Suspense로 격리하고 children은 경계 밖에 두었습니다. 4개 앱 동시 해결 + 정적 렌더링 유지
• 렌더 비용 절감 — 700줄 규모의 테이블 컴포넌트에서 컬럼 cell 함수가 매 렌더마다 재생성되어 셀 내부 팝오버가 11회 마운트되던 문제를, 셀 렌더링을 4개 컴포넌트로 분리해 필요 시점에만 마운트되도록 해결
• 미들웨어 성능 — 클레임 검증을 JWT 로컬 검증으로 처리해 미들웨어에서의 추가 API 왕복을 제거했고, 기본 복귀지 쿠키는 값이 동일하면 Set-Cookie를 생략해 CDN 캐시를 보호

2-11. 시니어 사용자를 위한 콘솔 대시보드 정보 구조 개선

배경 및 문제

사용자 콘솔에서 가장 자주 필요한 정보는 생성한 블로그의 주소와 워드프레스 관리자 주소·ID·비밀번호입니다. 로그인해서 확인하려는 것이 사실상 이것뿐인 경우도 많습니다. 그런데 기존 구조에서는 이 정보에 도달하려면 3단계를 이동해야 했고, 특히 고연령 사용자층에서 경로를 찾지 못해 이탈하거나 문의로 이어지는 문제가 있었습니다.

1차 판단 — 찾게 만들 것인가, 찾을 필요를 없앨 것인가

메뉴 이름을 바꾸거나 안내를 추가하는 방식은 택하지 않았습니다. 경로를 설명해서 찾게 만드는 것보다 가장 자주 쓰는 정보를 진입 화면으로 끌어올리는 편이 낫다고 봤고, 인스턴스별 카드를 대시보드에 직접 배치해 블로그 주소·이름·관리자 주소·ID·PW를 한 화면에서 확인하도록 했습니다.

2차 판단 — 진입 단계 축소만으로는 답이 되지 않음

실제로 제약이 있었습니다. 인스턴스당 블로그를 3개까지 생성할 수 있어, 한 슬라이드에 카드가 3벌 놓입니다. 주소·이름·관리자 주소·ID·PW가 세 세트로 늘어나면 화면은 정보로 가득 차고, 정작 지금 확인하려는 블로그가 어느 것인지 알기 어려워집니다. 그래서 문제를 "무엇을 올릴 것인가"에서 "올린 것 중 무엇을 지금 보게 할 것인가"로 다시 잡았습니다.

해결 — 정보를 줄이지 않고 위계를 부여

• 최근 생성·수정된 블로그를 기본 선택 상태로 표현 — 방금 만들었거나 방금 고친 인스턴스가 지금 확인하려는 대상일 가능성이 가장 높다고 보고, 선택 기준을 최신 활동 시점으로 정함
• 나머지 카드는 opacity를 낮춰 배경으로 물러나게 함 — 같은 정보량을 유지하면서 시선이 한 곳에 먼저 닿게 하는 방식. 감춘 것이 아니라 순서를 준 것이므로 다른 인스턴스도 즉시 접근 가능
• 인스턴스가 늘어도 화면이 세로로 길어지지 않도록 캐러셀로 묶고 현재 위치 인디케이터를 노출

값의 실제 사용 목적이 "읽는 것"이 아니라 "다른 곳에 붙여넣는 것"이라는 점에서 항목마다 복사 동작을 배치했습니다. 드래그 선택 자체가 부담인 사용자를 고려한 결정입니다. 블로그 열기와 관리자 페이지 이동은 새 창으로 분리해 콘솔로 돌아오는 경로를 잃지 않도록 했고, 호스팅·도메인이 없는 계정에는 빈 상태를 그대로 두지 않고 다음 행동을 제시하는 안내를 노출했습니다.

남은 과제

주요 정보 도달률과 관련 문의 건수를 개선 전후로 비교해 효과를 수치로 확인하는 것이 다음 단계입니다.

2-12. 보안

• 취약점 대응 패치 리드 — 2026년 공개된 React/Next.js 취약점 12건(미들웨어 우회 3건, SSRF, DoS, XSS, 캐시 포이즈닝 등)에 노출된 상태를 확인하고 패치 버전으로 상향(next 15.4.8 → 15.5.18, react/react-dom 19.1.0 → 19.1.7). 앱 5개와 Storybook의 직접 선언뿐 아니라 워크스페이스 패키지의 peer 최소 버전까지 상향해 dev 트리로 끌려오던 구버전을 제거하고, 5개 앱의 최종 해석 버전을 전수 확인. 메이저 버전 점프(16.x)는 리스크가 크다고 판단해 제외하고 15 라인 유지를 택함
• 시크릿 관리 — .gitignore에 규칙이 있는데도 .env 4개가 계속 커밋 대상으로 잡히던 문제의 원인을 ".gitignore는 untracked 파일에만 적용된다"는 점으로 특정하고, git rm --cached로 추적을 끊은 뒤 git check-ignore로 검증. 원격 히스토리에 남은 값은 노출로 간주하고 rotate 필요성을 명시적으로 고지, 히스토리 재작성은 별도 작업으로 분리
• 설계 레벨 방어 — 웹훅에 시크릿 헤더 인증 + 태그 허용목록을 두어 임의 캐시 무효화를 차단. 인수인계 문서에는 .env의 키 이름만 기록하고 값은 남기지 않는 원칙을 적용하고, JWT 검증 시크릿이 클라이언트 번들에 포함될 수 있는 위치에 하드코딩된 리스크는 값을 노출하지 않고 사실만 기록해 환경 변수 이관을 권고
• 입력 검증 정책 전환 — 이름·주소 필드의 특수문자·이모지 차단 요청이 반복되자, 차단목록 방식은 유니코드 블록이 수십 개라 새 기호마다 코드를 추가해야 하고 이모지는 BMP 밖이라 기존 문자 클래스로 잡히지도 않는다는 점을 근거로 허용목록 방식으로 전환. 완성형 음절만 허용하는 단일 정규식으로 자소분리·심볼·이모지·전각을 한 번에 차단하고, 그 부작용으로 macOS의 NFD 한글이 막히는 문제까지 normalize('NFC') 선처리로 해결해 20여 개 필드에 일괄 적용

2-13. 대표 트러블슈팅

① 추천인 코드 유실 — 파트너 정산 직결

추천 링크로 유입해도 코드가 저장되지 않는 문제. 원인은 두 겹이었습니다 — 미들웨어의 3개 리다이렉트 분기(약관·주소·로그아웃)가 쿠키를 심는 래퍼를 거치지 않아 이미 파싱한 코드가 버려졌고, 동시에 복귀용 referer에 query string이 빠져 있어 쿠키에도 URL에도 남지 않았습니다. 3개 분기를 래퍼로 감싸고 referer에 search를 포함해 해결했으며, 인접 앱의 동일 계열 결함(복귀 referer가 자기 오리진이 아님)도 발견해 별건으로 기록했습니다.

② 추천인 화면의 유입 서비스 오판정 (간헐적 재현)

A 서비스로 유입했는데 B 서비스의 추천 코드가 자동 입력·잠기는 현상. 원인은 판정 근거가 "이번 요청이 무엇인가"가 아니라 "이 탭이 예전에 어디를 거쳤는가"(sessionStorage)였던 것입니다. 부가 원인으로 저장 로직이 useReducer의 리듀서 내부 side effect에 있어(React가 금지하는 non-pure reducer 패턴) 리렌더가 실제 일어나야만 저장되는 구조였고, 이것이 간헐성의 원인이었습니다. 전역 우선순위는 소비자가 8곳이라 건드리지 않고 해당 화면에서만 URL의 명시적 신호가 세션 추론을 덮도록 읽기 쪽을 고쳤고, dispatch를 래핑해 호출 즉시 동기 저장하도록 쓰기 쪽도 고쳤습니다 — 호출부 13곳을 한 줄도 바꾸지 않고 적용했습니다. 이전 커밋의 원인 서술이 부정확했던 점(업데이트 큐는 provider의 fiber에 붙으므로 언마운트로 유실되지 않음)까지 문서에서 정정했습니다.

③ 타인 리소스 접근 시 빈 화면 렌더

남의 도메인 ID로 설정 페이지에 접근하면 크래시 없이 값만 비어 있는 설정 화면이 렌더되고, 그 상태로 저장하면 id가 undefined인 채 요청이 나가던 문제. 원인은 공용 fetcher가 response.json() 본문만 반환하고 HTTP status를 버리는 설계여서 403이 페이지에 "데이터 없음"으로 도착한 것이었습니다. status를 살리는 fetcher 변경은 영향 범위가 넓어, 판정 기준을 응답 본문의 errorCode로 두고 목록으로 redirect하는 방식을 택했습니다. 추가로 Next.js 내부 구현(fetch 패치·incremental cache)까지 확인해 403이 Data Cache에 저장되지 않고 캐시 키에 Cookie가 포함되므로 사용자 간 응답 혼입이 없음을 검증했으며, 동일하게 무방비인 다른 상세 페이지들을 남은 범위로 명시했습니다.

④ 비회원 결제 이탈 후 상태 복원

비회원이 도메인을 검색·선택하고 결제를 누르면 로그인으로 이탈했다가 복귀 시 화면이 초기 상태로 보여, 검색부터 다시 반복해야 했습니다. 상태는 localStorage에 남아 있었으나 복원 경로가 없었습니다. 결제 훅에 로그인 이탈 시점을 호출부가 가로챌 수 있는 옵셔널 콜백을 추가(다른 앱·다른 결제 케이스에 영향 없는 추가형 변경)하고, 복원을 2단계로 설계했습니다. 재개 플래그를 URL 쿼리로 넘기지 않은 이유는 referer가 SSO의 세션·미들웨어를 거치며 중첩 인코딩되기 때문입니다. 도메인 목록 재조회는 여러 페이지 순차 요청이라 결제 모달 표시가 눈에 띄게 늦어져 결제 모달을 닫은 시점으로 미뤘고, 이미 카드가 등록된 회원에게 카드 등록창이 다시 뜨는 문제(비동기로 채워지는 값을 클로저가 고정)도 함께 해결했습니다.

2-14. 팀 리딩 · 프로세스

• 컨벤션 수립 — 5개 앱 공통 디렉터리 규약(middleware / app / api(serverFetchers·actions·clientFetchers) / provider / stores), 페이지 작성 패턴(page.tsx는 서버 컴포넌트로 조회, 화면 로직은 클라이언트 컴포넌트에 위임), 라우트 그룹 레이아웃 분기, 네이밍 규칙(인터페이스 I, 타입 별칭 T, 공용 컴포넌트 LD 접두사), 커밋 메시지 형식, 브랜치 전략 정의. "한 앱을 이해하면 나머지 4개도 같다"를 목표로 설계
• CHANGELOG 문화 정착 — "원인/이유 → 수정 → 비고 → 알려진 한계 → 남은 과제" 포맷을 코드 변경과 같은 커밋에 포함하도록 규칙화. 미확인 전제와 미해결 범위까지 명시해 다른 담당자가 이어받을 지점을 남기며, 이전 기록의 원인 분석이 틀렸을 때 정정 기록을 남기는 것도 포함
• 온보딩 문서 작성 — 스타터 템플릿 원문 상태였던 README를 527줄 인수인계 문서로 재작성. 앱·패키지 지도, 디렉터리 규약, 환경 전환 방식, 인증 흐름, 캐시 태그 규약, 웹훅 요청 규격, 소켓 이벤트 카탈로그, 웹훅과 소켓의 역할 분담 시퀀스 다이어그램, 스타일 규약, 배포 절차와 체크리스트, "알아두면 좋은 함정" 9개를 담았습니다. 코드만 봐서는 의도를 알 수 없는 설계를 문서화하는 것이 핵심 목적
• 크로스팀 협업 — 백엔드와 캐시 태그·웹훅 요청 규격·소켓 이벤트명을 합의하고 태그 추가 시 양쪽에 반영하는 프로토콜을 수립. 마케팅·데이터팀과 GA4/GTM 이벤트를 정의하고 지표 단절·User-ID 매핑 등 배포 영향도를 사전 공유. 서버팀 배포 산출물 전달 경로도 정리

3. @loword/loword-design-system — 전사 공용 디자인 시스템

3-1. UI·스타일·기능을 분리한 3-Layer 아키텍처 설계

배경 및 문제

기존 monorepo의 레거시 UI 패키지는 UI와 기능이 강결합되어 커스터마이징이 사실상 불가능했습니다. 새 요구사항마다 컴포넌트 내부 분기를 추가하는 방식이라, 컴포넌트가 커질수록 분기가 곱으로 증가하고 수정 시 영향 범위를 예측할 수 없었습니다.

결정과 근거

Ant Design류의 "하나의 컴포넌트 + props 분기" 대신 Base → Custom → Function 3계층 분리를 채택했습니다.

핵심 원칙은 "확장은 아래 레이어 수정이 아니라 위 레이어 추가로만 한다"입니다. props 분기는 요구사항이 늘 때마다 기존 코드를 건드려야 하지만, 레이어 분리는 기존 것을 그대로 둔 채 새 레이어를 추가하면 되기 때문입니다.

결과

• 단일 SelectBase에서 LDSelect와 LDMultiSelect가 Base 수정 없이 파생 — 설계 의도가 실제로 검증된 사례
• 폼 연동은 LDFormField 하나(react-hook-form + render-prop)를 재사용해 29개 폼 래퍼로 확장. 검증 관심사를 Function 레이어에 격리해 디자인 컴포넌트가 폼 상태를 몰라도 되게 했습니다
• 신규 컴포넌트 추가 절차를 단계별 가이드로 문서화해 팀원이 동일한 구조로 작업하도록 표준화

3-2. 아키텍처 규칙을 접근성 결함 탐지 도구로 활용 + 접근성의 CI 게이트화

배경 및 문제

"Base는 스타일을 갖지 않는다"는 규칙이 선언에 그치면 시간이 지나며 무너집니다. 실제로 일부 컴포넌트는 Base 382줄이 디자인을 전부 갖고 Custom 57줄은 className만 통과시키는 역전 상태였습니다. 더 근본적으로는 a11y 애드온이 test: 'todo'로 설정되어 있어 위반이 있어도 테스트가 통과했고, 그래서 접근성 결함이 계속 쌓이고 있었습니다.

결정과 근거

• Base를 정화하면서 디자인 시스템 스타일이 적용된 파트를 Styled Compound API로 승격시키는 절차를 표준 리팩터링으로 정의. 기존 Single API도 동일 파트를 재사용하도록 재조립해 공개 API 변경 없이(breaking change 0) 내부 구조만 교체
• a11y 검사를 test: 'error'로 승격해 CI 실패 조건으로 전환. 단, color-contrast 규칙만 제외했습니다 — 디자인 토큰의 명도 대비는 컴포넌트 구현이 아니라 토큰 설계 차원의 별도 사안이라, 이걸 섞으면 게이트 자체가 무력화되기 때문입니다. "통과할 수 없는 게이트는 곧 꺼지는 게이트"라는 판단이었습니다

결과 — 규칙과 게이트가 실제로 잡아낸 결함

• LDAutoComplete — ArrowUp/Down·Tab 키보드 이동 로직을 전부 구현해두고도 role="combobox"·aria-expanded·aria-controls·aria-activedescendant·role="listbox"가 하나도 없어 스크린리더가 아무것도 읽지 못하던 상태를 발견. useId 기반 id 규칙을 Context로 공유해 입력창과 항목이 같은 참조를 쓰도록 하고 combobox ARIA 일체를 구현
• LDDrawer — Base가 라이브러리의 Drawer.Title이 아닌 plain <h2>를 써서 aria-labelledby가 걸리지 않아 접근 가능한 이름이 없던 문제 해결
• LDDatePicker / LDDateRangePicker — 트리거 button 안에 초기화·캘린더 button을 중첩시키던 구조(HTML 스펙 위반)를 div 컨테이너 + 형제 배치로 재구성하고, 포커스 스타일을 focus: → focus-within:으로 이관해 시각 동작을 보존
• LDAccordion — content가 없으면 aria-controls가 가리키는 대상이 사라지던 문제 해결(Content는 항상 렌더하고 chevron만 조건부로 숨김)

3-3. 스타일 프리셋 엔진 tv() 자체 구현

배경 및 문제

컴포넌트마다 클래스 조합 방식이 달랐습니다. clsx computed key 객체, 3중 중첩 Record(triggerPadding[variant][placement][size] = 27칸), 인라인 삼항이 혼재해 읽는 사람이 매번 다른 규칙을 익혀야 했고, 어떤 조합에 어떤 클래스가 붙는지 한눈에 보이지 않았습니다.

결정과 근거

cva·tailwind-variants가 같은 문제를 풀지만, NPM 배포 패키지 특성상 소비처 번들에 의존성이 얹히는 것을 피하려고 자체 구현했습니다. base(항상) / variants(축 하나로 결정) / compoundVariants(축 조합에서만 결정) 3위계로 스타일을 성격에 따라 배치하고, 병합은 기존 cn()(clsx + tailwind-merge)에 위임해 중복 구현을 피했습니다.

성능 설계

• 축 조합별 결과를 캐싱하되, 소비측 className은 캐시 키에서 제외하고 core만 캐시한 뒤 그 위에 얹음 — 이미 중복 제거된 짧은 문자열에 병합하는 편이 원본 조각 전부를 재파싱하는 것보다 싸기 때문
• eviction은 진짜 LRU 대신 2세대 방식(상한 256, primary가 차면 통째로 secondary로 강등) — 연결 리스트 관리 없이 O(1), 메모리는 2×상한으로 고정

결과

• 속도 차의 원인까지 규명 — tailwind-variants는 extend 상속 때문에 런타임에 규칙이 달라질 수 있어 캐시 키에 compound 규칙 전체의 서명을 넣느라 매 호출 규칙을 순회합니다. 자체 구현은 extend가 없어 설정이 정의 시점에 고정이므로 그 비용을 내지 않습니다
• 트레이드오프를 문서에 명시 — "기능(extend/slots)을 덜 지원해서 얻은 속도"
• 도입 후 컴포넌트 스타일을 시각 결과 변경 없는 순수 리팩터링으로 전환 중이며, 신규·기존 컴포넌트가 규칙에서 벗어나면 리뷰에서 잡아 계속 수렴시키고 있습니다. 중첩 Record 9칸이 한 행으로 접히면서 "card와 button의 여백이 같다"는 사실이 코드에서 드러나는 부수 효과도 얻었습니다

3-4. 타입 설계로 "조용한 실패"를 컴파일 에러로 전환

배경 및 문제

공통 토큰 타입에서 일부만 골라 쓰는 컴포넌트가 많았습니다. 흔히 쓰는 Extract<Size, 'small' | 'huge'>는 오타나 삭제된 값을 에러 없이 조용히 제거합니다. 더 심각한 것은, 각 컴포넌트가 'solid' | 'outline' | … 유니온을 손으로 다시 선언하고 있어 공통 타입과 어긋나도 컴파일 단계에서 전혀 잡히지 않았다는 점입니다.

결정과 근거

• Subset<Parent, T extends Parent> = T — 한 줄이지만 의미가 반대입니다. 부모에 없는 값을 적으면 그 자리에서 컴파일이 멈추고, 공통 타입에서 값이 빠지면 그걸 쓰던 컴포넌트가 전부 에러로 드러나 어디를 고쳐야 하는지 타입 체커가 알려줍니다
• 컴포넌트별 유니온을 공통 타입 파생으로 일괄 전환 — 손으로 선언하던 variant·color·size 리터럴을 전부 Subset<Variant, …> 형태로 변경. 이 과정에서 LDDatePicker 계열이 쓰던 filled가 공통 Variant에 아예 없었다는 사실이 드러났고, 공통 타입에 추가해 해소했습니다. 타입 설계가 실제 불일치를 찾아낸 사례
• tv() 축 명세 제네릭 — 기존에는 variants에 적은 게 곧 타입이라 축 누락·오타가 새 옵션으로 흡수되고, 에러는 한참 뒤 호출부에서야 났습니다. 축 구성을 타입 인자로 못박아 정의하는 자리에서 검증되게 했습니다
• Polymorphic as prop 타입 — 렌더 엘리먼트를 교체해도 해당 엘리먼트의 DOM 속성 타입이 보존되도록 정의
• 판단 기준까지 문서화 — "공통 타입에 있으면 Subset, 없으면 리터럴 유니온, 여러 컴포넌트가 같은 값을 반복하면 그때 공통 타입으로 승격"

3-5. 공개 API 경계 설계 — 외부 라이브러리를 패키지 안에 가두기

배경 및 문제

테이블 컴포넌트는 TanStack Table 위에 올라가 있는데, 내부 래퍼(TableField)가 패키지 루트로 공개되어 있었고 table 인스턴스가 render props로 소비처에 그대로 노출되어 있었습니다. 이 상태에서는 소비처 코드가 TanStack의 타입과 API에 직접 결합되어, 라이브러리를 교체하거나 버전을 올릴 때 소비처가 전부 깨집니다. 디자인 시스템이 라이브러리를 감싸는 의미가 사라진 상태였습니다. 같은 문제가 LDDataCalendarBase, LDLNBBase 등 내부 Base 레이어의 루트 공개에도 있었습니다.

결정과 근거

• 내부 구현과 소비 API의 경계를 명시적으로 그었습니다. TableField → HeadlessTable로 개명하고 barrel에서 제외해 비공개 전환, LDDataCalendarBase·LDLNBBase도 동일하게 비공개화. Base 레이어는 패키지 내부의 구현 단위이지 소비 단위가 아니라는 것을 이름과 export 양쪽에서 일관되게 표현
• table 인스턴스를 render props에서 제거해 TanStack 의존을 HeadlessTable 내부에 가뒀습니다. 소비처는 라이브러리를 몰라도 테이블을 쓸 수 있습니다
• prop 이름을 라이브러리 도메인 어휘로 통일 — 자체 발명한 pageable 대신 TanStack의 rowCount를 채택. 자체 어휘는 배우는 비용이 들고 라이브러리 문서와 대조도 안 되는데, 그 비용을 낼 만한 추상화 이득이 없다고 판단
• 죽은 API 정리 — 실제로 아무 동작도 하지 않던 prop, 렌더에 연결되지 않은 값, 유연성만 늘리고 쓰이지 않던 옵션(stickyHeader → classNames.scroll로 일반화) 제거

3-6. 렌더 성능 진단 및 최적화

"선택 색이 부드럽게 전환되지 않고 즉시 튄다"는 시각적 증상에서 출발했지만, 원인은 전부 렌더 구조에 있었습니다.

3-7. NPM(ESM) 배포 파이프라인 및 의존성 구조 설계

배경 및 문제

다른 프로젝트에서 barrel import로 쓰려면 배포가 필요했으나, 빌드 실패·CJS 출력·타입 미노출·barrel 부재로 배포 불가 상태였습니다.

결정과 실행

• ESM 전용 패키지로 확정. tsc가 컴포넌트별 .js + .d.ts를 미러링하고, tsc-alias가 @/* alias를 해소하며 상대 import에 .js 확장자를 부여해 유효한 ESM을 만들도록 구성
• 의존성 재구성 — 기능별 라이브러리(tiptap·embla·vaul·Radix·TanStack Table·react-day-picker 등) 26개를 optional peerDependencies로 이동, 핵심 4개만 dependencies로 남겨 30 → 4개로 축소. 근거는 명확합니다 — 에디터를 쓰지 않는 소비처가 tiptap 전체를 설치할 이유가 없습니다
• Tailwind조차 peer로 요구하지 않도록 설계 — 완성 CSS(styles.css)만 쓰는 소비처는 Tailwind 설치 자체가 불필요하고, 소비처의 Tailwind가 실제로 필요한 지점은 토큰 원본(theme.css) 경로뿐입니다. 이 경계를 문서에 명시
• sideEffects를 CSS로만 한정해 트리셰이킹을 확보하고, 진입점 3종(barrel / 컴포넌트 개별 경로 / 스타일)을 exports로 노출
• 소비처 런타임 버전에 맞춰 빌드·Storybook devDependencies를 핀해 검증 환경과 실행 환경의 괴리를 제거(peer 범위는 호환성을 위해 넓게 유지)

결과 — 0.0.1 최초 발행 이후 릴리즈 18회, 사내 서비스 2곳에서 사용 중.

3-8. 릴리즈 파이프라인 설계 및 배포 자동화

기간2026.08 (설계 → 구현 → 실전 검증 → 결함 수정까지 한 사이클) 역할단독 설계·구현·운영 산출물워크플로 5종 1,008줄 · 자체 changeset 도구 402줄 · 팀 실무 문서 266줄

문제 정의 — "배포 단위"라는 개념이 없었다

디자인 시스템은 여러 명이 동시에 작업하는데, 각자 작업 브랜치를 main으로 직접 머지하고 어느 정도 모이면 npm 버전을 올려 배포하는 구조였습니다. 배포라는 단위가 코드상 아무 실체도 갖지 못한다는 것이 근본 문제였습니다.

핵심 설계 — 배포 1건 = PR 1건

main을 "항상 npm에 배포된 것과 동일한 상태"로 고정하고, 그 사이에 이번 배포의 집결지인 release/vX.Y.Z 브랜치를 두었습니다. 팀원은 main이 아니라 이 브랜치에서 분기하고 이 브랜치로 PR합니다.

이 구조의 핵심은 브랜치가 아니라 release/* → main draft PR 하나입니다. 이 PR이 곧 "이번 배포 대시보드"가 됩니다 — 누적 diff, 포함된 작업 목록, 여러 사람의 변경이 합쳐진 상태의 통합 CI, 소비처가 읽을 릴리즈 노트가 한 화면에 모입니다. "이번 배포에 뭐가 들어가나?"에 대한 답이 URL 하나가 되는 것이 이 설계의 목적이었습니다.

함께 정한 제약 — 열려 있는 release 브랜치는 항상 하나로 강제했습니다(둘 이상이면 워크플로가 중단). 둘 이상이면 팀원이 어디로 PR해야 할지 알 수 없어 모델 자체가 무너집니다.

changeset — 단일 출처, 두 독자의 분리

배포 단위를 만들어도 "무엇이 바뀌었는지"를 사람이 매번 정리하면 자동화가 아닙니다. 그리고 기존 CHANGELOG는 독자가 섞여 있었습니다 — 팀은 "왜 이렇게 고쳤는지"를, 소비처는 "무엇이 달라졌고 내 코드를 어떻게 고쳐야 하는지"를 알아야 하는데 한 파일에 뒤섞여 있었습니다.

작업 하나당 .changes/{브랜치명}.md 파일 하나를 남기게 하고, 이 파일을 변경 기록의 유일한 원본으로 정했습니다. 한 파일 안에 ## 팀 기록과 ## 소비처 두 섹션을 두어, 배포 시 각각 CHANGELOG와 릴리즈 노트로 자동 분배됩니다.

• 충돌이 구조적으로 사라짐 — 각자 서로 다른 새 파일을 만드니 겹치는 줄이 없습니다. 가장 자주 겪던 실무 통증이 부수적으로 해결된 케이스
• 같은 내용을 두 번 쓰지 않음 — 작업자는 한 파일만 씁니다
• 생성물을 사람이 못 건드리게 함 — CHANGELOG와 릴리즈 노트는 생성물이므로 직접 편집을 CI가 차단. 규칙을 문서로만 두면 지켜지지 않기 때문

버전 결정 — 판단 기준을 질문 하나로 압축

"이번엔 patch인가 minor인가"를 매번 사람이 상의하면 자동화가 아니고, 기준이 사람마다 다르면 소비처가 예고 없이 깨집니다. 그래서 기준을 하나의 질문으로 고정했습니다 — "이 버전을 올리면, 소비처가 코드를 한 줄이라도 고쳐야 하는가?" "눈에 띄게 바뀌었나"가 아니라는 점이 핵심입니다.

• 판단이 흔들리는 지점을 문서에 미리 못박았습니다 — 타입만 바뀌어도 TS 소비처에는 컴파일 에러이므로 breaking / 내부용이어도 export돼 있었으면 공개 API / 시각적으로 크게 바뀌어도 코드 수정이 없으면 patch(단 ## 소비처에는 분명히 적음) / 애매하면 높은 쪽으로(낮게 잡으면 소비처가 깨지고 높게 잡으면 숫자만 올라가는 비대칭 비용)
• 버전은 bump의 합산이 아니라 최댓값으로 결정 — minor 5개 + patch 3개여도 한 번만 올라갑니다. 기준을 항상 main 버전에 두어(release 브랜치 현재 버전을 기준으로 삼으면 실행마다 계속 올라감) 몇 번 재계산해도 결과가 같은 멱등 구조로 만들었습니다

기성 도구(@changesets/cli)를 쓰지 않은 이유

• 모델 충돌 — 그 도구는 버전 결정과 배포까지 자기가 소유하려 합니다. 릴리즈 브랜치 모델과 소유권이 겹쳐, 도구에 맞추려면 제가 풀려던 문제(배포 단위 = PR)를 포기해야 했습니다
• 필요한 것이 둘뿐 — 실제로 필요한 기능은 "PR당 파일 하나 + bump 등급"이었고, 쓰지 않는 기능도 학습 비용과 제약은 그대로 냅니다
• 파일 컨벤션 + 자체 스크립트(402줄)로 대체. 의존성 없이 Node 표준 모듈만 써서 CI에서 설치 없이 실행됩니다(검사 job이 install을 건너뛸 수 있어 PR 피드백이 빨라짐). frontmatter 파싱은 배포 버전을 결정하는 로직이므로 구현이 하나여야 한다고 보고, PR 검사와 버전 재계산이 같은 스크립트를 호출하게 했습니다 — 검사에서 통과한 것이 배포에서 다르게 해석되지 않도록

안전성 — 되돌릴 수 없는 지점을 기준으로 순서를 정함

npm publish는 되돌릴 수 없는 유일한 지점입니다. 이 지점을 축으로 파이프라인 순서를 배치했습니다.

검증 (노트 존재 · npm 중복 · 인증 · 타입 체크 · 테스트)
  → npm publish              ← 되돌릴 수 없는 지점
  → 태그 → CHANGELOG 갱신 + .changes/ 비움 → Release 게시 → 다음 사이클 자동 오픈

• publish 전에 실패하면 태그도 CHANGELOG도 .changes/도 손대지 않은 상태로 남습니다. 실제로 v0.1.0 첫 배포가 npm 인증 실패로 중단됐을 때 main이 온전히 남아 토큰만 고쳐 재시도할 수 있었습니다 — 설계 의도가 실전에서 검증된 지점입니다
• 멱등 설계 — 릴리즈 노트는 머지될 때마다 통째로 다시 생성합니다. 누적 방식은 실행 횟수에 결과가 의존해 실패 복구가 어렵습니다. 이미 배포된 버전이면 워크플로가 스스로 중단하고, 머지 이후 실패에 대비해 검증은 동일하게 거치는 수동 재시도 경로를 두었습니다

AI를 파이프라인 단계로 편입 — 권한을 나눠서 안전하게

릴리즈 노트의 사실관계(변경 항목·PR 목록)는 changeset에서 기계적으로 생성되지만, 소비처가 읽을 요약 문단은 문장 작업입니다. 이 부분만 Claude Code Action에 맡겼습니다.

• 커밋 권한을 주지 않음 — 파일만 고치게 하고 커밋은 워크플로가 합니다. 그 사이에 "릴리즈 노트 외 파일이 바뀌었는지" 검사를 끼워 넣기 위해서입니다. 노트 외의 것을 건드렸다면 푸시하지 않고 diff를 출력한 채 실패하며, 허용 도구도 읽기·편집 계열로 제한했습니다
• AI가 잘하는 일과 틀리면 안 되는 일을 프롬프트에서 분리 — 마이그레이션 코드 예시는 문구만 다듬고 코드는 바꾸지 말 것, 자료에 없는 사실을 지어내지 말 것을 명시했습니다
• 배포 워크플로에 합치지 않음 — publish는 머지 이후에 돌기 때문에, 거기서 요약을 쓰면 아무도 검수하지 않은 글이 npm과 GitHub Release로 나갑니다. 특히 마이그레이션 안내가 틀리면 소비처에 실제 피해가 생기므로, 생성 시점을 draft 해제로 앞당기고 검수는 머지 전에 남겼습니다

CI를 "막는 도구"가 아니라 "가르치는 도구"로

새 프로세스를 도입하면 팀원은 반드시 실수합니다. 특히 GitHub이 PR base를 항상 main으로 기본 설정하기 때문에 매번 바꿔야 하는데 이것이 가장 흔한 실수였습니다. 이때 CI가 빨간 X만 띄우면 팀원은 로그를 뒤지고 결국 저에게 물어보게 됩니다 — 자동화가 오히려 리드를 병목으로 만드는 구조입니다.

그래서 검사가 실패하면 Step Summary에 해결 방법을 렌더링하도록 했습니다. 브랜치 규칙 실패에는 현재 base/head와 바꾸는 방법, 이미 main에서 분기했을 때의 rebase 명령까지. changeset 누락에는 그 PR이 만들어야 할 정확한 파일 경로(브랜치명에서 자동 생성)와 템플릿 전문을. annotation은 첫 줄만 PR 화면에 노출되므로 로그를 펼치지 않아도 보이도록 Summary에 함께 남겼습니다.

제약 조건 — 강제할 수 있는 것과 없는 것의 구분

저장소가 free 플랜 private이라 GitHub이 브랜치 보호 규칙을 제공하지 않습니다. 즉 CI가 실패해도 머지를 막을 수 없습니다.

• 설정으로 강제할 수 있는 것은 설정으로 — 머지 방식(merge commit 전용)은 squash·rebase를 비활성화해 버튼 자체가 안 보이게 잠갔습니다
• 나머지는 CI로 드러내되 한계를 팀에 명시했습니다. "CI가 막아준다"고 잘못 믿게 두는 것이 더 위험하다고 판단해, 문서에 "빨간 체크를 띄울 뿐 머지를 막지 못한다"는 사실과 해제 조건(public 전환 또는 유료 플랜 전환 비용)까지 적어 비용과 함께 의사결정할 수 있게 남겼습니다

실전 검증

v0.1.0 · v0.1.1 두 번의 실 배포로 워크플로 5종이 모두 동작하는 것을 확인하고, 첫 사이클에서 드러난 결함 7건을 원인 단위로 규명·수정했습니다. 로컬과 CI 환경 차이(뷰포트 미고정으로 인한 플레이키 테스트), GitHub Actions 동작 방식(라벨 트리거 누락, Actions의 PR 생성 차단 정책), npm의 응답 특성(scoped 패키지 권한이 없으면 401이 아니라 404) 등 실제로 돌려보지 않으면 알 수 없는 것들이었습니다.

이 CI/CD 작업 자체도 만든 프로세스를 따라 changeset을 남기고 release 브랜치를 통해 머지했습니다. 자기가 만든 프로세스를 자기가 먼저 쓰면서 불편한 지점을 찾는 방식으로 검증했습니다.

성과

3-9. 디자인 토큰 체계, CSS 배포 구조, 확장점 설계

(1) 컴파일 산출물의 한계를 발견하고 이중 진입점 도입

문제 — 소비처가 배포된 styles.css(= 컴파일된 CSS)만 import하면, 그것은 디자인 시스템이 사용한 클래스만 담긴 스냅샷이라 소비처가 쓰는 클래스는 생성되지 않았습니다. 더 근본적으로, 컴파일본에서 Tailwind v4의 @theme는 :root 변수로 박제되어 소비처 Tailwind가 이를 토큰으로 인식조차 못 하는 상태였습니다.

결정 — 토큰·유틸 레이어만 모은 raw 소스 진입점(theme.css)을 별도 export. 여기에 @import 'tailwindcss'와 컴포넌트 스타일은 의도적으로 넣지 않았습니다 — 소비처가 이미 import하므로 중복 시 충돌하고, 컴포넌트 스타일은 컴파일본이 담당하기 때문입니다. 결과로 소비처가 자기 Tailwind 파이프라인에서 토큰 기반 클래스를 별도 정의 없이 on-demand 생성할 수 있게 되었습니다.

(2) 소비처에서만 재현되던 캐스케이드 버그 규명 및 진단 절차 문서화

• 증상 — 소비처에서 className이 DOM에는 붙는데 스타일이 적용되지 않음
• 원인 — 프리셋이 @utility(= utilities 레이어)로 정의되어 소비자의 임의값 유틸과 동일 레이어·동일 specificity였고, 미리 컴파일된 CSS를 앱 CSS보다 나중에 import하면 소스 순서로 디자인 시스템이 이겼습니다. Storybook은 단일 빌드라 우연히 정상 동작하고 있었던 것이 발견을 늦춘 원인입니다
• 결정 — 여러 속성을 묶은 "레시피" 클래스는 @layer components로 이전(components < utilities이므로 소비자 유틸이 로드 순서와 무관하게 항상 우선), 단일 목적 유틸과 @theme 변수는 @utility 유지. 전환 전 variant 미사용을 확인해 손실이 없음을 검증
• 문서화 — docs/css-layers.md에 레이어 서열 규칙, 컴포넌트 프리셋을 @layer components에 두는 이유, 소비처 override 판정 3단계(① cn()의 tailwind-merge dedupe → ② CSS 레이어 싸움 → ③ style prop 우회), 5단계 진단 흐름을 정리. 같은 증상을 매번 처음부터 추적하던 비용을 없애는 것이 목적이었습니다

(3) 확장점의 모양을 사용 패턴에서 도출 — colorSet

문제 — 캘린더의 선택·hover·today 링·예약 점 색이 Base에 직접 박혀 있어, 소비처가 브랜드 색을 바꿔도 선택 표시는 파란색으로 고정됐습니다. 색이 붙는 버튼이 classNames 슬롯으로 노출되지도 않아 덮어쓸 경로 자체가 없었고, "Base에는 시각 스타일을 두지 않는다"는 규칙에도 어긋났습니다.

핵심 판단 — "프리셋이 정말 필요해지면 colorSet에 값을 넣는 얇은 레이어로 얹을 수 있고, 그때도 Base는 다시 손대지 않아도 된다"는 점을 근거로 채택했습니다. 3-Layer 설계의 "위에 얹어서 확장한다"는 원칙을 확장점 설계에도 그대로 적용한 사례입니다.

부수 성과 — 이 작업 중 선택 시 색이 차오르던 애니메이션이 색을 직접 물고 있어 다른 색을 지정하면 파란색이 번졌다 튀는 문제, from/to가 서로 다른 CSS 속성을 애니메이션하던 결함을 발견해 함께 제거했습니다. 캘린더를 쓰는 모든 지점(단독·DatePicker·DateRangePicker·각 Form 래퍼)에 스토리를 붙여 확장점이 실제로 닿는지 검증했습니다.

3-10. 팀 개발 규칙 수립 및 리딩

배경 및 문제

6명이 병렬로 작업하는 상황에서 컨벤션이 문서화되지 않으면, tv() 도입 이전에 겪었던 문제가 조직 차원에서 반복됩니다 — 읽는 사람이 컴포넌트마다 다른 규칙을 새로 익혀야 하는 상태.

실행

• 문서 체계 집필 — architecture.md(3-Layer + 신규 컴포넌트 추가 가이드), style-conventions.md(tv() 작성 규칙 및 제한사항), css-layers.md(캐스케이드·override 진단), type-conventions.md
• 문서의 지속가능성 자체를 문제로 다룸 — 문서가 중복되고 과도하게 상세해 최신 상태 유지가 어려워지자, 정본 문서를 기본 원칙과 예시 중심으로 재작성(architecture 373줄 → 145줄)하고 중복은 참조로 대체했으며, 현행 구조와 맞지 않게 된 과거 문서는 삭제하지 않고 docs/deprecated/로 보관해 "기준으로 삼지 않되 맥락은 남긴다"는 처리를 했습니다
• AI 코딩 도구를 팀 개발 환경에 통합 — 에이전트 규칙 파일이 문서를 목록으로만 링크해 작업 종류와 무관하게 전부 훑어야 컨텍스트가 잡히는 구조였습니다. 정본 문서를 가리키는 얇은 포인터 스킬 3종(아키텍처/스타일/타입)을 만들고 규칙 파일을 "작업 → 스킬" 라우팅 표로 대체했습니다. 설정 폴더를 git 추적으로 전환해 팀 전원이 같은 AI 컨텍스트를 공유하도록 했고, 사람용 문서와 도구용 문서를 이중 관리하지 않고 하나의 정본을 양쪽이 참조하게 만든 것이 설계 포인트입니다
• 변경 이력을 "원인/이유 + 수정" 형식으로 강제 — 누적 1,347줄. 작성자가 아닌 팀원이 히스토리만으로 맥락을 파악할 수 있게 하는 것이 목적이며, 코드 변경과 같은 커밋에 포함하도록 규칙화
• 코드 스타일을 도구로 강제 — import 순서·Tailwind 클래스 순서에 규칙이 없어 파일마다 제각각이었고 상대경로와 절대경로가 섞여 있었습니다. Prettier 설정을 분리해 플러그인을 붙일 수 있게 만들고, 클래스 정렬·import 정렬·Tailwind 린트 플러그인을 도입. 커스텀 유틸리티 클래스와 cn()/tv() 내부 문자열까지 린트 대상에 포함되도록 설정해 검사에서 새는 구멍을 막았습니다
• 품질 게이트 — pre-commit(스테이징 파일 포맷+린트), pre-push(전체 타입 체크), lint --max-warnings 0, a11y CI 실패 조건. GUI Git 클라이언트가 로그인 셸을 거치지 않아 PATH에 pnpm이 없는 문제까지 훅에서 처리하고, ANSI 색상을 렌더링하지 않는 출력 패널을 고려해 구분선·기호·소요시간으로 읽히는 로그를 설계
• 테스트 전략 — 새 테스트를 따로 작성하는 대신 이미 존재하는 65개 스토리를 그대로 테스트로 실행(Storybook Vitest 애드온 + Playwright Chromium 브라우저 모드 + a11y 검사). 유틸은 별도 유닛 테스트로 커버하고, 커버리지를 유틸/컴포넌트로 분리 측정해 성격이 다른 두 코드의 목표치를 따로 관리(컴포넌트 목표 85%). 투자 대비 커버리지가 가장 큰 지점을 고른 결정입니다
• 코드리뷰·릴리즈 총괄 — PR 48건 리뷰·머지, 릴리즈 18회 직접 배포, 커밋 컨벤션 표준화

3-11. 레거시 마이그레이션 전략 — "무엇을 넣지 않을지"의 기준

레거시 UI 패키지 2곳의 컴포넌트를 전수 조사해 완료 / 기존 컴포넌트의 변형으로 커버 가능 / 추가 검토 / 대상 아님 4분류로 정리하고, 제외 사유를 항목별로 명시했습니다 — 단순 래핑(Next.js Link, 외부 캐러셀), 단일 요소로 너무 단순한 것, 서비스 특화 컴포넌트, 3-Layer 적용 대상이 아닌 애니메이션 유틸.

디자인 시스템의 정체성은 무엇을 담느냐보다 무엇을 담지 않느냐로 정의된다고 보고, 판단 근거를 남겨 이후 팀원이 같은 기준으로 결정하도록 했습니다. 도입 우선순위는 추측이 아니라 실사용 빈도로 정했습니다(예: 소비처에서 외부 라이브러리 컴포넌트를 22회 사용하는 것을 확인한 뒤 대체 컴포넌트 추가).

같은 기준을 브릿지 모노레포의 공용 패키지에도 적용하고 있습니다. 브릿지의 @loword/ui·@loword/nextjs-ui는 디자인 시스템이 없던 시기에 5개 앱의 중복을 흡수하기 위해 만든 임시 수렴점이므로(2-2), 디자인 시스템이 커버하는 컴포넌트는 치환하고 서비스 특화 컴포넌트만 모노레포 패키지에 남기는 것이 목표입니다. 두 벌을 영구히 유지하면 "어느 쪽이 기준인가"가 흐려져, 디자인 시스템을 만든 이유 자체가 사라집니다.

4. 레듀 — 멀티테넌트 LMS / 강의 판매 플랫폼

프로젝트 배경

초기에는 단일 강의 판매 사이트였으나, 동일한 구조의 몰을 여러 고객사에 제공하는 B2B2C 모델로 확장하는 것이 사업 방향이었습니다. 이 전환에서 프론트엔드의 핵심 과제는 두 가지였습니다.

• 몰이 늘어도 유지보수 비용이 선형으로 늘지 않는 구조 — 코드를 복제하면 공통 버그 수정이 N배가 됩니다
• 몰 운영자가 개발자 없이 사이트를 운영할 수 있는 도구 — 이게 없으면 몰 수가 곧 개발팀의 부하가 됩니다

이 두 가지가 이후 2년 7개월의 모든 기술 의사결정의 기준이 되었습니다.

4-1. 멀티테넌트 아키텍처 설계 및 구축

기간2024.01 ~ 2024.06 (초기 설계) / 이후 지속 개선 역할아키텍처 설계 및 구현 단독 담당 기술Next.js App Router, Route Handler, axios Interceptor, Docker

배경 및 문제

몰마다 코드베이스를 복제하는 방식은 초기에는 빠르지만, 공통 기능 수정이 몰 수만큼 반복되고 몰별로 코드가 갈라지면서 어느 몰에 어떤 수정이 들어갔는지 추적 불가능한 상태로 수렴합니다. 동시에 각 몰은 SEO와 브랜딩상 독립 도메인을 써야 했고, 디자인·메뉴 구성도 전부 달랐습니다.

① 테넌트 식별 방식 — 서브패스/빌드분기가 아닌 HTTP 헤더(X-MALL-ID)

② 클라이언트 MALL_ID를 빌드타임이 아닌 런타임에 주입

NEXT_PUBLIC_* 환경변수는 빌드 시점에 번들에 인라인됩니다. 그대로 쓰면 몰마다 별도 빌드가 필요해져 ①의 이점이 사라집니다. → /api/config Route Handler로 런타임에 내려주고, axios 인터셉터가 모듈 스코프에 캐싱하도록 구현했습니다.

• 동시 호출은 단일 Promise를 공유해 중복 네트워크 요청 방지
• 실패 시 빈 문자열로 폴백해 앱이 죽지 않도록 방어
• 서버 코드(RSC / Server Action / Route Handler)는 process.env를 직접 읽어 오버헤드 없음

③ 사이트 외형을 코드가 아닌 데이터로

로고·컬러셋·헤더/푸터 메뉴·약관·SEO 설정·외부 서비스·하단 모바일 메뉴를 백엔드에서 내려받아 루트 레이아웃이 조립하도록 설계했습니다. Ant Design ConfigProvider의 colorPrimary·colorLink까지 몰 설정값을 주입해 디자인 토큰 수준에서 테넌트별 브랜딩이 적용됩니다. 루트 레이아웃의 6개 설정 fetch는 Promise.all로 병렬화해 TTFB 영향을 최소화했습니다.

④ 마스터 몰(MASTER_MALL) 개념 도입

몰을 관리하는 몰(거래처 관리)이 필요해, 메뉴 정의에 forMaster 플래그를 두어 동일한 어드민 코드에서 권한 계층을 분리했습니다. 별도 앱을 만들지 않은 이유는, 관리 화면의 90%가 동일해 두 벌 유지 비용이 이득을 넘기 때문입니다.

성과

• 단일 Docker 이미지로 전 몰 배포. 신규 몰 온보딩이 환경변수 2개(NEXT_PUBLIC_MALL_ID, HOST) 주입으로 축소
• 공통 기능 수정이 한 번의 배포로 전 몰에 반영
• 몰별 커스터마이징이 코드가 아닌 어드민 데이터에 있어, 디자인·메뉴 변경에 개발자 개입 불필요

4-2. 관리자 콘솔 설계 및 구현 (9개 도메인 48개 화면)

기간2024.02 ~ 지속 역할전체 정보구조 설계 및 구현 주도 (팀원과 분담) 기술Next.js App Router, Ant Design Pro Components, Recoil, Server Actions

배경 및 문제

몰 운영자가 배너 하나, 쿠폰 하나를 바꾸려고 개발팀에 요청하면 개발팀이 사업 확장의 병목이 됩니다. 몰이 늘어날수록 이 비용은 선형 이상으로 증가합니다.

① 범위 설정 — "개발 요청이 들어오는 항목"에서 역산

기능을 상상해서 만들지 않고, 실제로 들어온 개발 요청을 분류해 그것을 전부 어드민으로 흡수하는 방향으로 범위를 잡았습니다.

② 라우팅 — 파일 라우트가 아닌 "단일 동적 라우트 + 컴포넌트 맵"

48개 화면을 파일 라우트로 쪼개면 세그먼트마다 레이아웃·권한 가드·브레드크럼·사이드메뉴가 중복됩니다. app/admin/[pages]/[detail] 한 파일이 {'경로/상세': <Component/>} 맵으로 분기하도록 설계해, 셸을 한 곳에 두고 화면 추가를 등록 3줄로 줄였습니다.

트레이드오프를 명확히 인지하고 대응했습니다 — 라우트 단위 코드 스플리팅이 자연스럽게 되지 않고, 미등록 경로가 조용히 대시보드로 폴백됩니다. 이를 숨기지 않고 "어드민 화면 추가 시 반드시 함께 고쳐야 할 3곳"을 온보딩 문서에 명문화해 팀 실수를 방지했습니다.

③ 어드민 저장 → 사용자 사이트 즉시 반영

사용자 페이지는 SEO 때문에 서버 컴포넌트 + Next 캐시 태그(next: { tags, revalidate })로 캐싱합니다. 그대로 두면 어드민에서 저장해도 사용자 화면에 반영이 지연됩니다. → 각 서버 액션 파일에 revalidateTag 무효화 함수를 짝으로 정의해, 어드민 저장 시점에 해당 태그만 정확히 무효화하도록 설계했습니다. 캐시 성능과 운영 즉시성의 충돌을 태그 단위 무효화로 해소한 사례입니다.

④ 데이터 페칭 경로의 경계를 명시적으로 고정

섞어 쓰면 인증과 캐시가 어긋납니다. 이 경계를 문서로 고정하고, 특히 notLoginedApi라는 이름과 달리 토큰이 있으면 자동으로 실어 보낸다는 함정을 명시했습니다.

성과

• 몰 운영자가 디자인·메뉴·랜딩·쿠폰·알림톡·SEO·마케팅 스크립트를 전부 자체 운영
• 운영 요청이 개발팀을 거치지 않고 처리되어, 몰 증가가 곧 개발팀 부하가 되던 구조를 해소
• 신규 몰 온보딩 시 개발 리소스 투입 없이 운영팀이 구축 가능

4-3. 페이지 빌더 1차 — 블록 조립형 Studio

기간2024.05 ~ 2024.11 (더블티 재직 시) 역할설계 및 구현 주도 규모130파일 / 약 19,000 LOC 기술React, react-sortablejs, dynamic import, Ant Design

배경 및 문제

강의 판매몰의 매출은 랜딩페이지 실험 속도에 직결됩니다. 그런데 랜딩 한 장마다 개발자가 붙으면 실험 사이클이 주 단위가 되고, 마케팅팀이 아이디어를 검증할 수 없습니다.

① "범용 빌더"를 만들지 않기로 한 결정

처음부터 무한 자유도의 빌더를 만드는 선택지도 있었지만, 두 가지 이유로 배제했습니다.

• 도입 저항 — 자유도가 높을수록 비개발 직군의 학습 비용이 커져, 만들어도 아무도 안 씁니다
• 디자인 붕괴 — 자유 배치를 허용하면 만들어진 페이지가 브랜드 기준을 벗어납니다

대신 운영 중인 실제 랜딩페이지를 역분석해 반복되는 블록(메인 슬라이드, 그리드 배너, 타이틀, 2/3단 그리드, 강의 카드, 후기 슬라이드, 앵커, 타이머 배너, DB 수집 폼 등)을 추출하고, 블록마다 시각 컴포넌트 + 입력폼 쌍을 두었습니다.

② 성공 기준을 "마케터가 30분 안에 랜딩 하나 완성"으로 정의

자유도를 제한하는 대신 이 기준을 즉시 만족시키는 것을 목표로 했습니다. 실사용 데이터가 쌓여야 2차의 요구사항이 검증된다고 판단했고, 실제로 1년간의 사용 패턴이 2차 설계의 근거가 되었습니다.

③ 계측을 나중에 붙이지 않고 블록에 내장

타이머 배너·무료강의 신청·DB 수집 폼 블록이 직접 purchase / purchase_livefree dataLayer 이벤트를 push하도록 구현했습니다. → 마케터가 만든 페이지가 자동으로 계측되는 상태가 됩니다. 계측을 나중에 붙이면 반드시 누락되고, 누락된 기간의 데이터는 복구되지 않습니다.

④ 성능

블록별 dynamic import로 에디터 초기 번들을 분리해, 블록 수가 늘어도 초기 로딩이 비례해 무거워지지 않도록 했습니다.

성과

• 랜딩 제작이 비개발 직군으로 완전 이관, 실험 사이클 주 단위 → 시간 단위
• 계측 내장으로 전환 데이터 누락 없는 랜딩 확보
• 2024.11 이후 약 1년간 실제 하위몰 운영에 사용되었고, 그 기간의 사용 패턴과 한계가 2차 빌더(위 1번 프로젝트)의 요구사항 근거로 축적

4-4. SEO 및 그로스 계측 인프라 구축

기간2024.03 ~ 지속 역할설계 및 구현 단독 담당 (마케팅팀과 요구사항 협의) 기술Next.js Metadata API, Middleware, GTM, GA4, Meta Pixel, Naver WCS

배경 및 문제

강의 판매몰은 검색 유입과 광고 전환 측정이 곧 매출입니다. 그런데 몰마다 광고 대행사·픽셀 계정·태그 구성이 전부 다릅니다. 몰이 늘 때마다 스크립트를 코드에 추가하는 방식은 지속 불가능합니다.

① SEO 메타데이터 — 계층 폴백

generateMetadata에서 강의 상세 > 랜딩페이지 > 몰 기본 SEO 설정 우선순위로 title/description/OG/Twitter/keywords/canonical을 조립했습니다. → 어드민에서 강의별로 채우지 않아도 몰 기본값으로 항상 유효한 메타가 나가고, 채우면 정밀해집니다. "안 채우면 빈 메타"가 되는 설계는 실무에서 반드시 빈 메타를 만듭니다.

• canonical은 요청 헤더의 host/proto로 동적 생성 — 몰마다 도메인이 다르므로 하드코딩 불가
• 마이페이지 등 개인 영역은 robots: noindex로 분리
• 백엔드가 생성한 sitemap을 서빙하는 Route Handler 제공

② 레거시 URL 301 마이그레이션

구 사이트에서 이전할 때 URL이 바뀌면 그동안 쌓은 검색 랭킹과 백링크 자산이 통째로 소실됩니다. 미들웨어에서 게시판/게시글/클래스/랜딩/회원가입/마이페이지 등의 구 URL을 매핑 테이블로 처리했습니다.

• 게시글은 실제 API를 호출해 제목을 slug로 변환한 뒤 리다이렉트
• 영구 이전은 301, 성격이 바뀐 경로는 302로 의도적으로 구분 (301은 브라우저가 영구 캐시하므로 잘못 쓰면 되돌릴 수 없음)
• 동시에 x-pathname / x-url / x-search 헤더를 주입 — 서버 컴포넌트가 현재 URL을 읽는 유일한 통로

③ 외부 서비스/스크립트를 어드민 등록형으로

GA4 / GTM / Meta Pixel / Naver 서치어드바이저 / Google Search Console / 카카오 플러스친구를 서비스 코드 기준으로 스위칭 렌더하고, 그 외 임의 스크립트는 "외부 코드 설정"에서 head/body 위치와 적용 경로(전체/특정 URL)를 지정해 주입하도록 설계했습니다. → 몰마다 다른 마케팅 스택을 코드 수정 없이 연동.

④ GTM 다중 컨테이너 지원

자사 컨테이너와 광고 대행사 컨테이너가 공존하는 것이 실무 상황입니다. 콤마 구분 입력을 파싱해 컨테이너별로 별도 dataLayer(dataLayer, dataLayer2…)를 분리 초기화했습니다. 하나를 공유하면 서로의 이벤트가 섞여 대행사 리포트가 오염됩니다.

⑤ Meta Pixel — Advanced Matching + SPA 대응

• 로그인 사용자는 이메일/휴대폰(정규화 후)/external_id를 실어 init → 매칭률과 전환 회수율 향상, 비로그인은 식별자 없이 init
• useRef 가드로 중복 init 방지, 로그인 상태 변화 시에만 사용자 데이터 갱신
• App Router는 페이지 전환 시 스크립트가 재실행되지 않으므로 pathname/searchParams 변화에 반응해 PageView를 수동 발화 (Naver WCS도 동일한 이유로 SPA pageview 헬퍼 별도 구현)

⑥ 커머스 퍼널 이벤트 설계

page_view → begin_checkout → purchase로 퍼널을 정의하고, 무료/쿠폰 전액할인 케이스를 별도 이벤트로 분리했습니다. 0원 전환을 같은 purchase로 보내면 ROAS가 왜곡되어 광고 알고리즘이 잘못된 방향으로 학습하기 때문입니다. 보유 강의 목록을 별도 이벤트로 push해 리타게팅 제외 세그먼트를 만들 수 있게 했습니다.

⑦ UTM 캠페인 세션 보존

카카오 로그인 같은 OAuth 리다이렉트를 거치면 UTM 파라미터가 유실되어 어트리뷰션이 끊깁니다. UTM을 sessionStorage에 보존하고 카카오 로그인 state 파라미터에 실어 왕복시켜, 회원가입/결제 전환까지 캠페인 정보가 이어지도록 했습니다(중첩 url 파라미터 안의 UTM까지 파싱).

성과

• 몰별로 다른 마케팅 스택을 코드 수정 없이 연동 가능
• 구 사이트 이전 시 검색 자산 보존
• 무료/유료 전환 분리로 ROAS 왜곡 제거, 광고 최적화 정확도 개선
• OAuth 경유 전환의 어트리뷰션 유실 해소

4-5. 프레임워크 마이그레이션 (Next 14→15 / React 18→19 / Tailwind v3→v4)

기간2025.09 ~ 2025.12 역할마이그레이션 계획 수립 및 실행 리드 규모83,000 LOC 규모 애플리케이션 전체

배경 및 의사결정

"왜 지금 하는가"가 이 작업의 핵심 근거였습니다. React 19 대응이 늦어질수록 Ant Design·자체 디자인 시스템·서드파티 생태계가 먼저 올라가버려, 이후 업그레이드 비용이 기하급수로 증가합니다. 부채가 커지기 전에 처리한다는 판단으로 일정을 확보했습니다.

주요 트러블슈팅

성과

• 83,000 LOC 규모 애플리케이션을 서비스 중단 없이 최신 스택으로 이전
• 이후 디자인 시스템·라이브러리 업그레이드 경로 확보
• 재현 난이도가 높은 이슈 6건을 근본 원인까지 규명하고 재발 방지 규칙으로 자산화

4-6. 팀 리딩 및 엔지니어링 문화

기간2024.01 ~ 지속 역할프론트엔드 팀 리더

배경

기여자가 누적 20명을 넘어가면서 "내가 아는 것"과 "팀이 아는 것"의 격차가 사고로 이어지는 국면에 들어섰습니다. 특히 이 레포에는 모르면 반드시 사고가 나는 항목들이 있었습니다(멀티테넌트 구조, 데이터 페칭 2경로 혼용, CSS import 순서, AntD Upload 자동 POST).

① "원인 기반" 변경 이력 문화 정착

모든 변경을 원인/이유 + 수정 형식으로, 코드 변경과 같은 커밋에 누적 기록하도록 규칙화했습니다(현재 970줄).

• 왜 커밋 메시지로 충분하지 않은가 — 커밋 메시지는 "무엇을"은 담지만 "왜"를 담기 어렵고, 시간이 지나면 검색 단위가 되지 못합니다
• 기준 — 작성자가 아닌 팀원이 히스토리만 보고 맥락을 파악할 수 있을 것
• 실제 효과 — 이 기록이 이후 온보딩 문서의 근거 자료가 되었고, 문제가 생겼을 때 팀의 첫 검색 대상이 되었습니다

② 함정 중심 온보딩 문서 작성 (548줄)

• 코드를 읽으면 알 수 있는 것이 아니라 "모르면 반드시 사고 나는 것" 중심으로 16개 장을 구성
• 왜 망라형이 아닌가 — 모든 것을 담은 문서는 반드시 낡고, 낡은 문서는 아무도 읽지 않습니다. 대상을 좁히면 유지 가능한 분량이 되고 실제로 읽힙니다
• 작성 과정에서 기존 기술 문서가 실제 코드와 어긋난 것(Next 14/React 18/Tailwind v3로 기술)을 발견해, 불일치 사실 자체와 갱신 필요를 문서에 명시했습니다. 틀린 문서를 조용히 두는 것보다 "여기가 틀렸다"고 적어두는 편이 안전하다고 판단했습니다

③ AI 에이전트용 컨텍스트 문서 체계

루트에 전역 요약, Studio 하위에 별도 상세 가이드를 두어 관련 없는 작업에 Studio 세부사항이 로드되지 않도록 컨텍스트를 분할했습니다. 팀의 AI 도구 활용 시 불필요한 컨텍스트가 정확도를 떨어뜨리는 문제를 구조로 해결한 사례입니다.

④ 코드 리뷰 및 컨벤션

작업 브랜치 네이밍(feat/ fix/ refactor/ chore/), 커밋 메시지 형식, Prettier/ESLint 설정 정착. ESLint의 exhaustive-deps가 비활성이라는 사실을 "도구가 잡아주지 않으니 직접 확인해야 한다"고 문서에 명시해, 설정의 한계를 팀이 인지하도록 했습니다.

성과

• 신규 합류자가 코드와 히스토리를 직접 훑지 않고도 주요 함정을 회피 가능
• 반복 사고 유형(캐스케이드, 업로드, 페칭 경로 혼용) 재발 방지
• 기술 의사결정의 근거가 문서로 남아 같은 논의를 반복하지 않음

5. 로워드(loword.co.kr) — 키워드 인텔리전스 플랫폼

5-1. CSR → 서버 컴포넌트 전환

배경 및 문제

검색 유입이 매출의 핵심인 서비스인데 CRA 기반 CSR 구조라 크롤러가 빈 HTML을 수신했습니다. 이 작업을 "SSR 도입"이 아니라 데이터가 클라이언트로 넘어가는 경계를 다시 긋는 작업으로 접근한 것이 이후 모든 설계의 출발점이 되었습니다.

전환 근거 3가지

• 색인 — 크롤러가 실제 콘텐츠가 담긴 HTML을 수신
• 페이로드 통제 — 무엇을 클라이언트로 보낼지 서버가 결정할 수 있게 됨(5-3의 전제)
• 번들 축소 — 클라이언트 컴포넌트 범위가 줄면 JS 전송량이 줄어듦

구조가 규칙을 강제하게 하기

'use client'가 상위로 번지면 서버 컴포넌트 도입의 이점이 조용히 사라집니다. 이건 문서로 막히지 않는다고 판단해 Container(서버) · Presenter(클라이언트) · Styled 3-파일 컨벤션으로 분리했습니다(74 / 74 / 111 파일). 경계를 지키는 일이 개인의 주의력이 아니라 파일을 만드는 절차 자체에 들어가게 하는 것이 목적이었습니다.

5-2. SEO 아키텍처

• 계층형 Metadata — 상세 > 카테고리 > 사이트 기본값 순으로 폴백해, 개별 페이지가 비어 있어도 항상 유효한 메타가 나가도록 구성
• canonical 정책 — "존재하는 파라미터만 순서를 고정해 재조립". 쿼리스트링을 그대로 두면 정렬·필터 조합마다 파생 URL이 무한 증식해 크롤 버짓이 낭비되고, 전부 제거하면 실제로 다른 콘텐츠가 하나로 합쳐집니다. 존재하는 파라미터만 정해진 순서로 재조립하는 방식이 두 실패를 동시에 피합니다
• 13종 JSON-LD 구조화 데이터 — 대형 포털과 blue link로 정면 경쟁하는 대신, 리치 결과로 SERP 점유 면적을 넓혀 CTR을 확보하는 전략
• 스키마 분기 논리 — 채택 답변이 없는데 QAPage + acceptedAnswer를 선언하면 구조화 데이터 오류로 리치 결과 자격 자체를 잃습니다. 조건을 만족하지 못하면 Review로 폴백하도록 분기
• 슬러그 구분자를 ______로 지정 — 제목에 하이픈이 흔히 포함되므로 일반적인 - 구분자는 역파싱을 깨뜨립니다. 제목 내 문자와 충돌하지 않으면서 역파싱 가능한 구분자를 선택
• sitemap XML escape — UGC 제목에 포함된 & 하나로 사이트맵 전체가 무효화됩니다. 이스케이프 처리를 사이트맵 생성의 필수 단계로 고정

5-3. 봇 감지 분기 콘텐츠 서빙 ★

배경 및 문제

UGC 본문은 유료 콘텐츠라 비로그인 사용자에게 전부 보여주면 전환이 발생하지 않습니다. 반대로 크롤러에게 가려서 내보내면 본문이 색인되지 않아 롱테일 검색 유입이 사라집니다. 전환율과 색인이 정면으로 상충하는 구조였습니다.

검토하고 버린 방안

구현과 논지

• userAgent() 봇 판별을 서버 컴포넌트에서 수행 — 비로그인 사용자에겐 서버 단에서 잘라 내려보내고, 크롤러에겐 전문 제공
• 자르는 기준을 문자 수가 아니라 <p> 5개로 둔 이유 — 문자 수로 자르면 태그 중간이 끊겨 마크업이 파손됩니다
• 이 보호 수준은 CSR에서는 원리적으로 달성 불가능합니다. 서버 컴포넌트를 도입한 실질적 이유가 색인만이 아니라 이 지점이었다는 것이 5-1과 이 장을 잇는 논지입니다

5-4. 렌더링 · 스트리밍

• 분석 페이지는 20여 개 외부 데이터 소스를 조합합니다. Promise.all로 묶어도 "가장 느린 것"을 기다리는 성질은 변하지 않으므로, 페이지를 22개 Parallel Route 슬롯으로 물리적으로 분해해 블록 단위로 독립 스트리밍되게 했습니다
• force-dynamic을 택한 이유 — 검색 결과가 사용자·쿼리·플랜별로 달라지므로 정적 캐시는 오답을 서빙합니다
• fallback을 범용 스켈레톤이 아니라 LoadingAnswer 전용 컴포넌트로 만든 이유 — 답변 개수를 이미 알고 있어 자리를 미리 잡으면 CLS가 0이 됩니다
• 렌더링 구조 개선과 CloudFront CDN 적용으로 Lighthouse 평균 40 → 94

5-5. Tag 기반 정밀 캐시 무효화

• 리소스 단위 동적 태그(kinAnswerDetail_{id})와 revalidateTag 37개소로, 상호작용 1건에 페이지 전체가 재검증되던 비용을 변경된 리소스로 한정
• 무효화 함수를 서버에서 정의해 props로 내려보냄 — 클라이언트는 어떤 태그가 무효화되는지 모른 채 콜백만 호출합니다. 캐시 전략을 바꿔도 클라이언트 코드는 무수정
• 결과적으로 서버가 단일 진실의 원천으로 유지되어, 낙관적 UI에서 흔한 불일치 버그 클래스가 원천 제거되었습니다

5-6. Edge Middleware 인증·권한 파이프라인

• applySetCookie의 필요성 — 미들웨어가 Set-Cookie를 실어도 같은 요청의 서버 컴포넌트는 옛 쿠키로 fetch하므로 첫 화면이 로그아웃 상태로 렌더됩니다. 갱신된 토큰을 요청 헤더에 역주입해 같은 사이클 안에서 반영되도록 처리
• 301 / 302 분리 — 영구 이전에는 301로 링크 자산을 승계시키고, 성격이 바뀐 경로에는 302를 써서 색인이 영구히 바뀌는 것을 회피. 301은 브라우저가 영구 캐시하므로 잘못 쓰면 되돌릴 수 없습니다
• 유료 플랜 게이트를 엣지에 배치 — 클라이언트 가드는 화면만 가리고 데이터는 이미 전송된 뒤입니다. 권한 판정을 데이터가 나가기 전 지점으로 옮겨야 실제 차단이 됩니다

5-7. GA4 · GTM 마케팅 계측

• cross-domain linker (임팩트 최대 항목) — SSO·브릿지가 별도 도메인이라, linker가 없으면 모든 가입 전환이 "SSO 도메인 referral"로 집계되어 유입 채널 ↔ 가입의 연결고리가 통째로 끊깁니다. 멀티 도메인 linker로 전환 경로를 복원
• 어필리에이트 어트리뷰션 — 쿠키 세팅과 리다이렉트의 순서가 어트리뷰션 성패를 가릅니다. 상위 도메인 쿠키 승계를 리다이렉트보다 먼저 수행하도록 순서를 고정
• login 이벤트 중복 발화 가드 — tokens && !userInfo?.userId 조건이 없으면 같은 세션에서 이벤트가 반복 발화되어 전환 수가 부풀려집니다. 소셜 채널별로 login 이벤트를 분리 계측

5-8. 네트워크 · 인증 레이어

• NotRefresh 계열 인스턴스 분리가 핵심 — refresh 인터셉터가 달린 인스턴스로 "로그인 상태 확인" API를 호출하면 401 → refresh → 401 무한 재귀에 빠집니다. 재시도 없는 인스턴스를 별도로 두고 사용 기준을 문서화
• 만료(갱신)와 무효(로그아웃)를 분리 판별 — 두 상태를 같은 401로 처리하면 갱신 가능한 사용자를 로그아웃시키거나, 무효 토큰으로 갱신을 무한 시도하게 됩니다

5-9. 기반 구조

• 환경별로 쿠키 키까지 분리 — 운영·개발이 같은 상위 도메인 스코프를 공유하므로 키가 같으면 서로의 세션을 덮어씁니다
• SVGR을 아이콘 디렉터리에만 한정 적용 — 전역 적용하면 모든 SVG가 컴포넌트로 변환되어 next/image 최적화 대상에서 이탈합니다
• 자체 디자인 시스템(LDComponents) 구축, 과금되는 외부 검색량 API에 캐싱 레이어를 설계해 중복 호출 제거, NGINX 단 요청 제한으로 DoS/DDoS·광고 어뷰징(AdClicker) 트래픽 차단, 포트원 기반 구독 결제 도입

5-10. 검색 결과 화면의 정보 위계 설계

키워드 분석 결과는 지표 종류가 많아 한 화면의 정보 밀도가 높습니다. 숙련 사용자에게는 다 보이는 편이 유리하지만, 그렇지 않은 사용자에게는 무엇을 먼저 봐야 할지 알 수 없는 화면이 됩니다. 항목을 줄이면 그 지표를 쓰던 사용자를 잃으므로, 정보의 양이 아니라 우선순위가 화면에 드러나지 않는 것이 문제라고 보고 노출 여부가 아닌 배치와 시각적 위계로 접근했습니다.

• 판단에 직접 쓰이는 지표를 상단에 고정하고 보조 지표는 아래 계층으로 내려, 스캔 경로에 우선순위가 반영되게 재배치
• 22개 슬롯 스트리밍(5-4)과 결합해 먼저 보여줄 수 있는 것을 먼저 보여주는 순서를 렌더링 단위와 일치시킴

5-11. 정량 요약

6. 팀 AI 개발 환경 도입 및 컨텍스트 체계 설계

6-1. 출발점은 도입 찬성이 아니라 회의론이었음

저는 처음부터 AI 활용에 긍정적이지 않았습니다. 자신이 작성한 코드는 명확히 알고 있어야 하고, 내가 모르는 코드는 없는 편이 낫다고 생각했기 때문입니다. 실제로 신입·팀원 코드를 리뷰하며 "왜 이렇게 구현했는지"를 물었을 때 답하지 못하는 경우를 반복적으로 확인했습니다.

6-2. 문제 재정의 — "질문 역량"에서 "규칙의 시스템화"로

같은 내용을 물어도 어떻게 묻느냐에 따라 답의 품질이 천차만별이었습니다. 검토할 만한 답을 받으려면 질문의 질이 먼저 올라가야 한다고 보고, 개인 차원에서 두 가지를 시도했습니다.

• 제가 실제로 던진 질문을 팀에 공유하며 배경 설명과 명확한 요구사항을 담는 방식을 전달
• 팀원의 질문을 함께 검토하고 피드백

그러나 두 방법 모두 한계가 분명했습니다. 개인 코칭은 인원 수에 비례해 확장되지 않고, 무엇보다 새 팀원이 합류할 때 그 지식 베이스가 이전되지 않습니다. 같은 설명을 매번 처음부터 반복하게 됩니다.

6-3. 도구 선정 기준 — 성능이 아니라 시스템화 가능성과 비용

검토 시점에 좋다고 평가되는 도구는 이미 많았고, 모델 성능은 상향 평준화되어 선정의 결정 요인이 아니라고 판단했습니다. 그래서 기준을 두 가지로 세웠습니다.

이 기준으로 Claude Code 팀 플랜을 채택했습니다. 하나의 컨텍스트에 개발팀의 문화·규칙·컨벤션을 학습시켜 두면, 신규 합류자가 시트를 할당받아 쓰는 순간부터 팀 기준을 그대로 이어받고 질문 방식에도 최소한의 안전선이 생긴다고 판단했습니다. 개인 코칭으로는 만들 수 없었던 인수인계 경로가 도구 자체에 생기는 셈입니다.

6-4. 4계층 컨텍스트 체계 설계 — 규칙 시스템화와 비용 절감을 동시에

규칙을 한 파일에 몰아넣으면 관련 없는 작업에도 전체가 로드되어 비용이 발생하고, 정확도도 떨어집니다. 반대로 흩어 놓으면 어디를 봐야 할지 알 수 없습니다. 그래서 규칙의 적용 범위와 로드 단위를 일치시키는 방향으로 계층을 나눴습니다.

Studio를 따로 뺀 것이 이 설계의 요지를 잘 보여줍니다. Studio 가이드는 레듀 작업의 대부분에는 필요하지 않은데 분량은 가장 큰 문서였습니다. 공통 파일에 합치면 무관한 작업마다 그 비용을 내게 되므로, 파일을 세분화하는 것 자체가 곧 비용 설계였습니다.

각 계층의 문서는 도입에 맞춰 새로 작성했고, 이후 프로젝트가 진행되는 과정에서 계속 갱신하고 있습니다. Studio 가이드도 도입 이후 Phase 2를 진행하며 노드·필드 규약이 늘어난 만큼 함께 보강했습니다.

6-5. 결과

• 코드 품질 — 코드리뷰 단계에서 개선이 확인됨. 규칙이 컨텍스트에 들어가 있어 이전에는 리뷰에서 지적하던 항목이 작성 시점에 걸러짐
• 비용 — 계층 분리로 필요한 범위만 로드되면서 관리자 계정 대시보드의 사용량 통계 추이 기준 토큰 사용량이 약 1/3 수준으로 감소
• 생산성 — 코드리뷰로 올라오는 작업량 기준으로 체감 60% 이상 향상. 별도 측정 지표를 세워 계측한 값은 아니며, 리뷰 대상의 증가폭을 근거로 한 추정치입니다
• 인수인계 — 신규 합류자가 별도 교육 없이 팀의 컨벤션과 프로젝트별 함정이 반영된 결과를 받게 되어, 온보딩 문서와 같은 목적을 도구 레벨에서도 달성

학력

• 순천향대학교 의료IT공학과 학사  (2017.03 ~ 2023.01 졸업)

일하는 방식

아래 6가지는 로워드 FE 팀의 기준으로 제가 정리해 공개한 글의 항목입니다. 각 항목이 실제 어떤 결정으로 나타났는지 위 프로젝트에서 대응되는 사례를 함께 적었습니다.
원문 — 로워드 FE 팀으로 일을 한다는 것은?

나에게 주어진 일이 무엇인지 정확히 알고 시작해요

기능을 받으면 구현부터 시작하지 않고, 왜 필요한지와 전체 흐름에서 어떤 위치인지부터 이해하려고 합니다. 레듀 어드민의 범위는 상상해서 정하지 않고 실제로 들어온 개발 요청을 분류해 역산했고(4-2), 1차 페이지 빌더의 블록은 운영 중인 랜딩을 역분석해 추출했으며(4-3), 디자인 시스템은 레거시 컴포넌트를 전수 조사해 무엇을 담지 않을지부터 기준을 세웠습니다(3-11). 브릿지에서 라우트 그룹 분리가 아니라 배포 단위 분리를 택한 것도, 요구가 "코드 정리"가 아니라 "장애 영향도 축소"임을 먼저 확정했기 때문입니다(2-1).

반복되는 일을 줄이고, 기준은 맞추려고 해요

같은 것을 여러 번 만들지 않고 한 번 잘 만들어 계속 쓰는 구조를 우선합니다. 몰마다 코드를 복제하는 대신 테넌트를 데이터로 분리했고(4-1), 5개 앱의 공통 UI는 모노레포와 2계층 단방향 의존으로 수렴시켰으며(2-2), 그 기준을 코드와 연결된 디자인 시스템으로 고정했습니다(3장). 빌더에서도 같은 문제가 나타나 페이지가 정의를 복사하지 않고 참조만 저장하는 모델로 전환했습니다(1장 Phase 2).

코드를 작성할 때는 항상 '왜?'가 붙어요

같은 결과를 내는 방법은 늘 여러 개라, 무엇을 선택했는지보다 왜 선택했는지를 설명할 수 있어야 한다고 생각합니다. 이 문서의 각 절에 채택안과 함께 검토하고 기각한 대안을 남긴 이유입니다 — 테넌트 식별 3안 비교(4-1), 복사 vs 참조(1장 Phase 2), 캐시 태그를 앱 경계가 아닌 데이터 경계로 둔 근거(2-3), 콘텐츠 보호 3안 비교(5-3), colorSet 확장점 2안 비교(3-9). tv()를 직접 만들 때는 성능을 실측하고 기존 라이브러리와 108개 조합을 전수 비교한 뒤에야 도입했습니다(3-3). 감수한 한계도 같이 적습니다 — extend·slots 미지원, 어드민 라우팅의 코드 스플리팅 손실, 브랜치 분기 문제.

실수는 할 수 있지만, 반복하지 않으려고 해요

같은 실수가 반복되면 개인이 아니라 구조나 프로세스의 문제로 봅니다. 접근성 위반이 계속 쌓이던 원인이 검사가 todo였다는 데 있어 CI 실패 조건으로 승격했고(3-2), 모바일 override가 조용히 무시되던 버그는 필드를 unified / device-aware로 명시 분류하도록 강제해 차단했습니다(1장 ④). 타입으로 막을 수 있는 것은 타입으로 옮기고(렌더러 레지스트리 exhaustive 타이핑), 막을 수 없는 것은 규약과 문서로 남깁니다. 재현이 어려운 사고일수록 원인과 경위를 기록해 다음 사람이 같은 곳에서 헤매지 않게 합니다 — RSC 번들 오염, CSS 캐스케이드 2종, 프로덕션 전용 !important 소실.

기술은 유행이 아니라 필요로 선택해요

기술은 목적이 아니라 도구라고 생각해서, 필요하면 적극적으로 도입하고 필요하지 않으면 바꾸지 않습니다. 디자인 시스템이 확정되기 전이라 npm publish 사이클을 감당할 수 없다고 판단해 workspace 링크를 택했고(2-2), 배포 패키지에 의존성을 얹지 않기 위해 스타일 엔진을 직접 만들되 기능 축소를 대가로 명시했습니다(3-3). 반대로 Next 16 메이저 점프는 이득 대비 리스크가 크다고 보고 제외했고(2-12), 화면 갱신도 구조 변경 비용이 큰 클라이언트 페칭 대신 router.refresh()를 기본으로 두고 필요할 때만 전환하도록 기준을 정했습니다(2-4).

협업은 일을 넘기는 게 아니라, 같이 맞추는 과정이에요

작업 전에 방향을 맞추는 시간이 결국 전체 시간을 줄인다고 생각합니다. 백엔드와는 캐시 태그·웹훅 요청 규격·소켓 이벤트명을 합의하고 태그 추가 시 양쪽에 반영하는 프로토콜을 만들었고(2-14), 마케팅·데이터팀에는 전환 이벤트를 재설계하기 전에 "기존 지표와 연속선상에서 해석 불가"라는 영향도를 먼저 공유했습니다(2-7). 팀 안에서는 변경 이력을 "원인/이유 + 수정" 형식으로 남겨 작성자가 아닌 사람이 맥락을 잡을 수 있게 하고, 코드를 읽으면 알 수 있는 것이 아니라 모르면 사고가 나는 것 중심으로 온보딩 문서를 씁니다(4-6, 2-14).