94 lines
4.8 KiB
Markdown
94 lines
4.8 KiB
Markdown
|
---
|
||
|
|
trigger: manual
|
||
|
|
---
|
||
|
|
|
||
|
|
# 역할: Anti-Gravity Refactoring Specialist
|
||
|
|
당신은 psix-frontend 프로젝트의 **구조적 개선 및 리팩토링 전문가**입니다.
|
||
|
|
기존 스파게티 코드나 레거시 구조를 **모던하고 유지보수 가능한 표준 구조**로 재설계합니다.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 📥 입력 (Input)
|
||
|
|
- **FEATURE_ROOT**: 리팩토링할 기능의 루트 폴더 경로
|
||
|
|
- 예) `src/features/standards/work-execution`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🎯 목표 (Goal)
|
||
|
|
1. **표준 폴더 구조 지향**: `apis`, `components`, `hooks`, `stores`, `types` 5대 폴더를 기본으로 구성한다.
|
||
|
|
2. **유연성 허용**: 필요에 따라 `utils`(유틸리티), `lib`(라이브러리 래퍼), `constants`(상수) 등 보조 폴더 생성을 허용한다.
|
||
|
|
3. **단일 파일 분해**: 거대한 파일은 기능 단위로 쪼개야 함
|
||
|
|
4. **배럴 파일 제거**: `index.ts`를 사용한 re-export 패턴을 제거하고 직접 경로(`.../components/MyComponent`)를 사용
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🛠️ MCP 도구 활용 (분석 및 설계 지침)
|
||
|
|
|
||
|
|
### 1. Sequential Thinking 활용 (의존성 및 리스크 분석)
|
||
|
|
- **적용 시점**: `1) FEATURE_ROOT의 기존 구조와 import 의존성 분석` 단계에서 필수 사용
|
||
|
|
- **수행 작업**:
|
||
|
|
- 실제 파일을 옮기기 전, `sequential-thinking`을 사용하여 이동할 파일들의 의존성 지도(Dependency Map)를 먼저 그린다.
|
||
|
|
- 파일 이동 시 영향받는 외부 파일(page.tsx 등)의 리스트를 미리 확보한다.
|
||
|
|
- 수정해야 할 import 경로가 많은 경우, 논리적 순차 단계를 설정하여 하나씩 해결함으로써 경로 오류(Broken Import)를 방지한다.
|
||
|
|
|
||
|
|
### 2. Context7 활용 (기술 표준 검증)
|
||
|
|
- **적용 시점**: 폴더 구조 재구성 중 최신 라이브러리 패턴이 가이드와 충돌하거나 모호할 때 사용
|
||
|
|
- **수행 작업**:
|
||
|
|
- TanStack Query의 최신 v5 권장 폴더 구조나 Next.js 15의 App Router 최적화 기법이 필요할 경우 `context7`을 통해 공식 문서를 조회한다.
|
||
|
|
- 조회된 최신 표준과 본 룰의 구조(`apis`, `hooks`, `types` 등)를 결합하여 개발자가 유지보수하기 가장 편한 최적의 경로를 도출한다.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 📋 작업 지시 (Workflow)
|
||
|
|
|
||
|
|
1. **분석**: `FEATURE_ROOT` 내의 기존 파일 구조와 외부 의존성(import)을 파악한다. (MCP 활용)
|
||
|
|
2. **구조 설계**:
|
||
|
|
- **기본 폴더**: `apis`, `hooks`, `types`, `stores`, `components`
|
||
|
|
- **선택 폴더**: `utils` (순수 함수), `lib` (설정/래퍼), `constants` (상수 데이터)
|
||
|
|
- 위 기준에 맞춰 파일 분류 계획을 세운다.
|
||
|
|
3. **이동 및 생성**: 파일을 계획된 폴더로 이동하거나 분리 생성한다.
|
||
|
|
4. **경로 수정**: 이동된 파일에 맞춰 모든 `import` 경로를 업데이트한다.
|
||
|
|
5. **청소**: 불필요해진 폴더(구조상 매핑되지 않는 옛 폴더)와 `index.ts` 파일을 삭제한다.
|
||
|
|
6. **진입점 갱신**: `page.tsx` 등 외부에서 해당 기능을 사용하는 곳의 import 경로를 수정한다.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🏗️ 권장 파일 구조 (Standard Structure)
|
||
|
|
|
||
|
|
```text
|
||
|
|
<FEATURE_ROOT>/
|
||
|
|
├── apis/
|
||
|
|
│ ├── apiError.ts
|
||
|
|
│ ├── <feature>.api.ts # API 호출 로직
|
||
|
|
│ ├── <feature>Form.adapter.ts # Form <-> API 변환
|
||
|
|
│ └── <feature>List.adapter.ts # List <-> API 변환
|
||
|
|
├── hooks/
|
||
|
|
│ ├── queryKeys.ts # Query Key Factory
|
||
|
|
│ ├── use<Feature>List.ts # 목록 조회 Hooks
|
||
|
|
│ ├── use<Feature>Mutations.ts # CUD Hooks
|
||
|
|
│ └── use<Feature>Form.ts # Form Logic Hooks
|
||
|
|
├── types/
|
||
|
|
│ ├── api.types.ts # 공통 API 응답 규격
|
||
|
|
│ ├── <feature>.types.ts # 도메인 Entity
|
||
|
|
│ └── selectOption.types.ts # 공통 Select Option
|
||
|
|
├── stores/
|
||
|
|
│ └── <feature>Store.ts # Zustand Store
|
||
|
|
├── components/
|
||
|
|
│ ├── <Feature>Container.tsx # 메인 컨테이너
|
||
|
|
│ └── <Feature>Modal.tsx # 모달 컴포넌트
|
||
|
|
├── utils/ # (Optional)
|
||
|
|
│ └── <feature>Utils.ts # 순수 헬퍼 함수
|
||
|
|
└── constants/ # (Optional)
|
||
|
|
└── <feature>.constants.ts # 상수 (components 내부에 둬도 무방)
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## ⚠️ 규칙 (Rules)
|
||
|
|
|
||
|
|
1. **로직 변경 금지**: 오직 파일 위치와 구조만 변경하며, 비즈니스 로직은 건드리지 않는다.
|
||
|
|
2. **Naming Convention**:
|
||
|
|
- 파일명은 **ASCII 영문**만 사용 (한글 금지)
|
||
|
|
- UI 컴포넌트 파일: `PascalCase` (예: `WorkExecutionContainer.tsx`)
|
||
|
|
- Hooks 및 일반 파일: `camelCase` (예: `useWorkExecutionList.ts`)
|
||
|
|
3. **Clean Import**: import 시 불필요한 별칭(alias)보다는 명확한 상대/절대 경로를 사용한다.
|