@kood/claude-code 0.3.5 → 0.3.7

package/templates/nextjs/docs/library/zod/index.md

@@ -0,0 +1,56 @@
+# Zod
+
+> v4 | TypeScript Schema Validation
+
+@complex-types.md
+@transforms.md
+@validation.md
+
+---
+
+<quick_reference>
+
+```typescript
+// 기본
+const schema = z.object({
+  email: z.email(),              // v4!
+  name: z.string().min(1).trim(),
+  website: z.url().optional(),   // v4!
+  age: z.number().int().positive(),
+})
+type Input = z.infer<typeof schema>
+
+schema.parse(data)              // 실패 시 throw
+schema.safeParse(data)          // { success, data/error }
+
+// TanStack Start
+export const createUser = createServerFn({ method: 'POST' })
+  .inputValidator(schema)
+  .handler(async ({ data }) => prisma.user.create({ data }))
+```
+
+</quick_reference>
+
+<v4_changes>
+
+```typescript
+// ✅ v4 새 API
+z.email()  z.url()  z.uuid()
+z.iso.date()  z.iso.datetime()  z.iso.duration()
+z.stringbool()  // "true"/"yes"/"1" → true
+
+// ❌ v3 deprecated
+z.string().email()  z.string().url()
+
+// 변경사항
+z.string().min(5, { error: "Too short." })  // message → error
+z.strictObject({ name: z.string() })  // 추가 키 에러
+z.looseObject({ name: z.string() })   // 추가 키 통과
+z.string().refine(val => val.includes("@")).min(5)  // refinement 체이닝
+
+// 템플릿 리터럴
+const css = z.templateLiteral([z.number(), z.enum(["px", "em", "rem"])])
+// `${number}px` | `${number}em` | `${number}rem`
+```
+
+</v4_changes>

package/templates/nextjs/docs/library/zod/transforms.md

@@ -0,0 +1,51 @@
+# Zod - 변환
+
+<patterns>
+
+```typescript
+// Transform
+const stringToLength = z.string().transform((val) => val.length)
+stringToLength.parse('hello')  // => 5
+
+type In = z.input<typeof stringToLength>   // string
+type Out = z.output<typeof stringToLength> // number
+
+// Pipe (검증 후 변환)
+const stringToNumber = z.string()
+  .transform((val) => parseInt(val, 10))
+  .pipe(z.number().min(0).max(100))
+
+stringToNumber.parse('50')  // => 50
+stringToNumber.parse('150') // throws
+
+// Coerce (강제 변환)
+z.coerce.string()   // 모든 값 → 문자열
+z.coerce.number()   // 모든 값 → 숫자
+z.coerce.boolean()  // 모든 값 → 불리언
+z.coerce.date()     // 모든 값 → 날짜
+z.coerce.bigint()   // 모든 값 → BigInt
+
+z.coerce.number().parse("42")  // => 42
+z.coerce.date().parse("2021-01-01")  // => Date
+
+// v4: 입력 타입이 unknown으로 변경
+type In = z.input<typeof z.coerce.string()>  // unknown
+
+// v4 환경변수 불리언
+z.stringbool()  // "true"/"yes"/"1" → true, "false"/"no"/"0" → false
+
+// Preprocess
+const trimmed = z.preprocess(
+  (val) => typeof val === 'string' ? val.trim() : val,
+  z.string()
+)
+
+// 입력/출력 타입 분리
+const Schema = z.object({
+  createdAt: z.string().transform((str) => new Date(str)),
+})
+type SchemaInput = z.input<typeof Schema>   // { createdAt: string }
+type SchemaOutput = z.output<typeof Schema> // { createdAt: Date }
+```
+
+</patterns>

package/templates/nextjs/docs/library/zod/validation.md

@@ -0,0 +1,70 @@
+# Zod - 검증
+
+<patterns>
+
+```typescript
+// Refinement (v4: message → error)
+const PasswordSchema = z.string()
+  .min(8)
+  .refine((val) => /[A-Z]/.test(val), { error: '대문자 필수' })
+  .refine((val) => /[0-9]/.test(val), { error: '숫자 필수' })
+
+z.string().refine(val => val.includes("@")).min(5)  // v4: refinement 후 체이닝
+
+// Async
+const schema = z.string().refine(async (val) => val.length <= 8)
+await schema.parseAsync('hello')
+
+// Superrefine
+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'],
+    })
+  }
+})  // v4: ctx.path 사용 불가
+
+// 커스텀
+const px = z.custom<`${number}px`>((val) =>
+  typeof val === 'string' && /^\d+px$/.test(val)
+)
+px.parse('42px')  // ✅
+px.parse('42vw')  // throws
+
+// 에러 처리
+const result = schema.safeParse(data)
+if (!result.success) {
+  result.error.errors.forEach((err) => {
+    console.log(err.path, err.message, err.code)
+  })
+  const flat = result.error.flatten()  // { fieldErrors: { email: ['Invalid email'] } }
+}
+
+// TanStack Start
+export const createUser = createServerFn({ method: 'POST' })
+  .inputValidator(zodValidator(createUserSchema))
+  .handler(async ({ data }) => prisma.user.create({ data }))
+
+// 환경 변수
+const env = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']),
+  DATABASE_URL: z.string().url(),
+  API_SECRET: z.string().min(32),
+}).parse(process.env)
+
+// Middleware
+const workspaceMiddleware = createMiddleware({ type: 'function' })
+  .inputValidator(zodValidator(z.object({ workspaceId: z.string() })))
+  .server(({ next, data }) => next())
+
+// Zod Mini (v4)
+import * as z from "zod/mini"
+z.string().check(z.minLength(5), z.maxLength(10), z.trim())
+```
+
+</patterns>

package/templates/tanstack-start/CLAUDE.md

@@ -88,8 +88,9 @@
 src/
 ├── routes/          # __root.tsx, index.tsx, $slug.tsx
 │   └── [path]/
-│       ├── -components/  # 페이지 전용
-│       └── -functions/   # 페이지 전용 Server Functions
+│       ├── -components/  # 페이지 전용 (필수)
+│       ├── -hooks/       # 페이지 전용 Custom Hooks (필수)
+│       └── -functions/   # 페이지 전용 Server Functions (필수)
 ├── functions/       # 공통 Server Functions
 ├── components/ui/
 ├── middleware/
@@ -97,7 +98,10 @@ src/
 └── lib/
 ```
 
-공통 → `@/functions/`, 라우트 전용 → `routes/[경로]/-functions/`
+**필수 규칙:**
+- 페이지당 `-components/`, `-hooks/`, `-functions/` 폴더 필수 (줄 수 무관)
+- Custom Hook은 페이지 크기와 무관하게 **반드시** `-hooks/` 폴더에 분리
+- 공통 함수 → `@/functions/`, 라우트 전용 → `routes/[경로]/-functions/`
 </structure>
 
 ---

package/templates/tanstack-start/docs/architecture.md

@@ -159,27 +159,58 @@ routes/<route-name>/
 | **-components/** | 100-200줄 | 페이지 전용 컴포넌트 분리 |
 | **-sections/** | 200줄+ | 논리적 섹션 분리 |
 | **-tabs/** | 탭 UI | 탭 콘텐츠 분리 |
-| **_layout/** | Pathless | 공통 레이아웃 (URL 미영향) |
+| **route.tsx** | 레이아웃 | 하위 경로 공통 레이아웃 |
 
 #### Layout Routes 패턴
 
+> ⚠️ **route.tsx로 레이아웃 구성**
+>
+> `route.tsx`는 하위 경로의 공통 레이아웃 역할을 합니다.
+> `index.tsx`는 Route Group `()`으로 묶어야 합니다.
+>
+> **필수:** `route.tsx`는 반드시 `component`를 export해야 합니다.
+>
+> | ❌ 금지 | ✅ 필수 |
+> |--------|--------|
+> | `export const Route = createFileRoute(...)({})` | `export const Route = createFileRoute(...)({ component: ... })` |
+
 ```
 routes/
-├── (auth)/_layout/          # Pathless Layout
-│   ├── route.tsx            # <Outlet />
-│   ├── login.tsx            # /login
-│   └── register.tsx         # /register
+├── (auth)/
+│   ├── route.tsx           # 레이아웃 (<Outlet />)
+│   ├── (main)/
+│   │   └── index.tsx       # /auth (목록/메인)
+│   ├── login/
+│   │   └── index.tsx       # /auth/login
+│   └── register/
+│       └── index.tsx       # /auth/register
 ```
 
 ```typescript
-// routes/(auth)/_layout/route.tsx
-export const Route = createFileRoute('/(auth)/_layout')({
+// ❌ 금지: component 없음
+export const Route = createFileRoute('/(auth)')({
+  beforeLoad: async () => ({ user: await getUser() }),
+})
+
+// ✅ 필수: component 반드시 포함
+// routes/(auth)/route.tsx - 레이아웃
+export const Route = createFileRoute('/(auth)')({
   component: () => (
     <div className="auth-container">
       <Outlet />
     </div>
   ),
 })
+
+// routes/(auth)/(main)/index.tsx - 메인 페이지
+export const Route = createFileRoute('/(auth)/')({
+  component: AuthMainPage,
+})
+
+// routes/(auth)/login/index.tsx
+export const Route = createFileRoute('/(auth)/login')({
+  component: LoginPage,
+})
 ```
 
 ### 2. Services Layer

package/templates/tanstack-start/docs/guides/hooks.md

@@ -10,6 +10,34 @@
 
 ---
 
+<mandatory_separation>
+
+## ⚠️ 필수 규칙: Custom Hook 분리
+
+**모든 페이지는 Custom Hook을 `-hooks/` 폴더에 분리해야 합니다.**
+
+- 페이지 크기(줄 수)와 **무관**하게 반드시 분리
+- 10줄짜리 간단한 페이지도 Hook 분리 필수
+- 페이지 컴포넌트는 오직 UI 렌더링만 담당
+
+```typescript
+// ✅ 올바른 구조
+routes/users/
+├── index.tsx              // UI만
+├── -hooks/
+│   └── use-users.ts       // 모든 로직
+├── -components/
+└── -functions/
+
+// ❌ 잘못된 구조
+routes/users/
+└── index.tsx              // UI + 로직 혼재
+```
+
+</mandatory_separation>
+
+---
+
 <hook_order>
 
 ## Hook 내부 순서 (필수)

package/templates/tanstack-start/docs/guides/routes.md

@@ -19,12 +19,16 @@ routes/
 ├── users/
 │   ├── index.tsx        # /users (List)
 │   ├── $id.tsx          # /users/:id (Detail)
-│   ├── -components/     # 페이지 전용 컴포넌트
-│   ├── -sections/       # 섹션 분리 (복잡한 경우)
-│   └── -hooks/          # 페이지 전용 Hook
+│   ├── -components/     # 페이지 전용 컴포넌트 (필수)
+│   ├── -hooks/          # 페이지 전용 Hook (필수)
+│   ├── -functions/      # 페이지 전용 Server Functions (필수)
+│   └── -sections/       # 섹션 분리 (선택, 복잡한 경우만)
 └── posts/
     ├── index.tsx
-    └── $slug.tsx
+    ├── $slug.tsx
+    ├── -components/     # 필수
+    ├── -hooks/          # 필수
+    └── -functions/      # 필수
 ```
 
 | 접두사 | 용도 | 라우트 생성 |
@@ -33,6 +37,11 @@ routes/
 | `$` | 동적 파라미터 | ✅ 생성 |
 | `_` | Pathless Layout | ✅ 생성 (경로 없음) |
 
+**⚠️ 필수 규칙:**
+- 모든 페이지에 `-components/`, `-hooks/`, `-functions/` 폴더 **필수**
+- 페이지 크기(줄 수)와 **무관**하게 Custom Hook은 반드시 `-hooks/` 폴더에 분리
+- `-sections/`는 200줄 이상 복잡한 페이지에서만 선택적 사용
+
 </route_structure>
 
 ---
@@ -257,15 +266,25 @@ export const UserCard = ({
 
 ---
 
-<page_size_rules>
+<folder_structure_rules>
+
+## 폴더 구조 규칙
+
+**⚠️ 모든 페이지에 필수:**
+- `-components/`: 페이지 전용 컴포넌트
+- `-hooks/`: 페이지 전용 Custom Hook (줄 수 무관)
+- `-functions/`: 페이지 전용 Server Functions
+
+**선택적 사용:**
+- `-sections/`: 200줄+ 복잡한 페이지에서만 사용
 
-| 페이지 크기 | 구조 | 예시 |
+| 페이지 크기 | 필수 | 선택 |
 |------------|------|------|
-| ~100줄 | 단일 파일 | 간단한 페이지, 폼 |
-| 100-200줄 | `-components/` 분리 | 목록 + 필터 |
-| 200줄+ | `-sections/` + `-components/` | 대시보드, 복잡한 UI |
+| ~100줄 | `-components/`, `-hooks/`, `-functions/` | - |
+| 100-200줄 | `-components/`, `-hooks/`, `-functions/` | - |
+| 200줄+ | `-components/`, `-hooks/`, `-functions/` | `-sections/` |
 
-</page_size_rules>
+</folder_structure_rules>
 
 ---