이 문서는 AI 에이전트가 이 코드베이스에서 작업할 때 참고하는 지침서입니다.
- 모든 PR 제목, PR 설명, 코드 리뷰 코멘트는 반드시 한국어로 작성한다.
- 커밋 메시지 본문도 한국어로 작성한다. (prefix는 영어 허용:
feat:,fix:등) - 코드 내 주석도 한국어로 작성한다.
Playhive(플레이하이브) 는 축구, 야구, e스포츠 등 함께 즐기는 클린 스포츠 커뮤니티 애플리케이션입니다. 사용자들은 일반 사용자 라우트에서 다양한 소식과 정보를 주고 받으며, 관리자 권한으로 대시보드를 관리할 수 있는 하이브리드 어플리케이션(사용자 + 관리자 웹 뷰)입니다.
- 라이브 URL: https://playhive-web.vercel.app/
- 목적: 클린 스포츠 커뮤니티 서비스
| 분류 | 기술 |
|---|---|
| 프레임워크 | Next.js 15 (App Router) |
| 언어 | TypeScript, React 19 |
| 스타일링 | Tailwind CSS v3 |
| UI 라이브러리 | HeroUI (@heroui/react 등), Framer Motion, Lucide React |
| 상태 관리 | Zustand (클라이언트 상태) |
| 데이터 페칭 | Tanstack React Query v5 (서버 상태 관리), Axios |
| 에디터 | Tiptap |
| 배포 | AWS Amplify |
| 코드 포맷터 | Prettier + prettier-plugin-tailwindcss |
| 린터 | ESLint (추가적인 strict 룰 일부 비활성화) |
이 프로젝트는 Next.js App Router의 디렉토리 라우팅과 함께 용도에 따라 책임을 분리한 폴더 구조를 사용합니다.
src/
├── app/ # Next.js App Router (라우팅, 레이아웃, 공통 컴포넌트)
│ ├── (route)/ # 일반 사용자 대상 화면의 페이지 그룹 (도메인/라우트 단위 분리)
│ ├── (admin)/ # 어드민 전용 대시보드 및 페이지 그룹
│ ├── _components/ # 애플리케이션 전역에서 사용되는 공용 UI 컴포넌트 (`_gnb` 등)
│ ├── _constants/ # 앱 전역 상수
│ ├── api/ # API Route (Next.js 백엔드 엔드포인트)
│ ├── layout.tsx # 최상위 루트 레이아웃 (글로벌 컨텍스트 설정)
│ └── globals.css # 전역 스타일시트
│
├── _hooks/ # React Query 커스텀 훅 및 공통 커스텀 훅 모음
├── _types/ # 전역에서 사용되는 공통 TypeScript 인터페이스/타입
├── lib/ # 외부 라이브러리 설정, 유틸리티 제공 (Google Analytics 설정 등)
├── services/ # 비즈니스 로직 및 외부/내부 API 호출(Axios 등) 계층 함수 모음
└── utils/ # 상태를 갖지 않는 순수 유틸리티(Helper) 함수들
- 비즈니스 로직 분리: 컴포넌트 내부에서 비대한 API 로직을 직접 구현하지 않고,
services/폴더에 엔드포인트를 구현한 뒤,_hooks/폴더 내에 React Query 기반 커스텀 훅을 만들어 컴포넌트에 연결합니다. - 컴포넌트 도메인 캡슐화: 특정 페이지나 도메인(예: 공지사항, 어드민 대시보드)에만 사용되는 구성 요소는
app/(route)/.../_components혹은app/(admin)/.../_components같은 지역_components폴더에 위치시켜 응집도를 높입니다. - 전역으로 사용되는 공통 UI만
src/app/_components최상위 공통 폴더로 이동시킵니다.
- 서버 상태: 외부 데이터를 불러오거나 뮤테이션을 진행할 땐 반드시
@tanstack/react-query의 훅을 사용해 캐싱/무효화 로직을 제어합니다. - 클라이언트 상태: 전역적으로 공유되어야 하는 클라이언트 측 상태(예: 모달 온/오프, UI 뷰 전환용 임시 상태 등)가 필요할 때엔
zustand를 활용하여 처리합니다.
- 기본 UI 요소나 뷰의 구축 시 HeroUI 컴포넌트를 우선적으로 활용하며 부족한 디테일, 여백, 커스텀 스타일링은 Tailwind CSS의 유틸리티 클래스로 해결합니다.
- 꼭 필요한 경우가 아니면 JS 인라인 객체
style={{...}}을 사용하지 않습니다.
<img>태그 사용 제한이.eslintrc.json에 의해 임시로 해제되어 있으나, Next.js의 성능 최적화를 고려해 가급적<Image>컴포넌트를 사용합니다. 정적으로 확정된 도메인 외 새로운 외부 이미지를 가져와야 할 시next.config.ts의images.domains또는images.remotePatterns에 등록하여야 합니다.- Next.js의
<Image>와unoptimized속성 등을 서비스 제약에 맞게 적절히 사용합니다.
- ESLint에서
no-explicit-any등이 임시로 꺼져 있더라도, 추후 타입 안정성을 확보할 수 있도록 신규 코드는any대신 명확하게 추론되거나interface/type으로 지정된 정적 타입을 최대한 사용합니다. - 객체 형태에는
interface, 유니온 및 별칭에는type을 사용합니다. - 사용되지 않는 변수(
no-unused-vars)나 훅 디펜던시(exhaustive-deps) 경고가 해제되어 있지만, 이로 인한 사이드 이펙트나 메모리 누수가 생기지 않도록 논리적으로 올바른 코드를 작성합니다.
- 소스 코드에 환경 변수나 시크릿을 절대 하드코딩하지 않습니다. (
NEXT_PUBLIC_...규칙 사용)
# 개발 서버 시작
npm run dev
# 프로덕션 빌드
npm run build
# 프로덕션 서버 실행
npm start
# ESLint 실행
npm run lint| 라우트 | 경로 그룹 | 설명 |
|---|---|---|
| 일반 커뮤니티/뉴스 | (route)/ |
유저들이 뉴스를 보거나 게시판을 사용하기 위한 서비스 화면 |
| 관리자 계정 라우팅 | (admin)/ |
어드민 권한 사용자만 볼 수 있는 백오피스 / 대시보드 화면 |
- 프로덕션 코드에 불필요한
console.log남기지 않기 (디버깅 완료 후 제거) - 컴포넌트 내부에 거대한 비동기 API 로직 직접 작성 금지 (항상
_hooks/services레이어 활용) - Tailwind 클래스 수동 재정렬 금지 (
prettier-plugin-tailwindcss가 규격에 맞게 자동 처리) - 환경 변수 값 파일 내 하드코딩 금지
- PR 설명, 코멘트, 커밋 메시지의 본문을 영어로 작성 금지
- 프로덕션 배포 전에 구글/네이버 색인 및 크롤러 수집을 위한 시맨틱 마크업을 고려합니다.
layout.tsx와 개별 페이지 수준에서metadata객체를 올바르게 export하여 Open Graph (OG) Tag, Description 을 정의해야 합니다.
feat: 새로운 기능 추가
fix: 버그 수정
style: 스타일/포맷 변경 (기능 변경 없음)
refactor: 코드 리팩토링
docs: 문서 수정
chore: 빌드 설정, 패키지 업데이트 등
커밋 메시지 예시:
feat: 포스트 검색 필터링 기능 추가
fix: 어드민 대시보드에서 탈퇴 사유 리스트 렌더링 에러 해결