인터페이스 설계 멘탈 모델 v3

┌─────────────────────────────────────────────────┐ │ 0. 설계가 필요한가? │ │ └─ 필요 없으면 → 뭉쳐둠, 끝 │ └─────────────────┬───────────────────────────────┘ │ 필요하면 ▼ ┌─────────────────────────────────────────────────┐ │ 1. 복잡성 회피 │ │ ├─ 일반해에 매칭 → 지움 │ │ ├─ 플랫폼/라이브러리 → 쓰고 끝 │ │ └─ 남는 자투리만 → 다음 단계로 │ └─────────────────┬───────────────────────────────┘ ▼ ┌─────────────────────────────────────────────────┐ │ 2. What 인수분해 │ │ ├─ 일반 / 구체 나눔 │ │ └─ 요구사항의 언어 = 경계 │ └─────────────────┬───────────────────────────────┘ ▼ ┌─────────────────────────────────────────────────┐ │ 3. 안에서 바깥으로 조립 │ │ ├─ leaf에서 출발 │ │ ├─ 작은 것들의 조합 (레이어드) │ │ └─ 구체는 바깥으로, IoC로 받음 │ └─────────────────┬───────────────────────────────┘ ▼ ┌─────────────────────────────────────────────────┐ │ 4. 형태 결정 │ 5. 연결 결정 │ │ ├─ 일반해 차용 │ ├─ 관절 선택 │ │ └─ 관용어 사용 │ └─ IoC 레벨 결정 │ └─────────────────┬───────────────────────────────┘ ▼ ┌─────────────────────────────────────────────────┐ │ 6. 점검 │ │ ├─ 호출자 관점에서 예측 가능한가? │ │ └─ 주니어 인수인계 / 콜센터 테스트 │ └─────────────────────────────────────────────────┘ ↺ 전 과정을 점진적으로 (작게, 반복)

IF 숙련도 낮음 → 뭉쳐라 IF 분리가 잦음 → 멈춰라 IF 일회성 컴포넌트 → 관대하게 적용 IF 재사용 범위 넓음 (디자인 시스템, 공유 모듈) → 설계 투자 가치 있음

// ❌ props가 통로로 전락 function ProductListPage() { const { data, isLoading, error } = useQuery(['products'], fetchProducts); const [filter, setFilter] = useState('all'); return ( <ProductList products={data} isLoading={isLoading} error={error} filter={filter} onFilterChange={setFilter} /> ); }

// ✓ 자기 완결적 function ProductList() { const { data, isLoading, error } = useQuery(['products'], fetchProducts); const [filter, setFilter] = useState('all'); if (isLoading) return <Skeleton />; if (error) return <ErrorSection />; return ( <List items={data} filter={filter} onFilterChange={setFilter} /> ); }

const GetProduct = ({ children }: { children: (product: Product) => React.ReactNode }) => { const { id } = useParams<{ id: string }>(); return ( <QueryErrorResetBoundary> {({ reset }) => ( <ErrorBoundary fallback={<ErrorSection onRetry={reset} />}> <Suspense fallback={<Skeleton />}> <SuspenseQuery {...productQueries.detail(Number(id))}> {({ data }) => <>{children(data)}</>} </SuspenseQuery> </Suspense> </ErrorBoundary> )} </QueryErrorResetBoundary> ); };

function ProductDetailPage() { return ( <> <GetProduct> {product => ( <section> <ProductImage images={product.images} /> <ProductInfoSection product={product} /> <Stock label="재고" value={product.stock} /> <QuantityCounter product={product} /> <AddToCartButton product={product} /> </section> )} </GetProduct> <GetProduct> {product => ( <section> <Text variant="H2_Bold">상세 정보</Text> <Text>{product.detailDescription}</Text> </section> )} </GetProduct> <GetRecommendedProducts> {recommendedProducts => ( <section> <Text variant="H2_Bold">추천 제품</Text> <HStack> {recommendedProducts.map(product => ( <Link to={`/product/${product.id}`} key={product.id}> <RecommendedProduct product={product} /> </Link> ))} </HStack> </section> )} </GetRecommendedProducts> </> ); }

데이터, 계산 → 순수 함수로 액션 → 면적 최소화

"이거 뭐랑 닮았지?" → "List네" → 지움, 끝

IF 복잡한 로직 → 먼저 플랫폼/라이브러리가 풀어놓은 게 있나 체크 IF 있으면 → 쓰고 끝 IF 없으면 → 그때 직접 설계 IF 직접 로직 짜고 있음 → "차력쇼 아닌가?" 자문

// ❌ 굳이 분리 const handleClick = () => { setCount(count + 1); }; <button onClick={handleClick}>+</button> // ✓ 인라인 <button onClick={() => setCount(count + 1)}>+</button>

IF 작은 핸들러 함수 → 웬만하면 인라인 시도 IF 핸들러가 커지거나 재사용 필요 → 그때 분리 IF 분리했는데 암묵적 인자 생김 → 설계 재검토

일반: 여러 곳에서 반복되는 패턴, 도메인에 무관한 것 구체: 이 맥락에서만 필요한 것, 도메인 특화된 것

기획서가 '할인'이라 부르면 → 코드에서도 '할인'이 경계 기획서가 '장바구니'라 부르면 → 코드에서도 '장바구니'가 경계

페이지 └─ 섹션 └─ 컴포넌트 └─ 요소 └─ (더 이상 분해할 What 없음)

IF 일반 → 일반해의 idiomatic 인터페이스에 맞춤 IF 구체 → 바깥으로 밀고 IoC로 주입받기를 시도 IF 다음 중 하나면 → 구체를 내부로 담는다 (분리 안 함) - 응집도가 높아지는 경우 - 경감되는 고통 대비 설계 비용이 안 맞는 경우 - 기획 문서의 언어(변경의 단위)와 맞는 경우

ProductCard (요구사항 덩어리) ├─ 이미지 (일반: Image 컴포넌트) ├─ 제목 (일반: Text 컴포넌트) ├─ 가격 (일반: Text + 포맷팅) ├─ 장바구니 버튼 (구체: 이 맥락 특화) └─ 좋아요 버튼 (구체: 이 맥락 특화)

시작점: AST leaf node (추상화 멘탈모델의 가장 안쪽) 방향: 안 → 바깥 결과: 작은 것들이 조합되어 큰 것이 됨

이너 → 셔츠 → 가디건 → 패딩조끼 → 목도리 → 코트 → 장갑

// 기본 이미지 onClose: withFoo(domainFn, { config }) // 겹겹이 쌓기 onClose: withLogging(withAnalytics(withConfirm(closeFn, {...}), {...}), {...}) ↑ ↑ ↑ ↑ 레이어4 레이어3 레이어2 레이어1(코어)

1. 가장 안쪽(leaf)부터 시작 2. 데이터/계산을 순수함수로 빼냄 3. 일반 → 일반해의 표준 인터페이스 차용 4. 구체 → 바깥으로 밀고 IoC 5. 작은 것들을 조합해서 큰 덩어리 표현 6. 바깥으로 한 층씩 쌓아올림

IF 일반해 중심으로 조립 안 됨 → 추상화 경계 잘못 OR What 추출 잘못 IF props drilling 발생 → 억지로 뚫지 말고 의존성 역전 고려 IF 겹겹이 쌓여서 가장 안쪽에 플래그 필요 → 망함 신호 IF 조합 늘어날 때마다 컴포넌트 수정 → IoC 부족 IF showX 플래그 증가 → IoC로 전환 IF 큰 추상화가 한 덩어리로 생김 → 안에서 밖으로 안 했다는 신호

IF 내부에 hook 있음 → 커스텀 훅 OK IF 내부에 hook 없음 → use- 붙이지 말고 일반 함수로 IF 커스텀 훅이 커짐 → 데이터/계산을 순수함수로 빼낼 수 있는지 검토 IF 커스텀 훅 만들어야 함 → 일단 슬픈 상황으로 가정, 정당한 What 기반인지 검토

작은 hook에서 나온 데이터 + 순수함수 여러 겹 레이어드 + 사용처 가까이에서 결합

// ❌ 큰 덩어리가 한번에 function ProductCard({ product, onAddToCart, onLike }) { const [isLiked, setIsLiked] = useState(false); const [isInCart, setIsInCart] = useState(false); const handleAddToCart = () => { setIsInCart(true); onAddToCart(product); }; const handleLike = () => { setIsLiked(!isLiked); onLike(product); }; return ( <div> <img src={product.image} /> <h3>{product.name}</h3> <p>{formatPrice(product.price)}</p> {showCartButton && ( <button onClick={handleAddToCart}> {isInCart ? '담김' : '장바구니'} </button> )} {showLikeButton && ( <button onClick={handleLike}> {isLiked ? '♥' : '♡'} </button> )} </div> ); }

// ✓ 안에서 바깥으로, IoC로 구체를 받음 function ProductCard({ product, bottomAddon }: { product: Product; bottomAddon?: React.ReactNode; }) { return ( <div> <img src={product.image} /> <h3>{product.name}</h3> <p>{formatPrice(product.price)}</p> {bottomAddon} </div> ); } // 사용처에서 구체를 주입 <ProductCard product={product} bottomAddon={ <Flex> <AddToCartButton product={product} /> <LikeButton product={product} /> </Flex> } />

"이거 뭐랑 닮았지?" → "Toggle이네" → checked, onChange 그대로 차용 → 끝

on- : 이벤트 핸들러 (onClick, onChange, onClose) is- : boolean 상태 (isOpen, isLoading, isDisabled) has- : 존재 여부 (hasError, hasItems) render- : 렌더 함수 (renderItem, renderHeader) -ed : 과거/수동 상태 (disabled, checked, selected)

"이 버튼 누르면 모달이 닫혀요" → onClose ✓ "이 버튼 누르면 handleModalDismissAction이 실행돼요" → ✗

IF 재사용 범위 넓음 → 도메인 용어 제거 (onSelect) IF 내부용 → 도메인 용어 허용 (handleProductSelection)

문짝 (콜백): 밖에서 "뭘 할지" 결정 → onClose, onSubmit, onChange 어깨 (슬롯): 밖에서 "뭘 보여줄지" 결정 → children, bottomAddon, header 무릎 (설정): 밖에서 "어떤 변형인지" 결정 → variant, size, disabled 두개골 (고정): 열지 않음 → 내부 상수, 하드코딩

1. "이 관절이 없어도 이 컴포넌트인가?" 체크 2. Yes → 고정 (열지 않음) 3. No → 열어야 함 → 유형 결정

IF 관절 없어도 컴포넌트 성립 → 고정 (내부 상수) IF 밖에서 "뭘 할지" 결정 → 콜백 (onSubmit, onChange) IF 밖에서 "뭘 보여줄지" 결정 → 슬롯 (children, bottomAddon) IF 밖에서 "어떤 변형인지" 결정 → 설정 (variant, size)

Level 1 (기본): children, callback → 문제의 80% 해결 → 가장 먼저 시도 Level 2 (중급): named slots → 복잡한 레이아웃 → header, footer, sidebar 등 Level 3 (고급): render props, compound component, 로직 주입 → 라이브러리급 유연성 → 정말 필요할 때만

IF 간단한 확장 → Level 1 (children, callback) IF 복잡한 레이아웃 → Level 2 (named slots) IF 라이브러리급 유연성 → Level 3 (render props, compound, 로직 주입) IF 자주 쓰는 조합 있음 → Preset으로 닫아둠

onClose: withFoo(domainFn, { config })

onClose: withFoo(domainFn, { config }) ↑ ↑ ↑ ↑ 관절 레이어 실제로직 설정

IF 구체적인 것 → 바깥으로 밀어라 IF 결합이 생기면 → 필사적으로 끊어라 IF 목적/의도 없으면 → 하지 마라 IF "혹시 모르니까" → 비용으로만 전가됨 IF 플랫폼/라이브러리 개발자 아닌데 제네릭 빡세게 → 잘못된 신호

구현 끝 → 모드 전환 → 점검 시작

- 설명해야 할 사정이나 암묵적 맥락이 많은가? - 생각만 해도 지치는가? - 말이 길어지고 숨이 찰 것 같은가? → 하나라도 Yes면 잘못된 것

- 자연스럽게 말이 되는가? - 전문 용어 없이 설명 가능한가? → 자연스럽게 말이 되면 고객 언어

- "인터페이스만 보고 안 까봐도 돼?" → 놀람 최소화 - "props가 통로로 전락하지 않았나?" → 본질이 드러나는가 - "이 관절이 왜 필요해?" → 불필요한 열림 - "함수가 받은 것만으로 일할 수 있어?" → 자기완결성

- "이 컴포넌트는 무엇을 모르는가?" → 모름 목록이 길수록 좋음 - "새 요구사항이 왔을 때 어디를 수정하나?" → 사용처만 수정하면 성공, 컴포넌트 열어봐야 하면 IoC 부족 - "이 컴포넌트를 다른 곳에서 쓸 수 있나?" → 다른 프로젝트에 그대로 가져갈 수 있으면 성공

IF 같은 팀 → 좀 거칠어도 됨 IF 다른 팀 → 내부를 몰라야 함, 깨지면 안 됨 IF 외부(라이브러리) → 버전 관리, 하위 호환성 필수

잘못 열면 → 사용처가 의존함 → 닫으면 breaking change 안 열어도 될 걸 열면 → 복잡성만 증가 → 유지보수 비용

// Step 1: 닫아둠 function ProductCard({ product }: { product: Product }) { return ( <div> <img src={product.image} /> <h3>{product.name}</h3> <p>{formatPrice(product.price)}</p> <AddToCartButton product={product} /> </div> ); }

// 사용처에서 긴장 발생: // "장바구니 버튼 대신 좋아요 버튼 넣고 싶은데..." // "버튼 두 개 다 넣고 싶은데..." // Step 2: 긴장이 생긴 부분만 연다 function ProductCard({ product, bottomAddon // 이 관절만 열림 }: { product: Product; bottomAddon?: React.ReactNode; }) { return ( <div> <img src={product.image} /> <h3>{product.name}</h3> <p>{formatPrice(product.price)}</p> {bottomAddon} </div> ); }

Level 1 (children, callback) → 문제의 80% 해결 ↓ 긴장 발생 Level 2 (named slots) → 복잡한 레이아웃 ↓ 긴장 발생 Level 3 (render props, compound) → 라이브러리급 유연성

IF showX 플래그가 늘어남 → IoC로 전환할 신호 IF 사용처마다 분기가 생김 → 관절을 열 신호 IF 제네릭이 빡세짐 → 과하게 열었다는 신호 IF "혹시 모르니까" 열고 있음 → 멈출 신호

// v1: 완전히 닫힘 <Dialog title="삭제" onClose={close}> 정말 삭제하시겠습니까? </Dialog> // v2: 긴장 발생 ("버튼 텍스트 바꾸고 싶은데") // → 버튼 관절만 연다 <Dialog title="삭제" onClose={close} confirmText="삭제" // 열림 cancelText="취소" // 열림 > 정말 삭제하시겠습니까? </Dialog> // v3: 긴장 발생 ("버튼 영역 자체를 커스텀하고 싶은데") // → 슬롯으로 전환 <Dialog title="삭제" onClose={close}> 정말 삭제하시겠습니까? <Dialog.Footer> // 슬롯으로 열림 <Button variant="danger">삭제</Button> <Button variant="ghost">취소</Button> </Dialog.Footer> </Dialog>

□ 0. 설계가 필요한가? - 숙련도, 재사용 범위, 일회성 여부 확인 □ 1. 복잡성 회피 - 일반해에 매칭되는가? - 플랫폼/라이브러리가 풀어놓은 게 있는가? - 인라인으로 단순화할 수 있는가? □ 2. What 인수분해 - 일반과 구체로 나눴는가? - 요구사항의 언어가 경계인가? □ 3. 안에서 바깥으로 조립 - leaf에서 출발했는가? - 레이어드 옷차림처럼 겹쳐지는가? - 구체는 바깥으로 밀었는가? □ 4. 형태 결정 - 일반해/관용어를 따르는가? - 콜센터 테스트 통과하는가? □ 5. 연결 결정 - 필요한 관절만 열었는가? - IoC 레벨이 적절한가? □ 6. 점검 - 주니어 인수인계 테스트 통과하는가? - 콜센터 테스트 통과하는가? - 모름 목록이 긴가? - 사용처만 수정하면 되는가? □ 진행 방식 - 점진적으로 하고 있는가? - 한 번에 하나의 모자만 쓰고 있는가?

// 1) 소통 안 하는 음침한 블랙박스 직원 // 아무것도 소통하지 않고 음침하게 자기 영역을 감춤 function 소통안하는음침한블랙박스직원(): JSX.Element // 2) 잡다하게 요구만 많은 직원 // 별로 하는 일도 없는데 잡다하게 많이 요청함 function 잡다하게요구만많은직원(props: { userId: string userName: string userEmail: string userAge: number userGender: string userAddress: string userPhoneNumber: string userCreatedAt: Date userUpdatedAt: Date }): JSX.Element // 3) 오지라퍼 직원 // 남의 것까지 받아서 건드림 function 오지라퍼직원(props: { user: User setUser: (user: User) => void globalSettings: Settings setGlobalSettings: (settings: Settings) => void }): JSX.Element // 4) 횡설수설하는 직원 // 뭘 해달라는 건지 모르겠음 function 횡설수설하는직원(props: { data: unknown flag1: boolean flag2: boolean mode: 'A' | 'B' | 'C' type: string }): JSX.Element

어떤 직원이 일할 때 멘보샤가 필요함 (eg. props로 멘보샤를 받음) 말이 되나 싶어서 일할 때 멘보샤가 왜 필요하냐고 꾸짖고 뺐음 그러자 공장 창고 물류가 멈춤 알고 봤더니 이 직원이 거래하는 거래처 직원이 멘보샤를 안 주면 일을 안 해주는 것이었음

[조립 실패] - 일반해 중심으로 조립 안 됨 - props drilling 발생 - 겹겹이 쌓여서 가장 안쪽에 플래그 필요 - 조합 늘어날 때마다 컴포넌트 수정 - showX 플래그 증가 - 큰 추상화가 한 덩어리로 생김 [훅 실패] - 내부에 hook 없는데 use- 붙임 - 커스텀 훅이 비대해짐 - 정당한 What 없이 훅 생성 [인터페이스 실패] - 설명해야 할 암묵적 맥락이 많음 - 말이 길어지고 숨이 참 - 제네릭이 빡세짐 - "혹시 모르니까"로 관절 열음 [진행 실패] - 한번에 크게 함 - 두 모자 동시에 씀 - 10분 안에 안 끝남 - 신호 없이 시작함