| name | custom-component |
| description | 비대한 React 컴포넌트를 스코프별 서브 컴포넌트로 분리, 시맨틱 HTML 적용, 전용 서브디렉토리 구조화 |
| triggers | ["custom-component","컴포넌트 분리","컴포넌트화","split component"] |
| argument-hint | <component-file-path> |
| quality | high |
Custom Component
비대한 React 컴포넌트의 스코프별 서브 컴포넌트 분리, 시맨틱 HTML 적용, 전용 서브디렉토리 구조화.
When to Activate
- 단일 컴포넌트가 100줄 이상이고 여러 시각적/논리적 영역을 포함할 때
- 컴포넌트 내부에 조건부 렌더링이 복잡하게 얽혀 있을 때
$ARGUMENTS로 대상 컴포넌트 파일 경로가 주어질 때
Workflow
1단계: 분석
- 대상 컴포넌트 파일 읽기
- 해당 컴포넌트의 사용처와 의존성 Grep 파악
- 프로젝트 내 기존 컴포넌트 분리 패턴 탐색 (예:
tier-card/ 패턴)
2단계: 분리 설계
- 시각적/논리적 영역별 분리 지점 식별
- 각 영역에 적합한 시맨틱 HTML 태그 매핑:
- 페이지 섹션 →
<section>
- 도입부/제목 →
<header>
- 보조/장식 콘텐츠 →
<aside>
- 이름-값 쌍 →
<dl>/<dt>/<dd>
- 동적 알림 →
role="alert"
- 각 서브 컴포넌트의 책임과 props interface 정의
3단계: 서브 컴포넌트 생성
- 의존성 없는 서브 컴포넌트부터 생성 (leaf → root 순서)
- 레이아웃 컴포넌트는
children: ReactNode 기반 composition 패턴 사용
- prop pass-through 발생 시 children composition 대체
4단계: 오케스트레이터 리팩터
- 오케스트레이터 JSX는 HTML 태그 없이 컴포넌트만 조합:
<Layout>
<Content>
<ChildA ... />
<ChildB />
</Content>
<Sidebar />
</Layout>
- 오케스트레이터 로직(상태, 이펙트, 핸들러, API 호출)은 전용 훅으로 분리 (
/custom-hook 참조)
- 서브 컴포넌트로 이동한 import 정리
5단계: 디렉토리 구조화
- 오케스트레이터 전용 서브 모듈은 동명 서브디렉토리 안의
_components/, _hooks/로 분류:
component.tsx
component/
_components/
sub-a.tsx
sub-b.tsx
_hooks/
use-sub-action.ts
- 서브 컴포넌트 전용 훅은
_hooks/ 하위 배치, 전용 서브 훅은 훅 동명 서브디렉토리에 배치:
component/
_hooks/
use-sub-action.ts
use-sub-action/
use-state.ts
use-auth.ts
- 다른 곳에서도 사용되는 독립 컴포넌트/훅은 상위 디렉토리에 유지
- import 경로 업데이트
6단계: 검증
pnpm build 성공 확인
pnpm lint 통과 확인
- 시각적 변경 없음 확인 (Tailwind preflight가 시맨틱 태그 기본 스타일 초기화)
Constraints
- 오케스트레이터 JSX의 HTML 태그 금지 — 컴포넌트만 조합
- prop pass-through 대신 children composition 패턴 우선
- 프로젝트 코드 규칙 준수 (CLAUDE.md 참조): arrow function, named export, Tailwind only 등
- 기존 프로젝트 분리 패턴(tier-card/ 등) 기준 일관성 유지
Success Criteria
- 오케스트레이터 return문의 HTML 태그 없음
- 각 서브 컴포넌트의 단일 책임
- 전용 서브 컴포넌트의 하위 디렉토리 격리
- 빌드/린트 통과
- 시각적 변경 없음