@kood/claude-code 0.3.5 → 0.3.7

package/templates/nextjs/docs/library/prisma/relations.md

@@ -0,0 +1,69 @@
+# Prisma - 관계 쿼리
+
+## 중첩 생성
+
+```typescript
+const user = await prisma.user.create({
+  data: {
+    email: 'user@prisma.io',
+    posts: { create: [{ title: 'Post 1' }, { title: 'Post 2' }] },
+  },
+  include: { posts: true },
+})
+```
+
+## 관계 연결
+
+```typescript
+// connect - 기존 연결
+author: { connect: { id: 1 } }
+
+// connectOrCreate - 있으면 연결, 없으면 생성
+categories: { connectOrCreate: { where: { name: 'Tech' }, create: { name: 'Tech' } } }
+
+// disconnect - 관계 해제
+author: { disconnect: true }
+```
+
+## 관계 포함 조회
+
+```typescript
+// include
+const users = await prisma.user.findMany({ include: { posts: true, profile: true } })
+
+// 중첩
+include: { posts: { include: { categories: true } } }
+
+// 필터 + 정렬
+include: { posts: { where: { published: true }, orderBy: { createdAt: 'desc' }, take: 5 } }
+```
+
+## 관계로 필터링
+
+```typescript
+// some - 하나라도 만족
+where: { posts: { some: { published: true } } }
+
+// every - 모두 만족
+where: { posts: { every: { published: true } } }
+
+// none - 만족 없음
+where: { posts: { none: { published: false } } }
+```
+
+## 카운트
+
+```typescript
+include: { _count: { select: { posts: true } } }
+// 결과: { _count: { posts: 5 } }
+```
+
+## 중첩 수정/삭제
+
+```typescript
+// updateMany
+posts: { updateMany: { where: { published: false }, data: { published: true } } }
+
+// deleteMany
+posts: { deleteMany: { where: { published: false } } }
+```

package/templates/nextjs/docs/library/prisma/schema.md

@@ -0,0 +1,98 @@
+# Prisma - 스키마 정의 (Multi-File)
+
+## ⚠️ 필수 규칙
+
+1. **Multi-File 구조** 사용
+2. **모든 요소에 한글 주석** (파일, 모델, 필드, enum)
+
+## 구조
+
+```
+prisma/schema/
+├── +base.prisma    # datasource, generator
+├── +enum.prisma    # 모든 enum
+├── user.prisma     # User 모델
+└── post.prisma     # Post 모델
+```
+
+## 예시
+
+```prisma
+// +base.prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+generator client {
+  provider = "prisma-client"
+  output   = "../generated/prisma"
+}
+
+// +enum.prisma
+enum Role {
+  USER   // 일반 사용자
+  ADMIN  // 관리자
+}
+
+// user.prisma
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique  // 로그인 이메일
+  name      String?           // 표시 이름
+  role      Role     @default(USER)
+  posts     Post[]            // 작성 게시글 (1:N)
+  profile   Profile?          // 프로필 (1:1)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+```
+
+## 관계 유형
+
+```prisma
+// 1:1
+model Profile {
+  id     Int  @id @default(autoincrement())
+  user   User @relation(fields: [userId], references: [id])
+  userId Int  @unique
+}
+
+// 1:N
+model Post {
+  author   User @relation(fields: [authorId], references: [id])
+  authorId Int
+}
+
+// M:N (암묵적)
+model Post { categories Category[] }
+model Category { posts Post[] }
+
+// M:N (명시적)
+model CategoriesOnPosts {
+  post       Post     @relation(fields: [postId], references: [id])
+  postId     Int
+  category   Category @relation(fields: [categoryId], references: [id])
+  categoryId Int
+  @@id([postId, categoryId])
+}
+```
+
+## 기타
+
+```prisma
+// 선택적 관계
+author   User? @relation(fields: [authorId], references: [id])
+authorId Int?
+
+// 인덱스
+@@index([authorId])
+@@index([createdAt])
+
+// 복합 키
+@@id([postId, tagId])
+
+// 매핑
+@map("user_id")
+@@map("users")
+```

package/templates/nextjs/docs/library/prisma/setup.md

@@ -0,0 +1,49 @@
+# Prisma - 설치 및 설정
+
+## 설치
+
+```bash
+yarn add @prisma/client@7
+yarn add -D prisma@7
+npx prisma init
+```
+
+## v6 → v7 업그레이드
+
+```prisma
+// v6 (이전)
+generator client {
+  provider = "prisma-client-js"
+}
+
+// v7 (필수)
+generator client {
+  provider = "prisma-client"
+  output   = "../generated/prisma"
+}
+```
+
+## Prisma Client
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from './generated/prisma'
+
+const globalForPrisma = globalThis as unknown as { prisma: PrismaClient | undefined }
+export const prisma = globalForPrisma.prisma ?? new PrismaClient({ log: ['query'] })
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma
+```
+
+## TanStack Start 연동
+
+```typescript
+import { createServerFn } from '@tanstack/react-start'
+import { prisma } from '@/lib/prisma'
+
+export const getUsers = createServerFn({ method: 'GET' })
+  .handler(async () => prisma.user.findMany({ include: { posts: true } }))
+
+export const createUser = createServerFn({ method: 'POST' })
+  .inputValidator((data: { email: string; name: string }) => data)
+  .handler(async ({ data }) => prisma.user.create({ data }))
+```

package/templates/nextjs/docs/library/prisma/transactions.md

@@ -0,0 +1,50 @@
+# Prisma - 트랜잭션
+
+## 배열 기반 트랜잭션
+
+하나라도 실패하면 모두 롤백.
+
+```typescript
+const deletePosts = prisma.post.deleteMany({ where: { authorId: 7 } })
+const deleteUser = prisma.user.delete({ where: { id: 7 } })
+await prisma.$transaction([deletePosts, deleteUser])
+```
+
+## 인터랙티브 트랜잭션
+
+복잡한 로직, 조건부 처리.
+
+```typescript
+const result = await prisma.$transaction(async (tx) => {
+  const sender = await tx.account.findUnique({ where: { id: senderId } })
+  if (!sender || sender.balance < amount) throw new Error('Insufficient balance')
+
+  await tx.account.update({ where: { id: senderId }, data: { balance: { decrement: amount } } })
+  await tx.account.update({ where: { id: recipientId }, data: { balance: { increment: amount } } })
+
+  return { success: true }
+})
+```
+
+## 옵션
+
+```typescript
+await prisma.$transaction(async (tx) => { ... }, {
+  maxWait: 5000,              // 최대 대기 (ms)
+  timeout: 10000,             // 타임아웃 (ms)
+  isolationLevel: 'Serializable',  // ReadUncommitted | ReadCommitted | RepeatableRead | Serializable
+})
+```
+
+## 에러 처리
+
+```typescript
+try {
+  await prisma.$transaction(async (tx) => {
+    await tx.user.create({ data: { email } })
+    if (someCondition) throw new Error('Rollback')
+  })
+} catch (error) {
+  // 전체 롤백됨
+}
+```

package/templates/nextjs/docs/library/tanstack-query/index.md

@@ -0,0 +1,66 @@
+# TanStack Query
+
+> 5.x | React Data Fetching
+
+@use-query.md
+@use-mutation.md
+@invalidation.md
+@optimistic-updates.md
+
+---
+
+<quick_reference>
+
+```typescript
+// useQuery
+const { data, isLoading, error } = useQuery({
+  queryKey: ['users'],
+  queryFn: () => getUsers(),
+})
+
+// useMutation + invalidation
+const queryClient = useQueryClient()
+const mutation = useMutation({
+  mutationFn: createUser,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
+})
+mutation.mutate({ email, name })
+
+// Optimistic Update
+const mutation = useMutation({
+  mutationFn: updateUser,
+  onMutate: async (newUser) => {
+    await queryClient.cancelQueries({ queryKey: ['users'] })
+    const previous = queryClient.getQueryData(['users'])
+    queryClient.setQueryData(['users'], (old) => [...old, newUser])
+    return { previous }
+  },
+  onError: (err, newUser, context) => {
+    queryClient.setQueryData(['users'], context.previous)
+  },
+})
+
+// 설정
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5,   // 5분
+      gcTime: 1000 * 60 * 30,     // 30분
+      retry: 3,
+    },
+  },
+})
+
+const App = () => (
+  <QueryClientProvider client={queryClient}>
+    <YourApp />
+  </QueryClientProvider>
+)
+
+// Query Keys
+['todos']                       // 단순
+['todo', { id: 5 }]             // 파라미터
+['todos', 'list', { filters }]  // 계층적
+```
+
+</quick_reference>

package/templates/nextjs/docs/library/tanstack-query/invalidation.md

@@ -0,0 +1,54 @@
+# TanStack Query - Query 무효화
+
+<patterns>
+
+```typescript
+const queryClient = useQueryClient()
+
+// 단일
+queryClient.invalidateQueries({ queryKey: ['todos'] })
+
+// 다중
+await Promise.all([
+  queryClient.invalidateQueries({ queryKey: ['todos'] }),
+  queryClient.invalidateQueries({ queryKey: ['reminders'] }),
+])
+
+// 전체
+queryClient.invalidateQueries()
+
+// 옵션
+queryClient.invalidateQueries({
+  queryKey: ['posts'],
+  exact: true,  // 정확한 키 매칭만
+  refetchType: 'active',  // 'active' | 'inactive' | 'all' | 'none'
+})
+
+// Query Key 매칭
+queryClient.invalidateQueries({ queryKey: ['todos'] })  // prefix 매칭
+queryClient.invalidateQueries({ queryKey: ['todos', 'list'], exact: true })  // 정확한 매칭
+
+// Mutation과 함께
+useMutation({
+  mutationFn: addTodo,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),  // 성공/실패 무관
+})
+
+// 직접 업데이트 vs 무효화
+queryClient.setQueryData(['todos'], (old) => [...old, newTodo])  // 더 빠름
+queryClient.invalidateQueries({ queryKey: ['todos'] })  // 서버 데이터 보장
+```
+
+</patterns>
+
+<options>
+
+| refetchType | 설명 |
+|-------------|------|
+| active | 렌더링 중인 쿼리만 재조회 (기본) |
+| inactive | 비활성 쿼리만 |
+| all | 모든 매칭 쿼리 |
+| none | 무효화만, 재조회 안함 |
+
+</options>

package/templates/nextjs/docs/library/tanstack-query/optimistic-updates.md

@@ -0,0 +1,77 @@
+# TanStack Query - Optimistic Updates
+
+<patterns>
+
+```tsx
+// 추가
+useMutation({
+  mutationFn: addTodo,
+  onMutate: async (newTodo) => {
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+    const previousTodos = queryClient.getQueryData(['todos'])
+    queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
+    return { previousTodos }
+  },
+  onError: (err, newTodo, context) => {
+    queryClient.setQueryData(['todos'], context.previousTodos)
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+
+// 삭제
+useMutation({
+  mutationFn: deleteTodo,
+  onMutate: async (todoId) => {
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+    const previousTodos = queryClient.getQueryData(['todos'])
+    queryClient.setQueryData(['todos'], (old) =>
+      old.filter((todo) => todo.id !== todoId)
+    )
+    return { previousTodos }
+  },
+  onError: (err, todoId, context) => {
+    queryClient.setQueryData(['todos'], context.previousTodos)
+  },
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+})
+
+// 토글
+useMutation({
+  mutationFn: toggleTodo,
+  onMutate: async (todoId) => {
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+    const previousTodos = queryClient.getQueryData(['todos'])
+    queryClient.setQueryData(['todos'], (old) =>
+      old.map((todo) =>
+        todo.id === todoId ? { ...todo, completed: !todo.completed } : todo
+      )
+    )
+    return { previousTodos }
+  },
+  onError: (err, todoId, context) => {
+    queryClient.setQueryData(['todos'], context.previousTodos)
+  },
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+})
+
+// 단일 항목
+useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    await queryClient.cancelQueries({ queryKey: ['todos', newTodo.id] })
+    const previousTodo = queryClient.getQueryData(['todos', newTodo.id])
+    queryClient.setQueryData(['todos', newTodo.id], newTodo)
+    return { previousTodo, newTodo }
+  },
+  onError: (err, newTodo, context) => {
+    queryClient.setQueryData(['todos', context.newTodo.id], context.previousTodo)
+  },
+  onSettled: (newTodo) => {
+    queryClient.invalidateQueries({ queryKey: ['todos', newTodo.id] })
+  },
+})
+```
+
+</patterns>

package/templates/nextjs/docs/library/tanstack-query/use-mutation.md

@@ -0,0 +1,63 @@
+# TanStack Query - useMutation
+
+<patterns>
+
+```tsx
+// 기본
+const queryClient = useQueryClient()
+const mutation = useMutation({
+  mutationFn: postTodo,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+})
+mutation.mutate({ title: 'New Todo' })
+
+// 콜백
+useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    // mutation 시작 전 (optimistic update용)
+    return { previousData }  // context로 전달
+  },
+  onSuccess: (data, variables, context) => {},
+  onError: (error, variables, context) => {},
+  onSettled: (data, error, variables, context) => {
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+
+// mutate vs mutateAsync
+mutation.mutate(data, {
+  onSuccess: (result) => console.log(result),
+  onError: (error) => console.log(error),
+})
+
+try {
+  const result = await mutation.mutateAsync(data)
+} catch (error) { ... }
+
+// 캐시 업데이트
+useMutation({
+  mutationFn: patchTodo,
+  onSuccess: (data) => {
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+    queryClient.setQueryData(['todo', { id: data.id }], data)
+  },
+})
+```
+
+</patterns>
+
+<returns>
+
+| 속성 | 설명 |
+|------|------|
+| data | mutation 결과 |
+| error | 에러 객체 |
+| isPending | 실행 중 |
+| isSuccess/isError | 상태 |
+| mutate | 실행 (비동기) |
+| mutateAsync | 실행 (Promise) |
+| reset | 상태 초기화 |
+| variables | 전달된 변수 |
+
+</returns>

package/templates/nextjs/docs/library/tanstack-query/use-query.md

@@ -0,0 +1,70 @@
+# TanStack Query - useQuery
+
+<patterns>
+
+```tsx
+// 기본
+const { data, isLoading, error } = useQuery({
+  queryKey: ['todos'],
+  queryFn: getTodos,
+})
+if (isLoading) return <div>Loading...</div>
+if (error) return <div>Error: {error.message}</div>
+
+// 옵션
+useQuery({
+  queryKey: ['todos'],
+  queryFn: fetchTodos,
+  staleTime: 1000 * 60 * 5,      // fresh 유지 시간
+  gcTime: 1000 * 60 * 30,        // 가비지 컬렉션 시간
+  refetchOnWindowFocus: true,    // 포커스 시 리페치
+  refetchInterval: 1000 * 60,    // 자동 리페치 간격
+  retry: 3,                      // 재시도 횟수
+  enabled: !!userId,             // 조건부 실행
+  initialData: [],               // 초기 데이터
+  select: (data) => data.filter(t => t.done),  // 데이터 변환
+})
+
+// 파라미터
+useQuery({
+  queryKey: ['todo', todoId],
+  queryFn: () => fetchTodoById(todoId),
+  enabled: !!todoId,
+})
+
+// 의존적 쿼리
+const { data: user } = useQuery({ queryKey: ['user', userId], queryFn: ... })
+const { data: posts } = useQuery({
+  queryKey: ['posts', user?.id],
+  queryFn: () => fetchPostsByUserId(user!.id),
+  enabled: !!user?.id,
+})
+
+// 병렬
+const usersQuery = useQuery({ queryKey: ['users'], queryFn: fetchUsers })
+const postsQuery = useQuery({ queryKey: ['posts'], queryFn: fetchPosts })
+
+// 동적 병렬
+const userQueries = useQueries({
+  queries: userIds.map((id) => ({
+    queryKey: ['user', id],
+    queryFn: () => fetchUserById(id),
+  })),
+})
+```
+
+</patterns>
+
+<returns>
+
+| 속성 | 설명 |
+|------|------|
+| data | 쿼리 결과 |
+| error | 에러 객체 |
+| isLoading | 첫 로딩 중 |
+| isFetching | 백그라운드 페칭 중 |
+| isError/isSuccess | 상태 |
+| refetch | 수동 리페치 |
+| status | 'pending' \| 'error' \| 'success' |
+
+</returns>

package/templates/nextjs/docs/library/zod/complex-types.md

@@ -0,0 +1,61 @@
+# Zod - 복합 타입
+
+<patterns>
+
+```typescript
+// 객체
+const UserSchema = z.object({
+  name: z.string(),
+  email: z.email(),
+  age: z.number().optional(),
+})
+
+UserSchema.partial()              // 모든 필드 optional
+UserSchema.required()             // 모든 필드 required
+UserSchema.pick({ name: true })   // 특정 필드만
+UserSchema.omit({ email: true })  // 특정 필드 제외
+UserSchema.extend({ role: z.enum(['admin', 'user']) })
+UserSchema.merge(AnotherSchema)
+
+z.strictObject({ name: z.string() })  // v4: 추가 키 에러
+z.looseObject({ name: z.string() })   // v4: 추가 키 통과
+
+// 배열/튜플
+z.array(z.string())
+z.array(z.number()).min(1).max(10).length(5).nonempty()
+z.tuple([z.string(), z.number()])  // [string, number]
+
+// 유니온
+z.union([z.string(), z.number()])
+z.string().or(z.number())
+
+z.discriminatedUnion('type', [
+  z.object({ type: z.literal('circle'), radius: z.number() }),
+  z.object({ type: z.literal('rectangle'), width: z.number(), height: z.number() }),
+])
+
+// Enum
+const Status = z.enum(['pending', 'done', 'cancelled'])
+type Status = z.infer<typeof Status>  // 'pending' | 'done' | 'cancelled'
+
+enum Fruits { Apple, Banana }
+z.nativeEnum(Fruits)
+
+// Record/Map/Set
+z.record(z.string(), z.object({ name: z.string() }))  // { [key: string]: { name: string } }
+z.map(z.string(), z.number())  // Map<string, number>
+z.set(z.number())              // Set<number>
+
+// 재귀
+type Json = string | number | boolean | null | { [key: string]: Json } | Json[]
+
+const jsonSchema: z.ZodType<Json> = z.lazy(() =>
+  z.union([
+    z.string(), z.number(), z.boolean(), z.null(),
+    z.array(jsonSchema),
+    z.record(jsonSchema)
+  ])
+)
+```
+
+</patterns>