Instruction file imported from sphinfo/Figma-to-Cursor-Demo (.cursor/rules/code-guide.mdc). Copyright stays with the author.

React & TypeScript 개발 가이드라인 (Revised)

1. 기본 원칙 및 코드 스타일

1.1 코딩 기본 원칙

• 함수형 프로그래밍:
  함수형 컴포넌트와 선언적 프로그래밍 패턴을 사용하여 사이드 이펙트를 최소화합니다.
• 클래스 지양:
  클래스 기반 컴포넌트 대신 함수형 컴포넌트를 사용합니다.
• 가독성 우선:
  코드의 가독성과 유지보수성을 우선시하며, 성능 최적화는 가독성에 영향을 미치지 않는 선에서 진행합니다.
• 모듈화 및 재사용성:
  코드 중복을 피하고, 모듈화 및 재사용 가능한 컴포넌트와 함수를 작성합니다.
• Linting 및 포매팅:
  ESLint, Prettier 등 도구를 사용하여 코드 품질과 일관성을 유지합니다.

1.2 파일 구조 및 명명 규칙

1.2.1 기본 명명 규칙

• 디렉토리 구성:
  기능별 디렉토리 구성. 디렉토리 이름은 kebab-case를 사용합니다.

• 컴포넌트 명명:
  PascalCase 사용 (예: UserProfile)

• 함수/변수 명명:
  camelCase 사용 (예: getUserData)

• 이벤트 핸들러:
  handle 접두사 사용 (예: handleClick, handleSubmit)

• 상태 변수:
  조동사 포함 (예: isLoading, hasError, shouldUpdate)

• 내보내기:
  export const를 사용한 명명된 내보내기(named exports)를 기본으로 사용합니다.

  // 권장 방식
  export const UserCard = () => { ... }
  
  // 비권장
  export default function UserCard() { ... }

• 직접 모듈 import:
  관련 모듈들을 필요한 곳에서 각각 직접 import하여 사용합니다.

컴포넌트 파일 명명 규칙

• 페이지 컴포넌트:
  xxxPage.tsx (예: DashboardPage.tsx)
• 차트 컴포넌트:
  xxxChart.tsx (예: UserActivityChart.tsx)
• 목록 컴포넌트:
  xxxList.tsx (예: UserList.tsx)
• 아이템 컴포넌트:
  xxxItem.tsx (예: UserItem.tsx)
• 폼 컴포넌트:
  xxxForm.tsx (예: UserRegistrationForm.tsx)
• 모달 컴포넌트:
  xxxModal.tsx (예: ConfirmationModal.tsx)
• 레이아웃 컴포넌트:
  xxxLayout.tsx (예: DashboardLayout.tsx)
• 스타일 파일:
  컴포넌트와 동일한 이름의 SCSS 모듈 사용 (예: button.module.scss)

1.3 코드 작성 스타일

• 함수 선언 및 정의:
  • 순수 함수 및 유틸리티 함수:
    function 키워드를 사용하여 선언 (호이스팅 및 명시적 타입 선언 장점 활용)
  • 이벤트 핸들러 및 컴포넌트 내부 함수:
    const와 화살표 함수를 사용합니다 (예: const handleClick = () => { ... })
• 조건문:
  간단한 조건문은 중괄호 생략이 가능하나, 가독성이 떨어지면 명시적으로 사용합니다.
• 조기 반환:
  조건이 명확할 경우 조기 반환(early return)으로 중첩을 줄입니다.
• 중첩 지양:
  불필요한 중첩은 피하고, 복잡한 로직은 별도 함수로 분리합니다.
• 삼항 연산자:
  단순 조건에서만 사용하며, 복잡한 경우 if문을 사용합니다.
• 주석 및 문서화:
  복잡하거나 중요한 로직에는 주석을 추가하고, JSDoc 등을 통해 문서화합니다.

1.4 디렉토리 구조 기준

• 기본 원칙: 기능/도메인 기반 폴더 구조를 따릅니다. 관련 파일은 최대한 가까이 위치시켜 유지보수성을 높입니다.
• 페이지 기반 구조: 모든 페이지는 src/pages 하위의 독립 디렉토리로 구성되며, 각 디렉토리는 해당 페이지에 필요한 컴포넌트, 스타일, 훅 등을 포함할 수 있습니다.

✅ 권장 구조 예시

src/
├── api/                  # API 통신 관련 함수 및 타입
│   └── auth/             # (예시) 인증 관련 API
├── assets/               # 정적 리소스 (fonts, images, styles 등)
├── components/           # 공통/재사용 가능한 컴포넌트
│   ├── layout/           # 레이아웃 컴포넌트
│   └── ui/               # 기본 UI 컴포넌트 (shadcn 기반)
├── config/               # 환경 변수 및 설정값
├── hooks/                # 커스텀 훅
├── pages/                # 페이지 단위 컴포넌트
│   ├── home/             # 홈 페이지
│   │   ├── HomePage.tsx
│   │   └── components/   # 해당 페이지 전용 컴포넌트
│   └── login/
├── providers/            # Context API 기반 Provider들
├── router/               # 라우팅 관련 설정
├── store/                # Zustand 전역 상태 관리
│   └── slices/           # 상태 슬라이스
├── types/                # 전역 타입 정의
├── utils/                # 유틸리티 함수
├── App.tsx               # 애플리케이션 루트
├── main.tsx              # 애플리케이션 진입점
└── vite-env.d.ts         # Vite 환경 정의

📌 규칙 요약

• 공통 UI 컴포넌트: components/ui/ 하위에 위치 (shadcn 기준)
• 페이지 전용 컴포넌트: pages/xxx/components/ 내에 정의
• API 모듈: 도메인 단위로 구분 (api/auth/, api/user/ 등)
• 전역 상태: 도메인 단위로 Zustand 슬라이스 분리
• 정적 리소스: assets/ 하위에 이미지, 폰트, 전역 스타일 구분 저장

2. UI 및 상태 관리 가이

2.1 UI 및 스타일링 가이드

기본 UI 컴포넌트 라이브러리로 shadcn/ui를 사용합니다.

• 모든 버튼, 입력 필드, 다이얼로그, 토스트 등은 shadcn 컴포넌트를 우선 사용합니다.
• shadcn 컴포넌트는 @/components/ui/ 디렉토리에 자동 생성되며, 직접 수정하지 않습니다.
• 필요한 경우 shadcn 컴포넌트를 감싸는 래퍼(wrapper) 컴포넌트를 만들어 사용합니다.

2.1.1 UI 컴포넌트 및 스타일링

• 반응형 디자인:
  모바일 우선 접근 방식을 적용하여 다양한 기기에서 최적의 사용자 경험을 제공합니다.
• 스타일 관리:
  SCSS 모듈(CSS Modules)을 사용하여 컴포넌트별 스타일을 분리합니다.
• 인라인 스타일 금지:
  모든 스타일은 SCSS 모듈 또는 스타일링 라이브러리를 사용해 관리합니다.
• 스타일 분리:
  컴포넌트 파일과 스타일 파일을 분리하여 관리합니다 (예: Button.tsx, button.module.scss).

2.1.2 접근성 (a11y)

• 시맨틱 HTML:
  의미에 맞는 HTML 요소를 사용합니다.
• alt 텍스트:
  모든 이미지에 대해 적절한 대체 텍스트를 제공합니다.
• 키보드 네비게이션:
  Tab 키로 모든 상호작용 요소에 접근 가능하도록 구현합니다.
• ARIA 속성:
  필요한 경우 ARIA 역할 및 속성을 적용합니다.
• 포커스 관리:
  상호작용 요소에 명확한 포커스 스타일을 적용합니다.
• 자동 접근성 테스트:
  axe-core 등 도구를 사용하여 접근성 검사를 정기적으로 수행합니다.

2.2 상태 관리 및 데이터 패칭

2.2.1 상태 관리 전략

• 전역 상태:
  Zustand를 사용하여 전역 상태를 관리합니다.
• 로컬 상태:
  React hooks(useState, useReducer)를 활용하여 컴포넌트 내부 상태를 관리합니다.
• 스토어 분리:
  기능/도메인별로 별도의 Zustand 스토어를 생성합니다.
• 스토어 설계:
  평평한(flat) 구조를 유지하고, 스토어 간 의존성을 최소화합니다.

2.2.2 API 통신 및 데이터 관리

• 데이터 패칭:
  React Query(TanStack Query)를 사용하여 서버 상태를 관리합니다.
• API URL 관리:
  엔드포인트 URL은 상수 파일 또는 환경 변수로 관리합니다.
• 쿼리 키 관리:
  일관되고 명확한 쿼리 키를 정의해 캐싱 및 무효화 전략을 관리합니다.
• 에러 핸들링:
  모든 API 호출에 대해 적절한 에러 처리를 구현하며, 리트라이 및 취소 로직(예: AbortController)을 적용합니다.
• 쿼리 훅 위치:
  쿼리 훅은 /hooks/queries 디렉토리에 정의합니다.

2.2.3 비동기 작업 관리

• async/await 사용:
  Promise 체인 대신 async/await 문법을 사용해 가독성을 높입니다.
• 상태 관리:
  로딩, 성공, 에러 상태를 명확하게 관리합니다.
• 취소 메커니즘:
  필요한 경우 비동기 작업 취소(예: AbortController)를 구현합니다.
• 에러 처리:
  모든 비동기 함수에서 catch 구문을 포함해 에러를 처리합니다.

3. React 및 TypeScript 활용

3.1 컴포넌트 설계 원칙

• 단일 책임 원칙:
  컴포넌트는 한 가지 기능만 담당하도록 설계합니다.
• 컴포넌트 분해:
  복잡한 컴포넌트는 작은 단위로 분리하여 재사용성을 높입니다.
• 상태 관리 분리:
  UI 로직과 상태 관리 로직을 분리하여 테스트와 유지보수를 용이하게 합니다.
• 재사용성 고려:
  도메인 특화 로직과 일반 UI 컴포넌트를 분리해 재사용성을 극대화합니다.

3.2 TypeScript 활용 전략

• 타입/인터페이스 선택:
  객체 형태의 데이터는 인터페이스를 사용하고, 복잡한 타입 조합에는 타입 별칭(type)을 사용합니다.
• 열거형 대체:
  enum 대신 매핑된 객체(Map)를 사용해 가독성과 유연성을 확보합니다.
• Props 타입:
  컴포넌트의 props는 반드시 인터페이스로 정의합니다.
• 엄격한 타입 검사:
  tsconfig.json에서 strict: true를 활성화하여 타입 안정성을 보장합니다.
• 타입 추론 활용:
  불필요한 타입 어노테이션은 지양하고, 타입 추론을 적극 활용합니다.
• 유틸리티 타입 활용:
  Partial<T>, Pick<T, K>, Omit<T, K> 등 유틸리티 타입을 적절히 사용합니다.

3.3 성능 최적화 전략

• 메모이제이션:
  React.memo, useMemo, useCallback을 적절히 활용해 불필요한 리렌더링을 방지합니다.
• 컴포넌트 분리:
  렌더링 최적화를 위해 큰 컴포넌트를 작은 단위로 분리합니다.
• 동적 로딩:
  중요하지 않은 컴포넌트는 지연 로딩(lazy loading)을 적용합니다.
• 이미지 최적화:
  WebP 형식 사용, 이미지 크기 지정, 지연 로딩 구현 등으로 성능을 향상시킵니다.
• 리렌더링 최소화:
  불필요한 상태 업데이트를 방지하고, 최적의 렌더링 전략을 사용합니다.

4. 품질 관리 및 협업

4.1 테스트 전략

• 테스트 도구:
  Vitest와 React Testing Library를 사용하여 단위 테스트 및 통합 테스트를 수행합니다.
• 테스트 위치:
  테스트 파일은 구현 파일과 동일한 디렉토리에 두거나 별도의 __tests__ 디렉토리를 사용합니다.
• 테스트 우선순위:
  스냅샷 테스트보다 동작 테스트에 중점을 두고, 핵심 로직에 대해 충분한 테스트 커버리지를 확보합니다.
• 자동화:
  CI/CD 파이프라인에 테스트 자동화를 포함시켜, 코드 변경 시 지속적으로 검증합니다.

4.2 오류 처리 및 로깅

• 폴백 UI:
  예상 가능한 오류 상황에 대해 대체 UI를 구현합니다.
• 에러 캐치:
  Promise 기반 코드와 async/await 함수 모두에서 catch 구문을 포함하여 에러를 처리합니다.
• 사용자 피드백:
  사용자에게 적절한 오류 메시지를 제공하며, UX를 해치지 않는 방식으로 처리합니다.
• 로깅:
  개발 및 운영 환경에서 상세 오류 로깅을 구현해 문제 해결에 도움을 줍니다.

4.3 의존성 관리 및 업데이트

• 번들 크기:
  라이브러리 추가 시 번들 크기에 미치는 영향을 고려합니다.
• 정기 업데이트:
  보안 및 안정성 문제를 방지하기 위해 의존성을 정기적으로 업데이트합니다.
• 버전 관리:
  주요 라이브러리 버전 변경 시 신중한 검토와 테스트를 거칩니다.
• 라이브러리 선택:
  활발히 유지보수되고 문서화가 잘 된 라이브러리를 선택합니다.

이 가이드라인은 팀 내에서 일관된 코드 스타일과 모범 사례를 공유하기 위해 작성되었으며, 프로젝트의 특성이나 새로운 기술 도입에 따라 주기적으로 업데이트할 수 있습니다.