react-study/.agent/rules/refactoring-rule.md

trigger

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)

<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)보다는 명확한 상대/절대 경로를 사용한다.