프론트엔드 컨벤션
Next.js 16 + React 19 + TanStack Query v5 + FSD 아키텍처에서 **"좋은 코드이면서 일관된 코드"**를 생성하기 위한 컨벤션.
이 스킬을 사용해야 하는 경우
- 새로운 entity, feature, widget을 만들 때
- CRUD 폼이나 데이터 테이블을 구현할 때
- 기존 코드를 리팩토링할 때
- 프로젝트가 컨벤션을 준수하는지 검증할 때
- API layer, state management, error handling 패턴을 적용할 때
기술 스택
- Next.js 16.1.6 (App Router) + React 19.2.3 + TypeScript 5.9.2
- @tanstack/react-query ^5 + @tanstack/react-table ^8.21.3
- react-hook-form ^7.71.2 + zod ^3.25.76
- nuqs ^2.8.9 (URL state)
- Tailwind CSS ^4 + shadcn/ui (radix-nova) + sonner ^2.0.7 (toast)
- Turborepo ^2.8.12 + pnpm 9.0+ (내부:
@workspace/ui,@workspace/api)
규칙 카테고리
11개 카테고리, 67개 규칙. 작업에 맞는 파일을 참조:
| 영역 | 파일 | 언제 참조 |
|---|---|---|
| 아키텍처 | rules/architecture.md | FSD 레이어, import 방향, entity slice, barrel export |
| Next.js 패턴 | rules/nextjs-patterns.md | Page thin shell, Providers, 'use client', 특수 파일 |
| 코드 품질 | rules/code-quality.md | Dynamic import, conditional render, early return, forwardRef |
| 쿼리 | rules/queries.md | queryOptions factory, query keys, staleTime, prefetch, useQueries |
| 뮤테이션 | rules/mutations.md | invalidate, useApiMutation, optimistic |
| API 레이어 | rules/api-layer.md | API 객체, 응답 타입, SSR prefetch |
| 폼 | rules/forms.md | zod 스키마, useForm, FormDialog, edit 패턴 |
| 테이블 | rules/tables.md | DataTable, columns, server-side pagination |
| 상태 관리 | rules/state-management.md | nuqs, useState, 전역 상태 금지 |
| 에러 처리 | rules/error-handling.md | ApiError, toast, Error Boundary |
| 네이밍 | rules/naming.md | 파일/훅/타입/상수 네이밍 |
전체 인덱스는 INDEX.md 참조.
엄격도 수준
각 규칙은 세 가지 엄격도 중 하나:
| 레벨 | 의미 | AI 행동 |
|---|---|---|
| 🚫 MUST | 절대 위반 불가 | 항상 이 패턴을 따른다 |
| ⚠️ SHOULD | 특별한 이유 없으면 따름 | 기본 적용, 예외 시 주석으로 이유 명시 |
| ✅ MAY | 권장하지만 유연 | 상황에 맞게 판단 |
검증 워크플로
"이 프로젝트를 컨벤션 기준으로 검증해라" 요청 시 다음 순서로 수행:
- Tech stack 확인 — package.json에서 Next.js/React/TanStack Query 버전 확인
- FSD 구조 확인 (PS-01~05) — apps/*/entities, features, widgets, shared 존재 여부
- Import 방향 검증 (PS-02) — entity가 features/widgets를 import하는 곳 검색
- Entity 완전성 (PS-03) — 각 entity에 api.ts, queries.ts, hooks.ts, types.ts, index.ts 존재 여부
- Mutation 패턴 (DF-06, DF-07) — useApiMutation 사용률, raw useMutation 위반 검색
- 폼 패턴 (FM-01~07) — zod schema 위치, useForm+zodResolver, form hook 추출 여부
- 테이블 패턴 (TB-01~05) — useReactTable instance 방식, 서버사이드 manual 모드
- 상태 관리 (SM-01) — Context/zustand 사용 여부 (금지)
- 파일명 규칙 (NM-01) — kebab-case 준수율
출력 형식:
- 위반 목록 (규칙 ID +
file:line+ 수정 제안) - 준수율 요약 (카테고리별)
- 우선순위별 권고 (🚫 먼저, ⚠️ 다음)
작업별 빠른 시작
새 entity 추가: architecture → api-layer → queries → mutations → naming CRUD 폼 구현: forms → mutations (DF-06, DF-07) → naming 테이블 페이지 구현: tables → state-management → queries 새 페이지/라우트 추가: nextjs-patterns → architecture (PS-02, PS-05) 에러 처리: error-handling 성능 최적화: code-quality → queries (DF-10~12) 기존 코드 리팩토링: 해당 영역의 규칙 파일 전체
참고 자료
- Anthropic Skill 작성 모범 사례: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- TanStack Query v5 문서: https://tanstack.com/query/latest
- Feature-Sliced Design: https://feature-sliced.design