@kood/claude-code 0.1.0

package/templates/tanstack-start/docs/library/zod/validation.md

@@ -0,0 +1,208 @@
+# Zod - 검증
+
+> **상위 문서**: [Zod](./index.md)
+
+## Refinement (커스텀 검증)
+
+```typescript
+// v4 - error 파라미터 사용 (message는 deprecated)
+const PasswordSchema = z.string()
+  .min(8)
+  .refine((val) => /[A-Z]/.test(val), {
+    error: '대문자가 포함되어야 합니다',  // v4: message → error
+  })
+  .refine((val) => /[0-9]/.test(val), {
+    error: '숫자가 포함되어야 합니다',
+  })
+```
+
+### v4 Refinement 체이닝 개선
+
+```typescript
+// v3 - ZodEffects로 래핑되어 .min() 호출 불가
+z.string()
+  .refine(val => val.includes("@"))
+  .min(5) // ❌ 에러
+
+// v4 - 스키마 내부에 저장되어 체이닝 가능
+z.string()
+  .refine(val => val.includes("@"))
+  .min(5) // ✅ 정상 작동
+```
+
+### Async Refinement
+
+```typescript
+const schema = z.string().refine(async (val) => val.length <= 8)
+
+await schema.parseAsync('hello') // => "hello"
+```
+
+### 이메일 중복 검사 예시
+
+```typescript
+const EmailSchema = z.email()  // v4 새 API
+  .refine(async (email) => {
+    const exists = await checkEmailExists(email)
+    return !exists
+  }, {
+    error: '이미 사용 중인 이메일입니다',  // v4: message → error
+  })
+```
+
+## Superrefine (고급 검증)
+
+여러 이슈를 추가하거나 경로를 지정할 수 있습니다.
+
+> **v4 변경**: `ctx.path`는 더 이상 사용할 수 없습니다 (성능 향상을 위해 제거됨)
+
+```typescript
+const Schema = z.object({
+  password: z.string(),
+  confirmPassword: z.string(),
+}).superRefine((data, ctx) => {
+  if (data.password !== data.confirmPassword) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: '비밀번호가 일치하지 않습니다',
+      path: ['confirmPassword'],
+    })
+  }
+  // ctx.path // ❌ v4에서 더 이상 사용 불가
+})
+```
+
+### 복잡한 검증 로직
+
+```typescript
+const UserSchema = z.object({
+  username: z.string(),
+  email: z.string().email(),
+  age: z.number(),
+}).superRefine((data, ctx) => {
+  // 여러 조건 검증
+  if (data.age < 13 && data.email.includes('work')) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: '13세 미만은 업무용 이메일을 사용할 수 없습니다',
+      path: ['email'],
+    })
+  }
+
+  if (data.username.toLowerCase() === 'admin' && data.age < 18) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'admin 사용자명은 18세 이상만 사용 가능합니다',
+      path: ['username'],
+    })
+  }
+})
+```
+
+## 커스텀 스키마
+
+```typescript
+const px = z.custom<`${number}px`>((val) => {
+  return typeof val === 'string' ? /^\d+px$/.test(val) : false
+})
+
+type Px = z.infer<typeof px> // `${number}px`
+
+px.parse('42px')  // '42px'
+px.parse('42vw')  // throws
+```
+
+## TanStack Start와 함께 사용
+
+### Server Function 입력 검증
+
+```typescript
+import { createServerFn } from '@tanstack/react-start'
+import { zodValidator } from '@tanstack/react-start/validators'
+import { z } from 'zod'
+
+const createUserSchema = z.object({
+  email: z.email(),  // v4 새 API
+  name: z.string().min(1).max(100).trim(),
+  bio: z.string().max(500).optional(),
+})
+
+export const createUser = createServerFn({ method: 'POST' })
+  .inputValidator(zodValidator(createUserSchema))
+  .handler(async ({ data }) => {
+    // data는 타입 안전함
+    return prisma.user.create({ data })
+  })
+```
+
+### 환경 변수 검증
+
+```typescript
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+  DATABASE_URL: z.string().url(),
+  API_SECRET: z.string().min(32),
+})
+
+export const env = envSchema.parse(process.env)
+```
+
+### Middleware에서 사용
+
+```typescript
+import { createMiddleware } from '@tanstack/react-start'
+import { zodValidator } from '@tanstack/react-start/validators'
+import { z } from 'zod'
+
+const mySchema = z.object({
+  workspaceId: z.string(),
+})
+
+const workspaceMiddleware = createMiddleware({ type: 'function' })
+  .inputValidator(zodValidator(mySchema))
+  .server(({ next, data }) => {
+    console.log('Workspace ID:', data.workspaceId)
+    return next()
+  })
+```
+
+## 에러 처리
+
+```typescript
+const result = UserSchema.safeParse(data)
+
+if (!result.success) {
+  // ZodError 객체
+  const errors = result.error.errors
+
+  errors.forEach((err) => {
+    console.log('Path:', err.path)
+    console.log('Message:', err.message)
+    console.log('Code:', err.code)
+  })
+
+  // 평면화된 에러
+  const flatErrors = result.error.flatten()
+  console.log(flatErrors.fieldErrors)
+  // { email: ['Invalid email'], name: ['Required'] }
+}
+```
+
+## Zod Mini (경량 버전)
+
+v4에서 새롭게 추가된 경량 API:
+
+```typescript
+import * as z from "zod/mini"
+
+// regular Zod
+z.string().min(5).max(10).trim()
+
+// Zod Mini - check 메서드로 통합
+z.string().check(
+  z.minLength(5),
+  z.maxLength(10),
+  z.toLowerCase(),
+  z.trim(),
+)
+```

package/templates/tanstack-start/docs/mcp/context7.md

@@ -0,0 +1,204 @@
+# Context7 MCP
+
+> 라이브러리 공식 문서를 실시간으로 조회하는 도구
+
+---
+
+## 🚀 Quick Reference
+
+```
+✅ 사용 필수 상황:
+- 라이브러리 API 사용법 확인
+- 최신 버전 문법 확인
+- 공식 문서 기반 구현
+- 버전 마이그레이션
+
+❌ 불필요한 상황:
+- 이미 알고 있는 기본 문법
+- 프로젝트 내부 코드 분석
+- 비즈니스 로직 구현
+```
+
+---
+
+## 사용 방법
+
+### Step 1: 라이브러리 ID 조회
+
+```
+resolve-library-id 사용
+→ 라이브러리 이름으로 Context7 ID 획득
+```
+
+### Step 2: 문서 조회
+
+```
+get-library-docs 사용
+→ 특정 토픽의 문서 가져오기
+
+파라미터:
+- context7CompatibleLibraryID: 라이브러리 ID
+- topic: 조회할 주제 (예: "hooks", "routing")
+```
+
+---
+
+## 프로젝트 라이브러리별 사용 예시
+
+### TanStack Start
+
+```
+토픽 예시:
+- "server functions" - createServerFn 사용법
+- "routing" - 파일 기반 라우팅
+- "loader" - 데이터 로딩
+- "middleware" - 미들웨어 설정
+```
+
+### TanStack Query
+
+```
+토픽 예시:
+- "useQuery" - 쿼리 훅
+- "useMutation" - 뮤테이션 훅
+- "invalidation" - 캐시 무효화
+- "optimistic updates" - 낙관적 업데이트
+```
+
+### Prisma
+
+```
+토픽 예시:
+- "findMany" - 다중 조회
+- "create" - 생성
+- "relations" - 관계 쿼리
+- "transactions" - 트랜잭션
+```
+
+### Zod
+
+```
+토픽 예시:
+- "object" - 객체 스키마
+- "email" - 이메일 검증 (v4)
+- "transform" - 변환
+- "refinement" - 커스텀 검증
+```
+
+### Tailwind CSS
+
+```
+토픽 예시:
+- "configuration" - 설정
+- "theme" - 테마 커스터마이징
+- "responsive" - 반응형
+- "dark mode" - 다크 모드
+```
+
+### Better Auth
+
+```
+토픽 예시:
+- "setup" - 초기 설정
+- "session" - 세션 관리
+- "providers" - OAuth 설정
+- "2fa" - 이중 인증
+```
+
+---
+
+## 사용 시점
+
+### ✅ 반드시 사용
+
+| 상황 | 이유 |
+|------|------|
+| 새 API 사용 | 정확한 시그니처 확인 |
+| 버전 업그레이드 | 변경사항 확인 |
+| 에러 해결 | 올바른 사용법 확인 |
+| 고급 기능 | 옵션/설정 확인 |
+
+### ❌ 사용 불필요
+
+| 상황 | 이유 |
+|------|------|
+| 기본 문법 | 이미 문서화됨 |
+| 내부 코드 | Context7 범위 외 |
+| 비즈니스 로직 | 라이브러리 무관 |
+
+---
+
+## 실전 예시
+
+### 예시 1: TanStack Query 캐시 무효화
+
+```
+상황: mutation 후 목록 갱신이 안됨
+
+1. Context7로 "invalidation" 토픽 조회
+2. queryClient.invalidateQueries 사용법 확인
+3. 올바른 queryKey 패턴 적용
+
+결과:
+queryClient.invalidateQueries({ queryKey: ['users'] })
+```
+
+### 예시 2: Prisma 관계 쿼리
+
+```
+상황: User와 Post를 함께 조회하고 싶음
+
+1. Context7로 "relations" 토픽 조회
+2. include 옵션 사용법 확인
+
+결과:
+prisma.user.findUnique({
+  where: { id },
+  include: { posts: true }
+})
+```
+
+### 예시 3: Zod v4 마이그레이션
+
+```
+상황: Zod v3 → v4 업그레이드
+
+1. Context7로 "migration" 또는 "email" 토픽 조회
+2. v4 새 API 확인
+
+결과:
+// v3: z.string().email()
+// v4: z.email()
+```
+
+---
+
+## Sequential Thinking과 함께 사용
+
+```
+복잡한 구현 시:
+
+1. Sequential Thinking으로 구현 계획
+   ↓
+2. 필요한 라이브러리 기능 파악
+   ↓
+3. Context7로 각 기능 문서 조회
+   ↓
+4. 문서 기반 구현
+```
+
+---
+
+## 주의사항
+
+- **최신 문서**: Context7은 최신 공식 문서 제공
+- **버전 확인**: 프로젝트 버전과 문서 버전 일치 확인
+- **토픽 선택**: 구체적인 토픽으로 조회 시 더 정확한 결과
+
+---
+
+## 참고
+
+- 문서가 충분하지 않으면 다른 토픽으로 재조회
+- 여러 라이브러리 문서를 연속으로 조회 가능
+- Sequential Thinking과 조합하여 체계적 구현

package/templates/tanstack-start/docs/mcp/index.md

@@ -0,0 +1,116 @@
+# MCP (Model Context Protocol)
+
+> Claude Code 작업 효율성을 높이는 MCP 서버 활용 가이드
+
+---
+
+## 🚨 필수 사용 규칙
+
+```
+✅ 코드베이스 검색 → sgrep 사용 (grep/rg 금지)
+✅ 복잡한 분석/디버깅 → Sequential Thinking 사용
+✅ 라이브러리 문서 조회 → Context7 사용
+✅ 도구 조합: sgrep로 위치 파악 → Sequential로 분석 → Context7로 문서 확인
+```
+
+---
+
+## 🚀 Quick Reference
+
+### Sequential Thinking - 복잡한 문제 해결
+
+```
+사용 시점:
+- 버그 분석 및 디버깅
+- 아키텍처 설계
+- 복잡한 로직 구현
+- 코드 리팩토링 계획
+- 성능 최적화 분석
+
+사용법: 문제를 단계별로 분해하여 체계적으로 해결
+```
+
+### Context7 - 라이브러리 문서 조회
+
+```
+사용 시점:
+- API 사용법 확인
+- 라이브러리 최신 문법 확인
+- 공식 문서 기반 구현
+- 버전별 변경사항 확인
+
+사용법:
+1. resolve-library-id로 라이브러리 ID 조회
+2. get-library-docs로 문서 가져오기
+```
+
+---
+
+## 📁 문서 구조
+
+```
+docs/mcp/
+├── index.md              # 이 문서 (개요)
+├── sgrep.md              # 코드베이스 검색
+├── sequential-thinking.md # Sequential Thinking 상세
+└── context7.md           # Context7 상세
+```
+
+---
+
+## 📋 도구 목록
+
+| 도구 | 용도 | 사용 시점 |
+|-----|------|----------|
+| [sgrep](./sgrep.md) | 코드베이스 검색 | 코드 위치 파악, 자연어 검색 |
+| [Sequential Thinking](./sequential-thinking.md) | 체계적 문제 해결 | 복잡한 분석, 디버깅, 설계 |
+| [Context7](./context7.md) | 라이브러리 문서 | API 확인, 최신 문법 |
+
+---
+
+## ⚡ 작업별 MCP 선택 가이드
+
+### 버그 수정
+```
+1. sgrep로 관련 코드 위치 파악
+2. Sequential Thinking으로 문제 분석
+3. 원인 파악 후 Context7로 관련 API 확인
+4. 수정 구현
+```
+
+### 새 기능 구현
+```
+1. sgrep로 기존 패턴 검색
+2. Sequential Thinking으로 구현 계획 수립
+3. Context7로 사용할 라이브러리 문서 확인
+4. 단계별 구현
+```
+
+### 라이브러리 사용
+```
+1. Context7로 공식 문서 조회
+2. 필요시 Sequential Thinking으로 복잡한 통합 분석
+```
+
+### 성능 최적화
+```
+1. sgrep로 병목 의심 코드 검색
+2. Sequential Thinking으로 병목 분석
+3. Context7로 최적화 관련 API 확인
+4. 개선 구현
+```
+
+### 코드베이스 탐색
+```
+1. sgrep로 자연어 쿼리 검색
+2. 관련 코드 위치 파악
+3. 필요시 Sequential Thinking으로 흐름 분석
+```
+
+---
+
+## 🔗 관련 문서
+
+- [TanStack Start](../library/tanstack-start/index.md) - Server Functions
+- [Prisma](../library/prisma/index.md) - ORM
+- [Zod](../library/zod/index.md) - Validation

package/templates/tanstack-start/docs/mcp/sequential-thinking.md

@@ -0,0 +1,180 @@
+# Sequential Thinking MCP
+
+> 복잡한 문제를 체계적으로 분해하고 해결하는 사고 도구
+
+---
+
+## 🚀 Quick Reference
+
+```
+✅ 사용 필수 상황:
+- 버그 원인 분석
+- 아키텍처 설계
+- 복잡한 로직 구현
+- 리팩토링 계획
+- 성능 최적화
+- 다단계 작업 계획
+
+❌ 불필요한 상황:
+- 단순 코드 수정
+- 명확한 API 호출
+- 복사/붙여넣기 작업
+```
+
+---
+
+## 핵심 개념
+
+Sequential Thinking은 복잡한 문제를 **단계별로 분해**하여 체계적으로 해결하는 사고 방식입니다.
+
+### 작동 방식
+
+1. **문제 정의**: 해결해야 할 문제 명확화
+2. **분해**: 작은 단계로 나누기
+3. **순차 분석**: 각 단계 순서대로 분석
+4. **검증**: 각 단계 결과 검증
+5. **종합**: 최종 결론 도출
+
+---
+
+## 사용 시점
+
+### ✅ 반드시 사용
+
+| 상황 | 이유 |
+|------|------|
+| 버그 디버깅 | 원인 추적에 체계적 접근 필요 |
+| 시스템 설계 | 구성 요소 간 관계 분석 |
+| 복잡한 로직 | 단계별 흐름 파악 |
+| 리팩토링 | 영향 범위 분석 |
+| 성능 분석 | 병목 지점 식별 |
+
+### ❌ 사용 불필요
+
+| 상황 | 이유 |
+|------|------|
+| 단순 CRUD | 패턴이 명확함 |
+| 스타일 수정 | 분석 불필요 |
+| 오타 수정 | 즉시 수정 가능 |
+| 문서 확인 | Context7 사용 |
+
+---
+
+## 실전 예시
+
+### 예시 1: 버그 디버깅
+
+```
+문제: "로그인 후 세션이 유지되지 않음"
+
+Step 1: 증상 파악
+- 로그인 성공 후 페이지 이동 시 로그아웃됨
+- 새로고침 시 세션 사라짐
+
+Step 2: 가설 수립
+- 쿠키 설정 문제?
+- 세션 저장소 문제?
+- 미들웨어 문제?
+
+Step 3: 검증
+- 쿠키 확인 → httpOnly, secure 설정 확인
+- 세션 저장소 확인 → Redis 연결 상태 확인
+- 미들웨어 확인 → 세션 검증 로직 확인
+
+Step 4: 원인 특정
+- 쿠키 sameSite 설정이 'strict'로 되어 있어
+  cross-origin 요청 시 쿠키 미전송
+
+Step 5: 해결
+- sameSite: 'lax'로 변경
+```
+
+### 예시 2: 아키텍처 설계
+
+```
+문제: "사용자 알림 시스템 설계"
+
+Step 1: 요구사항 정리
+- 실시간 알림 (WebSocket)
+- 이메일 알림
+- 푸시 알림
+- 알림 히스토리
+
+Step 2: 구성 요소 식별
+- NotificationService (핵심 로직)
+- WebSocketHandler (실시간)
+- EmailProvider (이메일)
+- PushProvider (푸시)
+- NotificationRepository (저장)
+
+Step 3: 데이터 흐름 설계
+- 이벤트 발생 → NotificationService
+- NotificationService → 채널별 분배
+- 각 Provider → 전송
+- Repository → 저장
+
+Step 4: 인터페이스 정의
+- INotificationProvider
+- INotificationRepository
+- NotificationEvent 타입
+
+Step 5: 구현 순서 결정
+1. 타입/인터페이스 정의
+2. Repository 구현
+3. Service 핵심 로직
+4. Provider 구현
+5. WebSocket 통합
+```
+
+### 예시 3: 성능 최적화
+
+```
+문제: "목록 페이지 로딩 3초 이상"
+
+Step 1: 현재 상태 측정
+- API 응답: 2.5초
+- 렌더링: 0.5초
+
+Step 2: API 분석
+- 쿼리 확인: N+1 문제 발견
+- 데이터 양: 1000개 전체 로딩
+
+Step 3: 최적화 방안
+- N+1 해결: include로 조인
+- 페이지네이션: 20개씩 로딩
+- 인덱스: 자주 조회하는 컬럼
+
+Step 4: 구현
+- Prisma include 추가
+- 커서 기반 페이지네이션
+- DB 인덱스 생성
+
+Step 5: 결과 측정
+- API 응답: 0.3초 (88% 개선)
+```
+
+---
+
+## Context7과 함께 사용
+
+```
+복잡한 문제 해결 시:
+
+1. Sequential Thinking으로 문제 분석
+   ↓
+2. 필요한 라이브러리 API 파악
+   ↓
+3. Context7로 공식 문서 확인
+   ↓
+4. Sequential Thinking으로 구현 계획
+   ↓
+5. 구현
+```
+
+---
+
+## 참고
+
+- 복잡한 문제일수록 단계를 더 세분화
+- 각 단계에서 가정과 검증을 명확히
+- 필요시 이전 단계로 돌아가 재분석