project-scaffolder

Project Scaffolder

프론트엔드 프로젝트의 구조를 분석하고, AI 에이전트(Claude, Cursor, Windsurf 등)가 활용할 수 있는 아키텍처 컨텍스트 문서를 생성한다.

목적

1. 프로젝트 초기 구조 설정 - 일관된 폴더/파일 구조 수립
2. 아키텍처 문서화 - AI 에이전트의 core memory/context로 활용
3. 팀 온보딩 - 새 팀원이 프로젝트 구조 빠르게 파악
4. 일관성 유지 - 코딩 규칙과 패턴 표준화

워크플로우

1. 프로젝트 스택 파악

사용자에게 확인할 사항:

• 프레임워크: Next.js, React, Vue, Nuxt 등
• 백엔드/BaaS: Supabase, Firebase, Prisma, 자체 API 등
• 상태관리: TanStack Query, Zustand, Redux, Jotai 등
• UI 라이브러리: shadcn/ui, MUI, Chakra 등
• 기존 프로젝트 여부: 기존 구조 분석 vs 새로 생성

2. 기존 프로젝트 분석 (해당 시)

분석 대상:

# 폴더 구조 파악
find . -type d -name "node_modules" -prune -o -type d -print | head -50

# 핵심 파일 확인
ls -la lib/ app/ components/ hooks/ types/ spec/

3. 아키텍처 문서 생성

spec/PROJECT_ARCHITECTURE.md 파일 생성:

• 3-Layer 아키텍처 정의
• 폴더 구조 및 역할
• 코딩 규칙
• 외부 연동 패턴

4. CLAUDE.md / .cursorrules 업데이트

AI 에이전트 컨텍스트 파일에 아키텍처 규칙 추가.

---

핵심 아키텍처 패턴

3-Layer Separation (필수)

┌─────────────────────────────────────────────┐
│ 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