timsquad 2.0.0 → 3.3.0

package/templates/base/skills/database/prisma/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: prisma
+description: Prisma ORM 개발 가이드라인
+version: "1.0.0"
+tags: [prisma, orm, database]
+user-invocable: false
+---
+
+# Prisma ORM Guidelines
+
+## 철학
+- Schema as SSOT — 스키마가 진실의 원천
+- Type Safety — 자동 생성 타입 활용
+- Migration First — 스키마 변경은 마이그레이션으로
+
+## 마이그레이션 워크플로우
+
+| 명령어 | 용도 |
+|--------|------|
+| `npx prisma migrate dev --name {name}` | 개발 환경 마이그레이션 |
+| `npx prisma migrate deploy` | 프로덕션 적용 |
+| `npx prisma migrate reset` | DB 초기화 + 재적용 |
+| `npx prisma db push` | 빠른 프로토타이핑 (마이그레이션 없이) |
+| `npx prisma generate` | 클라이언트 재생성 |
+
+**순서**: schema.prisma 수정 → migrate dev → SQL 검토 → 커밋
+
+## Rules
+
+### 스키마
+- 모든 모델에 `id`, `createdAt`, `updatedAt`
+- 명시적 인덱스 정의 (`@@index`)
+- `@@map`으로 테이블명 명시
+- 관계는 명확히 정의
+
+### 쿼리
+- `select`로 필요한 필드만 조회 (성능)
+- 페이지네이션 적용 (`take`, `skip`)
+- 복잡한 작업은 트랜잭션 사용
+- **금지**: N+1 쿼리, 무한 결과 조회
+
+### 마이그레이션
+- `migrate dev`로 개발, `migrate deploy`로 배포
+- 마이그레이션 파일 커밋 필수
+- **금지**: 프로덕션에서 `db push`
+
+## Checklist
+- [ ] 싱글톤 인스턴스 사용
+- [ ] 마이그레이션으로 스키마 관리
+- [ ] 트랜잭션으로 데이터 정합성
+- [ ] select로 필요한 필드만 조회
+- [ ] 인덱스 적절히 설정
+- [ ] Repository 패턴 적용
+
+## 참조
+- `rules/schema-design.md` — 모델 정의, 공통 필드, 소프트 삭제 패턴
+- `rules/queries.md` — 싱글톤, CRUD, Relations, 트랜잭션, Repository 패턴

package/templates/base/skills/database/prisma/rules/queries.md

@@ -0,0 +1,133 @@
+---
+title: Prisma Query Patterns
+impact: HIGH
+tags: prisma, database, queries
+---
+
+# Prisma Query Patterns
+
+## 싱글톤 인스턴스
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined;
+};
+
+export const prisma = globalForPrisma.prisma ?? new PrismaClient({
+  log: process.env.NODE_ENV === 'development'
+    ? ['query', 'error', 'warn']
+    : ['error'],
+});
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma;
+}
+```
+
+## Extensions (소프트 삭제 자동 필터)
+
+```typescript
+export const prisma = prismaBase.$extends({
+  query: {
+    $allModels: {
+      async findMany({ model, operation, args, query }) {
+        args.where = { ...args.where, deletedAt: null };
+        return query(args);
+      },
+    },
+  },
+});
+```
+
+## 기본 CRUD
+
+```typescript
+// Create
+const user = await prisma.user.create({
+  data: { email: 'test@example.com', name: 'Test', password: hashedPassword },
+});
+
+// Read
+const user = await prisma.user.findUnique({ where: { id: userId } });
+const users = await prisma.user.findMany({
+  where: { role: 'USER' },
+  orderBy: { createdAt: 'desc' },
+  take: 10, skip: 0,
+});
+
+// Update
+const updated = await prisma.user.update({
+  where: { id: userId },
+  data: { name: 'New Name' },
+});
+
+// Delete
+await prisma.user.delete({ where: { id: userId } });
+
+// Upsert
+const user = await prisma.user.upsert({
+  where: { email: 'test@example.com' },
+  update: { name: 'Updated Name' },
+  create: { email: 'test@example.com', name: 'New User', password },
+});
+```
+
+## Relations 로딩
+
+```typescript
+// include: 관계 데이터 포함
+const userWithPosts = await prisma.user.findUnique({
+  where: { id: userId },
+  include: { posts: true, profile: true },
+});
+
+// select: 특정 필드만 선택 (성능 최적화)
+const userWithPosts = await prisma.user.findUnique({
+  where: { id: userId },
+  select: {
+    id: true, name: true,
+    posts: { select: { id: true, title: true }, where: { published: true }, take: 5 },
+  },
+});
+```
+
+## 트랜잭션
+
+```typescript
+const result = await prisma.$transaction(async (tx) => {
+  const user = await tx.user.create({ data: { email, name, password } });
+  await tx.profile.create({ data: { userId: user.id, bio: '' } });
+  await tx.notification.create({ data: { userId: user.id, message: 'Welcome!' } });
+  return user;
+});
+// 실패 시 모두 롤백
+```
+
+## Repository 패턴
+
+```typescript
+export interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+  save(user: User): Promise<User>;
+  delete(id: string): Promise<void>;
+}
+
+export class PrismaUserRepository implements UserRepository {
+  async findById(id: string) {
+    return prisma.user.findUnique({ where: { id } });
+  }
+  async findByEmail(email: string) {
+    return prisma.user.findUnique({ where: { email } });
+  }
+  async save(data: Omit<User, 'id' | 'createdAt' | 'updatedAt'>) {
+    return prisma.user.create({ data });
+  }
+  async delete(id: string) {
+    await prisma.user.delete({ where: { id } });
+  }
+}
+```

package/templates/base/skills/database/prisma/rules/schema-design.md

@@ -0,0 +1,80 @@
+---
+title: Prisma Schema Design Patterns
+impact: HIGH
+tags: prisma, database, schema
+---
+
+# Prisma Schema Design Patterns
+
+## 기본 모델 정의
+
+```prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String
+  password  String
+  role      Role     @default(USER)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  posts     Post[]
+  profile   Profile?
+
+  @@index([email])
+  @@map("users")
+}
+
+model Post {
+  id        String   @id @default(cuid())
+  title     String
+  content   String?
+  published Boolean  @default(false)
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  author    User     @relation(fields: [authorId], references: [id])
+  authorId  String
+
+  @@index([authorId])
+  @@map("posts")
+}
+
+enum Role {
+  USER
+  ADMIN
+}
+```
+
+## 공통 필드 패턴
+모든 모델에 공통으로 들어가는 필드 (Prisma는 상속 미지원, 컨벤션으로 관리):
+- `id String @id @default(cuid())`
+- `createdAt DateTime @default(now())`
+- `updatedAt DateTime @updatedAt`
+
+## 소프트 삭제
+
+```prisma
+model User {
+  id        String    @id @default(cuid())
+  deletedAt DateTime? // null이면 활성, 값 있으면 삭제됨
+  @@index([deletedAt])
+}
+```
+
+```typescript
+const activeUsers = await prisma.user.findMany({
+  where: { deletedAt: null },
+});
+```

package/templates/base/skills/frontend/nextjs/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: nextjs
+description: Next.js App Router 개발 가이드라인
+version: "1.0.0"
+tags: [nextjs, react, frontend]
+user-invocable: false
+---
+
+# Next.js 15+ App Router
+
+## 철학
+- Server First — 기본은 서버 컴포넌트
+- Progressive Enhancement — 필요할 때만 클라이언트
+- Colocation — 관련 파일은 가까이
+
+## Server vs Client 판단
+
+| 조건 | 컴포넌트 |
+|------|---------|
+| 데이터 페칭, DB 접근, 민감 정보 | Server (기본) |
+| 인터랙션, 이벤트, useState/useEffect | Client (`'use client'`) |
+| 브라우저 API 필요 | Client |
+| 그 외 | Server |
+
+## Rules
+
+### 컴포넌트
+- 기본은 Server Component
+- 인터랙션 필요할 때만 `'use client'`
+- Client Component는 작게 유지 (leaf에 배치)
+- **금지**: Server Component에서 useState/useEffect, 불필요한 `'use client'`
+
+### 데이터
+- Server Component에서 데이터 페칭
+- mutation은 Server Actions 사용
+- 적절한 캐싱 전략 설정
+- **금지**: Client Component에서 직접 DB 접근
+
+### 라우팅
+- 파일 기반 라우팅 규칙 준수
+- Route Group으로 레이아웃 관리
+- `loading.tsx`, `error.tsx` 제공
+
+## 성능 최적화
+- `next/image`: sizes 속성
+- `next/font`: 폰트 최적화
+- `next/link`: 프리페칭
+- 동적 import: 무거운 컴포넌트 지연 로딩
+
+## Checklist
+- [ ] Server Component 기본 사용
+- [ ] 'use client' 최소화
+- [ ] Server Actions로 mutation
+- [ ] 적절한 캐싱 전략
+- [ ] loading.tsx, error.tsx 구현
+- [ ] Metadata 설정
+
+## 참조
+- `rules/app-router.md` — 디렉토리 구조, Server/Client 예시, Data Fetching, Metadata, Loading/Error 패턴

package/templates/base/skills/frontend/nextjs/rules/app-router.md

@@ -0,0 +1,138 @@
+---
+title: Next.js App Router Patterns
+impact: HIGH
+tags: nextjs, frontend, app-router
+---
+
+# Next.js App Router Patterns
+
+## 디렉토리 구조
+
+```
+app/
+├── layout.tsx           # 루트 레이아웃 (필수)
+├── page.tsx             # 홈페이지 (/)
+├── loading.tsx          # 로딩 UI
+├── error.tsx            # 에러 UI
+├── not-found.tsx        # 404 UI
+│
+├── (auth)/              # Route Group (URL에 미포함)
+│   ├── login/page.tsx   # /login
+│   └── register/page.tsx # /register
+│
+├── dashboard/
+│   ├── layout.tsx       # 대시보드 레이아웃
+│   ├── page.tsx         # /dashboard
+│   └── settings/page.tsx # /dashboard/settings
+│
+├── users/
+│   ├── page.tsx         # /users (목록)
+│   └── [id]/
+│       ├── page.tsx     # /users/:id
+│       └── edit/page.tsx # /users/:id/edit
+│
+└── api/users/route.ts   # /api/users
+```
+
+## Server vs Client Component
+
+### 판단 기준
+```
+데이터 페칭 필요? → Server Component
+인터랙션/이벤트 필요? → Client Component ('use client')
+브라우저 API 필요? → Client Component
+그 외 → Server Component (기본)
+```
+
+### Server Component (기본)
+```typescript
+// app/users/page.tsx
+import { db } from '@/lib/db';
+
+export default async function UsersPage() {
+  const users = await db.user.findMany();
+  return (
+    <ul>
+      {users.map(user => <li key={user.id}>{user.name}</li>)}
+    </ul>
+  );
+}
+```
+
+### Client Component
+```typescript
+// components/counter.tsx
+'use client';
+import { useState } from 'react';
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>;
+}
+```
+
+## Data Fetching
+
+### Server Component에서 직접 fetch
+```typescript
+async function getPosts() {
+  const res = await fetch('https://api.example.com/posts', {
+    next: { revalidate: 60 },
+  });
+  return res.json();
+}
+```
+
+### Server Actions
+```typescript
+// app/actions/user.ts
+'use server';
+import { revalidatePath } from 'next/cache';
+
+export async function createUser(formData: FormData) {
+  const name = formData.get('name') as string;
+  await db.user.create({ data: { name, email: formData.get('email') as string } });
+  revalidatePath('/users');
+}
+```
+
+### 캐싱 전략
+| 옵션 | 설명 |
+|------|------|
+| `force-cache` | 기본값, 캐시 사용 |
+| `no-store` | 캐시 안 함, 항상 새로 요청 |
+| `revalidate: N` | N초마다 재검증 |
+| `revalidatePath()` | 특정 경로 재검증 |
+| `revalidateTag()` | 태그로 재검증 |
+
+## Metadata
+
+```typescript
+// 정적
+export const metadata: Metadata = { title: 'About Us' };
+
+// 동적
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { id } = await params;
+  const user = await getUser(id);
+  return { title: user.name };
+}
+```
+
+## Loading & Error
+
+```typescript
+// loading.tsx
+export default function Loading() { return <DashboardSkeleton />; }
+
+// error.tsx
+'use client';
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```

package/templates/base/skills/frontend/react/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: react
+description: React 컴포넌트 개발 가이드라인. 단일 책임, UI/로직 분리, 명시적 데이터 흐름, 서버/클라이언트 상태 분리.
+version: "1.0.0"
+tags: [react, components, frontend]
+user-invocable: false
+---
+
+# React Development Guidelines
+
+프로젝트 전체에서 일관된 React 컴포넌트 개발을 위한 컨벤션.
+
+## Philosophy
+
+- 컴포넌트는 단일 책임
+- UI와 로직 분리 (커스텀 훅)
+- Props로 명시적 데이터 흐름
+- 서버 상태와 클라이언트 상태 분리
+
+## Resources
+
+25개 규칙 (TimSquad 3 + Vercel 22). 카테고리 인덱스: [_sections.md](rules/_sections.md)
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| CRITICAL | rule | [async-parallel](rules/async-parallel.md) | Promise.all 병렬 실행 (2-10x) |
+| CRITICAL | rule | [bundle-barrel-imports](rules/bundle-barrel-imports.md) | barrel import 피하기 |
+| HIGH | rule | [component-conventions](rules/component-conventions.md) | 컴포넌트 구조, export, 크기 제한 |
+| HIGH | rule | [state-location](rules/state-location.md) | 상태 관리 선택 기준 |
+| HIGH | rule | [server-parallel-fetching](rules/server-parallel-fetching.md) | 서버 병렬 fetch |
+| HIGH | rule | [rerender-memo](rules/rerender-memo.md) | React.memo 최적화 |
+| MEDIUM | rule | [anti-patterns](rules/anti-patterns.md) | Props Drilling, useEffect 남용 |
+
+## Quick Rules
+
+### 컴포넌트
+- 함수형 컴포넌트 + Props interface
+- named export (`export function`, default export 금지)
+- 200줄 이하
+- forwardRef로 ref 전달 지원
+
+### 훅
+- 커스텀 훅으로 로직 분리 (`use` 접두사)
+- 의존성 배열 정확히 관리
+- 함수형 setState로 stale closure 방지
+- 조건문/반복문 안에서 훅 호출 금지
+- useEffect 남용 금지 (파생 상태는 useMemo)
+
+### 상태 관리
+- 서버 상태: React Query (TanStack Query)
+- 전역 UI 상태: Zustand
+- 로컬 상태: useState
+- 복잡한 로직: useReducer
+- 비싼 초기값: lazy init (`useState(() => ...)`)
+- Props drilling 3단계 이상 → Context 또는 Zustand
+
+### 성능 (vercel-react-best-practices 참조)
+- 리스트에 고유 key (index 금지)
+- Promise.all로 병렬 fetch
+- barrel import 피하기 (직접 import)
+- dynamic import로 무거운 컴포넌트 분리
+- content-visibility로 대량 리스트 최적화
+- toSorted()로 배열 불변성
+
+### 폼
+- React Hook Form + Zod (zodResolver)
+- onBlur 유효성 검사, submit 시 첫 에러 필드 포커스
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | 함수형 컴포넌트 + Props 타입 정의 |
+| CRITICAL | 커스텀 훅으로 로직 분리 |
+| CRITICAL | 서버 상태는 React Query |
+| CRITICAL | Error Boundary로 에러 격리 |
+| CRITICAL | Waterfall 제거 (Promise.all) |
+| CRITICAL | Barrel import 피하기 |
+| HIGH | 의존성 배열 정확히 관리 |
+| HIGH | 리스트에 고유 key (index 금지) |
+| HIGH | 폼은 React Hook Form + Zod |
+| HIGH | 함수형 setState 사용 |
+| HIGH | Dynamic import 분리 |
+| MEDIUM | 대량 리스트 가상화 / content-visibility |
+| MEDIUM | 불필요한 useEffect 제거 |
+| MEDIUM | RSC 경계에서 필요한 데이터만 전달 |

package/templates/base/skills/frontend/react/rules/_sections.md

@@ -0,0 +1,88 @@
+---
+title: React Rule Categories
+---
+
+# React Rule Categories
+
+25개 규칙을 카테고리별로 정리. TimSquad 커스텀 + Vercel react-best-practices 통합.
+
+## TimSquad Custom (tsq-)
+
+**Impact:** HIGH
+**Description:** 프로젝트 컨벤션 및 아키텍처 규칙
+
+| Rule | Description |
+|------|-------------|
+| [component-conventions](component-conventions.md) | 컴포넌트 구조 템플릿, export, 크기 제한 |
+| [state-location](state-location.md) | useState/Context/Zustand/React Query 선택 기준 |
+| [anti-patterns](anti-patterns.md) | Props Drilling, useEffect 남용, God Component |
+
+## Eliminating Waterfalls (async-)
+
+**Impact:** CRITICAL
+**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency.
+
+| Rule | Description |
+|------|-------------|
+| [async-parallel](async-parallel.md) | Promise.all for independent operations (2-10x) |
+| [async-defer-await](async-defer-await.md) | Start async work before awaiting |
+| [async-api-routes](async-api-routes.md) | Parallel data fetching in API routes |
+| [async-dependencies](async-dependencies.md) | Break async dependency chains |
+| [async-suspense-boundaries](async-suspense-boundaries.md) | Granular Suspense boundaries |
+
+## Bundle Size (bundle-)
+
+**Impact:** CRITICAL
+**Description:** Reducing initial bundle size improves TTI and LCP.
+
+| Rule | Description |
+|------|-------------|
+| [bundle-barrel-imports](bundle-barrel-imports.md) | Avoid barrel files, use direct imports |
+| [bundle-dynamic-imports](bundle-dynamic-imports.md) | Dynamic import for heavy components |
+| [bundle-defer-third-party](bundle-defer-third-party.md) | Defer non-critical third-party scripts |
+
+## Server-Side Performance (server-)
+
+**Impact:** HIGH
+**Description:** Optimizing server-side rendering and data fetching.
+
+| Rule | Description |
+|------|-------------|
+| [server-cache-react](server-cache-react.md) | React cache() for request dedup |
+| [server-parallel-fetching](server-parallel-fetching.md) | Parallel server data fetching |
+| [server-after-nonblocking](server-after-nonblocking.md) | after() for non-blocking work |
+
+## Re-render Optimization (rerender-)
+
+**Impact:** MEDIUM
+**Description:** Reducing unnecessary re-renders.
+
+| Rule | Description |
+|------|-------------|
+| [rerender-memo](rerender-memo.md) | React.memo for stable components |
+| [rerender-defer-reads](rerender-defer-reads.md) | Defer state reads to minimize scope |
+| [rerender-derived-state](rerender-derived-state.md) | Derive state instead of syncing |
+| [rerender-transitions](rerender-transitions.md) | useTransition for non-urgent updates |
+
+## Rendering Performance (rendering-)
+
+**Impact:** MEDIUM
+**Description:** Optimizing the rendering process.
+
+| Rule | Description |
+|------|-------------|
+| [rendering-content-visibility](rendering-content-visibility.md) | content-visibility: auto for large lists |
+| [rendering-hoist-jsx](rendering-hoist-jsx.md) | Hoist JSX out of loops/conditions |
+| [rendering-conditional-render](rendering-conditional-render.md) | Efficient conditional rendering |
+
+## JavaScript Performance (js-)
+
+**Impact:** LOW-MEDIUM
+**Description:** Micro-optimizations for hot paths.
+
+| Rule | Description |
+|------|-------------|
+| [js-index-maps](js-index-maps.md) | Pre-index data with Maps |
+| [js-early-exit](js-early-exit.md) | Early return for cheaper checks first |
+| [js-set-map-lookups](js-set-map-lookups.md) | Set/Map for O(1) lookups |
+| [js-combine-iterations](js-combine-iterations.md) | Combine array iterations |

package/templates/base/skills/frontend/react/rules/anti-patterns.md

@@ -0,0 +1,67 @@
+---
+title: Anti-Patterns
+impact: MEDIUM
+tags: anti-pattern, performance, useEffect
+---
+
+## Anti-Patterns
+
+### 1. useEffect for Derived State
+
+**Incorrect:**
+```tsx
+const [items, setItems] = useState([]);
+const [total, setTotal] = useState(0);
+
+useEffect(() => {
+  setTotal(items.reduce((sum, i) => sum + i.price, 0));
+}, [items]);
+```
+
+**Correct:**
+```tsx
+const total = useMemo(
+  () => items.reduce((sum, i) => sum + i.price, 0),
+  [items]
+);
+```
+
+### 2. Inline Object/Array in JSX
+
+**Incorrect:**
+```tsx
+// 매 렌더링마다 새 참조 → memo 무효화
+<Child style={{ color: 'red' }} items={[1, 2, 3]} />
+```
+
+**Correct:**
+```tsx
+const style = useMemo(() => ({ color: 'red' }), []);
+const items = useMemo(() => [1, 2, 3], []);
+<Child style={style} items={items} />
+```
+
+### 3. Props Drilling (3+ levels)
+
+3단계 이상 Props 전달 → Context 또는 Zustand 사용.
+
+### 4. God Component (500+ lines)
+
+하나의 거대한 컴포넌트 → 작은 단위로 분리, 훅으로 로직 추출.
+
+### 5. Stale Closure in Callbacks
+
+**Incorrect:**
+```tsx
+const [items, setItems] = useState(initialItems);
+const addItems = useCallback((newItems: Item[]) => {
+  setItems([...items, ...newItems]); // items 참조 고정됨
+}, [items]); // items 변경마다 재생성
+```
+
+**Correct:**
+```tsx
+const addItems = useCallback((newItems: Item[]) => {
+  setItems(curr => [...curr, ...newItems]); // 함수형 setState
+}, []); // 의존성 없음, 안정적
+```