chore: 프로젝트 초기 세팅 추가 (Orval, commitlint, Gemini Code Assist, CodeRabbit)

.coderabbit.yaml

@@ -0,0 +1,150 @@
+# CodeRabbit 설정
+# 공식 문서: https://docs.coderabbit.ai/reference/configuration
+# 기술 스택: Next.js 16 + React 19 + TypeScript + Tailwind CSS
+
+# =============================================================================
+# 일반 설정
+# =============================================================================
+
+# 리뷰 언어 설정 (ISO 코드)
+language: "ko-KR"
+
+# 얼리 액세스 기능 (실험적 기능 사용 여부)
+early_access: false
+
+# =============================================================================
+# 코드 리뷰 설정
+# =============================================================================
+reviews:
+  # 리뷰 톤 설정
+  # - "chill": 부드럽고 친절한 톤 (팀 프로젝트 권장)
+  # - "assertive": 단호하고 직접적인 톤
+  profile: "chill"
+
+  # PR 변경 요청 워크플로우 활성화
+  # true: 심각한 문제 발견 시 "Request Changes" 상태로 전환
+  request_changes_workflow: false
+
+  # PR 설명에 고수준 변경 요약 자동 생성
+  high_level_summary: true
+
+  # 워크스루(Walkthrough) 섹션 접기
+  collapse_walkthrough: true
+
+  # 변경된 파일 목록 요약 표시
+  changed_files_summary: true
+
+  # 시퀀스 다이어그램 생성 (코드 흐름 시각화)
+  sequence_diagrams: true
+
+  # 코드 리뷰 난이도 추정 표시
+  estimate_code_review_effort: true
+
+  # 관련 이슈 자동 분석
+  assess_linked_issues: true
+
+  # 관련 PR 표시
+  related_prs: true
+
+  # 라벨 자동 추천
+  suggested_labels: true
+
+  # 리뷰어 자동 추천
+  suggested_reviewers: true
+
+  # 시(poem) 생성 비활성화 (깔끔한 리뷰를 위해)
+  poem: false
+
+  # 리뷰 진행 중 포춘 쿠키 메시지 표시
+  in_progress_fortune: false
+
+  # ---------------------------------------------------------------------------
+  # 무시할 파일 패턴 (glob 형식, "!"는 제외 의미)
+  # ---------------------------------------------------------------------------
+  path_filters:
+    - "!**/*.lock"
+    - "!**/pnpm-lock.yaml"
+    - "!**/node_modules/**"
+    - "!**/dist/**"
+    - "!**/.next/**"
+    - "!**/coverage/**"
+    - "!**/*.min.js"
+    - "!**/*.min.css"
+
+  # ---------------------------------------------------------------------------
+  # 파일별 커스텀 리뷰 지침
+  # ---------------------------------------------------------------------------
+  path_instructions:
+    - path: "src/components/**"
+      instructions: |
+        - React 컴포넌트는 함수형으로만 작성되었는지 확인
+        - Props 타입이 명확하게 정의되었는지 확인
+        - 접근성(a11y) 속성이 적절히 사용되었는지 확인
+
+    - path: "src/app/**"
+      instructions: |
+        - Next.js App Router 규칙을 따르는지 확인
+        - 서버/클라이언트 컴포넌트 분리가 적절한지 확인
+        - 메타데이터가 올바르게 설정되었는지 확인
+
+    - path: "src/hooks/**"
+      instructions: |
+        - 커스텀 훅이 use 접두사를 사용하는지 확인
+        - 의존성 배열이 올바르게 설정되었는지 확인
+
+    - path: "src/lib/**"
+      instructions: |
+        - 유틸리티 함수가 순수 함수인지 확인
+        - 타입이 명확하게 정의되었는지 확인
+
+  # ---------------------------------------------------------------------------
+  # 자동 리뷰 설정
+  # ---------------------------------------------------------------------------
+  auto_review:
+    # 자동 리뷰 비활성화 (Gemini Code Assist만 사용)
+    enabled: false
+
+    # 드래프트 PR 자동 리뷰 비활성화
+    drafts: false
+
+    # 이 키워드가 PR 제목에 있으면 리뷰 건너뛰기
+    ignore_title_keywords:
+      - "WIP"
+      - "DO NOT MERGE"
+      - "DRAFT"
+
+  # ---------------------------------------------------------------------------
+  # 코드 분석 도구 설정 (기술 스택에 맞게 구성)
+  # ---------------------------------------------------------------------------
+  tools:
+    # Biome (JavaScript/TypeScript 린터)
+    biome:
+      enabled: true
+
+    # Markdownlint (마크다운 파일 검사)
+    markdownlint:
+      enabled: true
+
+    # LanguageTool (문법/철자 검사)
+    languagetool:
+      enabled: false # 한국어 지원 제한으로 비활성화
+
+# =============================================================================
+# 채팅 설정 (PR 코멘트에서 @coderabbitai 멘션 시)
+# =============================================================================
+chat:
+  # 자동 응답 활성화
+  auto_reply: true
+
+# =============================================================================
+# 코드 생성 설정 (PR 코멘트에서 요청 시 동작)
+# =============================================================================
+code_generation:
+  # Docstring 자동 생성 설정
+  docstrings:
+    language: "ko-KR"
+    path_instructions: []
+
+  # 유닛 테스트 자동 생성 설정
+  unit_tests:
+    path_instructions: []

.gemini/config.yml

@@ -0,0 +1,32 @@
+# Gemini Code Assist 설정
+# https://developers.google.com/gemini-code-assist/docs/customize-gemini-behavior-github
+
+# 재미 기능 (PR 요약에 시 추가 등)
+have_fun: false
+
+# 무시할 파일 패턴 (glob 패턴)
+ignore_patterns:
+  - "**/*.lock"
+  - "**/node_modules/**"
+  - "**/dist/**"
+  - "**/.next/**"
+
+# 코드 리뷰 설정
+code_review:
+  # 코드 리뷰 비활성화 여부
+  disable: false
+  # 리뷰 코멘트 심각도 임계값 (LOW, MEDIUM, HIGH, CRITICAL)
+  comment_severity_threshold: MEDIUM
+  # 최대 리뷰 코멘트 수 (-1: 무제한)
+  max_review_comments: -1
+
+# PR 열림 이벤트 설정
+pull_request_opened:
+  # 도움말 메시지 표시
+  help: false
+  # PR 요약 자동 생성
+  summary: true
+  # 자동 코드 리뷰
+  code_review: true
+  # 드래프트 PR에도 적용
+  include_drafts: false

.gemini/styleguide.md

@@ -0,0 +1,91 @@
+# GAK 프로젝트 코드 스타일 가이드
+
+이 문서는 Gemini Code Assist가 코드 리뷰 시 참고하는 팀 컨벤션입니다.
+**모든 리뷰 코멘트는 한국어로 작성해주세요.**
+
+---
+
+## 일반 원칙
+
+- **가독성**: 모든 팀원이 쉽게 이해할 수 있는 코드를 작성합니다.
+- **일관성**: 프로젝트 전체에서 동일한 스타일을 유지합니다.
+- **단순성**: 복잡한 해결책보다 단순한 해결책을 선호합니다.
+
+---
+
+## TypeScript / JavaScript
+
+### 네이밍 컨벤션
+
+- **변수/함수**: camelCase (예: `userName`, `fetchUserData`)
+- **상수**: UPPER_SNAKE_CASE (예: `MAX_RETRY_COUNT`, `API_BASE_URL`)
+- **컴포넌트/클래스**: PascalCase (예: `UserProfile`, `PaymentProcessor`)
+- **타입/인터페이스**: PascalCase (예: `UserResponse`, `ApiError`)
+
+### 코드 스타일
+
+- `any` 타입 사용을 지양합니다. 구체적인 타입을 명시하세요.
+- 중첩 깊이는 최대 2-3 단계로 유지합니다.
+- Early Return 패턴을 사용하여 `else`를 최소화합니다.
+- `console.log`는 커밋하지 않습니다.
+
+```typescript
+// ✅ Good - Early Return
+function processUser(user: User | null) {
+  if (!user) return null;
+  if (!user.isActive) return null;
+  return user.name;
+}
+
+// ❌ Bad - Deep Nesting
+function processUser(user: User | null) {
+  if (user) {
+    if (user.isActive) {
+      return user.name;
+    }
+  }
+  return null;
+}
+```
+
+---
+
+## React / Next.js
+
+### 컴포넌트 규칙
+
+- 컴포넌트는 함수형으로만 작성합니다.
+- 서버 컴포넌트와 클라이언트 컴포넌트를 명확히 분리합니다.
+- 클라이언트 컴포넌트는 파일 최상단에 `"use client"` 지시어를 추가합니다.
+- 한 컴포넌트는 한 가지 역할만 수행합니다. (SRP)
+
+### 데이터 페칭
+
+- 클라이언트에서 API 호출은 React Query를 통해 수행합니다.
+- 서버 컴포넌트에서는 직접 `fetch`를 사용합니다.
+
+### Hooks
+
+- 커스텀 훅은 `use` 접두사를 사용합니다. (예: `useAuth`, `useFetchUser`)
+- 훅에서 복잡한 로직을 추출하여 컴포넌트를 깔끔하게 유지합니다.
+
+---
+
+## 에러 처리
+
+- 구체적인 에러 타입을 사용합니다. (`Error`보다 `ApiError`, `ValidationError`)
+- 사용자에게 친화적인 에러 메시지를 제공합니다.
+- `try...catch` 블록으로 에러를 적절히 처리합니다.
+
+---
+
+## 주석
+
+- 주석은 한국어로 작성합니다.
+- "왜(why)" 그렇게 했는지 설명합니다. "무엇(what)"은 코드가 설명합니다.
+- TODO 주석에는 담당자와 이유를 명시합니다.
+
+```typescript
+// TODO(kyungwhan): 백엔드 API 완성 후 실제 엔드포인트로 변경
+const API_URL = "/api/mock/users";
+```

.husky/commit-msg

@@ -1,45 +1,2 @@
 #!/bin/sh
-
-# =============================================================================
-# 커밋 메시지 컨벤션 검사 스크립트
-# =============================================================================
-# 
-# [추후 논의] commitlint 도입 검토
-# - 현재: Shell script로 기본 검증 (추가 패키지 없음)
-# - 대안: @commitlint/cli + @commitlint/config-conventional
-#
-# =============================================================================
-
-commit_msg_file=$1
-commit_msg=$(cat "$commit_msg_file")
-
-# 허용되는 커밋 타입 정의
-pattern="^(feat|fix|docs|style|refactor|test|chore|design|comment|rename|remove|hotfix)(\!)?\: .+$"
-
-if ! echo "$commit_msg" | grep -qE "$pattern"; then
-  echo ""
-  echo "❌ 커밋 메시지가 컨벤션에 맞지 않습니다."
-  echo ""
-  echo "올바른 형식: <type>: <subject>"
-  echo ""
-  echo "허용되는 타입:"
-  echo "  feat     - 새로운 기능 추가"
-  echo "  fix      - 버그 수정"
-  echo "  docs     - 문서 수정"
-  echo "  style    - 코드 formatting (코드 변경 없음)"
-  echo "  refactor - 코드 리팩토링"
-  echo "  test     - 테스트 코드"
-  echo "  chore    - 기타 수정"
-  echo "  design   - UI 디자인 변경"
-  echo "  comment  - 주석 추가/변경"
-  echo "  rename   - 파일/폴더 이름 변경"
-  echo "  remove   - 파일 삭제"
-  echo "  hotfix   - 긴급 버그 수정"
-  echo ""
-  echo "예시:"
-  echo "  feat: 로그인 기능 추가"
-  echo "  fix: 버튼 클릭 오류 수정"
-  echo "  feat!: API 응답 구조 변경 (BREAKING CHANGE)"
-  echo ""
-  exit 1
-fi
+pnpm exec commitlint --edit $1

commitlint.config.js

@@ -0,0 +1,27 @@
+module.exports = {
+  extends: ["@commitlint/config-conventional"],
+  rules: {
+    "type-enum": [
+      2,
+      "always",
+      [
+        "feat",
+        "fix",
+        "docs",
+        "style",
+        "refactor",
+        "test",
+        "chore",
+        "design",
+        "comment",
+        "rename",
+        "remove",
+        "hotfix",
+      ],
+    ],
+    "subject-empty": [2, "never"],
+    "type-empty": [2, "never"],
+    // 한국어 커밋 메시지 및 고유명사 사용을 위해 비활성화
+    "subject-case": [0],
+  },
+};

orval.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig } from "orval";
+
+export default defineConfig({
+  gak: {
+    input: {
+      // TODO: 백엔드에서 제공하는 Swagger/OpenAPI 명세 URL 또는 파일 경로로 변경
+      target: "./swagger.json",
+    },
+    output: {
+      mode: "tags-split",
+      target: "./src/api/generated",
+      schemas: "./src/api/generated/models",
+      client: "react-query",
+      override: {
+        mutator: {
+          path: "./src/lib/api-client.ts",
+          name: "customInstance",
+        },
+        query: {
+          useQuery: true,
+          useMutation: true,
+        },
+      },
+    },
+  },
+});