프론트엔드 프로젝트 구조를 분석하고 정리하여 AI 에이전트가 활용할 수 있는 컨텍스트 문서를 생성하는 스킬. "프로젝트 구조 잡아줘", "폴더 구조 정리해줘", "아키텍처 문서화해줘", "프로젝트 초기 설정해줘" 등의 요청에 트리거된다. Next.js, Supabase, React 등 다양한 프론트엔드 스택에서 범용적으로 사용 가능하다.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
references/architecture-patterns.mdreferences/folder-structure-template.md프론트엔드 프로젝트의 구조를 분석하고, AI 에이전트(Claude, Cursor, Windsurf 등)가 활용할 수 있는 아키텍처 컨텍스트 문서를 생성한다.
사용자에게 확인할 사항:
분석 대상:
# 폴더 구조 파악
find . -type d -name "node_modules" -prune -o -type d -print | head -50
# 핵심 파일 확인
ls -la lib/ app/ components/ hooks/ types/ spec/
spec/PROJECT_ARCHITECTURE.md 파일 생성:
AI 에이전트 컨텍스트 파일에 아키텍처 규칙 추가.
┌─────────────────────────────────────────────┐
│ Component Layer (UI Logic) │
│ - Import hooks from /hooks/ │
│ - NO database client, NO inline queries │
└─────────────────┬───────────────────────────┘
│ imports
┌─────────────────▼───────────────────────────┐
│ Hook Layer (Query Management) │
│ - TanStack Query hooks │
│ - Import service functions │
│ - NO database client │
└─────────────────┬───────────────────────────┘
│ imports
┌─────────────────▼───────────────────────────┐
│ Service Layer (Data Access) │
│ - Pure functions with database queries │
│ - File: /lib/services/{domain}.ts │
│ - ONLY place for database client │
└─────────────────────────────────────────────┘
project/
├── app/ # Next.js App Router pages
│ ├── api/ # API routes (외부 연동만)
│ └── [feature]/ # Feature pages
│
├── components/ # React Components
│ ├── ui/ # Base UI (shadcn/ui 등)
│ └── [feature]/ # Feature-specific components
│
├── hooks/ # Custom React Hooks
│ └── use-[domain]-query.ts # TanStack Query hooks
│
├── lib/ # Core Business Logic
│ ├── services/ # Data Access Layer (DAL)
│ ├── supabase/ # Database client (Supabase 사용 시)
│ ├── api/ # External API clients
│ ├── auth/ # Authentication logic
│ ├── utils/ # Utility functions
│ ├── constants.ts # Global constants
│ └── menu-configs.ts # Navigation config
│
├── types/ # TypeScript Definitions
│ ├── database.types.ts # Auto-generated DB types
│ ├── models.ts # Domain model types
│ └── enums.ts # Enum definitions
│
├── stores/ # Client State (Zustand)
├── providers/ # React Context Providers
│
├── spec/ # Specifications & Docs
│ ├── PROJECT_ARCHITECTURE.md
│ ├── database-schema.md
│ └── detailed-features/
│
├── documentations/ # External API Docs
│ ├── [api-name]/ # Per-API documentation
│ └── ...
│
└── supabase/ # Supabase Config (해당 시)
└── migrations/ # Database migrations
lib/services/)역할: 모든 데이터베이스 쿼리를 캡슐화하는 Data Access Layer
파일 네이밍: {domain}-service.ts 또는 {table}.ts
패턴:
// lib/services/students.ts
import { createClient } from '@/lib/supabase/client'
import type { StudentRow, StudentInsert } from '@/types/models'
export async function getStudents(centerId: number): Promise<StudentRow[]> {
const supabase = createClient()
const { data, error } = await supabase
.from('students')
.select('*')
.eq('center_id', centerId)
if (error) throw error
return data
}
export async function createStudent(data: StudentInsert): Promise<StudentRow> {
// ...
}
규칙:
Promise<T> 반환/types/models.ts에서 importhooks/)역할: TanStack Query로 서버 상태 관리
파일 네이밍: use-{domain}-query.ts
패턴:
// hooks/use-students-query.ts
import { useQuery, useMutation } from '@tanstack/react-query'
import { getStudents, createStudent } from '@/lib/services/students'
export function useStudentsQuery(centerId: number) {
return useQuery({
queryKey: ['students', centerId],
queryFn: () => getStudents(centerId),
enabled: !!centerId,
})
}
export function useCreateStudentMutation() {
return useMutation({
mutationFn: createStudent,
// ...
})
}
규칙:
components/, app/)역할: UI 렌더링 및 사용자 인터랙션
패턴:
// components/students/student-list.tsx
import { useStudentsQuery } from '@/hooks/use-students-query'
export function StudentList({ centerId }: { centerId: number }) {
const { data: students, isLoading } = useStudentsQuery(centerId)
// UI 로직만
}
규칙:
lib/constants.ts)역할: 비즈니스 로직 상수의 Single Source of Truth
패턴:
// lib/constants.ts
export const CLASS_TIME = {
MIN_HOUR: 14,
MAX_HOUR: 21,
MIN_TIME: '14:00',
MAX_TIME: '21:00',
} as const
export const PAGINATION = {
DEFAULT_PAGE_SIZE: 20,
PAGE_SIZE_OPTIONS: [10, 20, 50, 100],
} as const
lib/menu-configs.ts)역할: 네비게이션 메뉴의 중앙 집중 관리
패턴:
// lib/menu-configs.ts
export function getCenterMenuData(): MenuData {
return {
navMain: [
{ title: "대시보드", url: "/center/dashboard", icon: Home },
{ title: "학생 관리", url: "/center/students", icon: Users },
// ...
]
}
}
documentations/)역할: 외부 API/라이브러리 문서 중앙 저장
구조:
documentations/
├── alim-talk/ # 카카오 알림톡
├── fullcalendar/ # FullCalendar 라이브러리
├── onedrive/ # Microsoft Graph API
├── openai/ # OpenAI API
└── shadcn/ # shadcn/ui 커스터마이징
spec/)역할: 시스템 명세 및 설계 문서
필수 파일:
PROJECT_ARCHITECTURE.md - 프로젝트 아키텍처 개요database-schema.md - DB 스키마 문서detailed-features/ - 기능별 상세 명세spec/PROJECT_ARCHITECTURE.md프로젝트 아키텍처 전체 문서:
AI 에이전트용 규칙 추가:
## Data Layer Architecture - SOLID Principles (MANDATORY)
CRITICAL: This project follows strict 3-layer architecture.
- Component Layer: hooks에서만 데이터 import
- Hook Layer: service 함수만 import
- Service Layer: DB 클라이언트 사용 (유일한 장소)
### 금지 패턴
- ❌ Component에서 DB 클라이언트 직접 사용
- ❌ Hook에서 인라인 쿼리 정의
- ❌ Service 외부에서 Supabase/Prisma 호출
lib/supabase/
├── client.ts # Browser client
├── server.ts # Server component client
├── middleware.ts # Auth middleware
└── service-role.ts # Admin client (서버 전용)
lib/firebase/
├── client.ts # Firebase app init
├── auth.ts # Auth functions
├── firestore.ts # Firestore queries
└── storage.ts # Storage functions
lib/prisma/
├── client.ts # Prisma client singleton
└── ...
prisma/
├── schema.prisma # Database schema
└── migrations/ # Migration files
상세 패턴은 references/ 폴더 참조:
architecture-patterns.md - 아키텍처 패턴 상세folder-structure-template.md - 폴더 구조 템플릿