@kood/claude-code 0.2.4 → 0.3.0

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

@@ -1,19 +1,35 @@
 # Custom Hook 패턴
 
-페이지/섹션의 모든 로직, 상태, 라이프사이클을 중앙화.
+> 페이지/섹션의 모든 로직, 상태, 라이프사이클 중앙화
 
-## 필수: Hook 내부 순서
+<instructions>
+@../library/tanstack-router/hooks.md
+@../library/tanstack-query/use-query.md
+@../library/tanstack-query/use-mutation.md
+</instructions>
 
-```
-1. State (useState, zustand store)
-2. Global Hooks (useParams, useNavigate, useQueryClient)
-3. React Query (useQuery → useMutation)
-4. Event Handlers & Functions
-5. useMemo
-6. useEffect
-```
+---
+
+<hook_order>
+
+## Hook 내부 순서 (필수)
+
+| 순서 | Hook 타입 | 예시 |
+|------|-----------|------|
+| 1 | State | `useState`, zustand store |
+| 2 | Global Hooks | `useParams`, `useNavigate`, `useQueryClient` |
+| 3 | React Query | `useQuery` → `useMutation` |
+| 4 | Event Handlers | `handleCreate`, `handleDelete` |
+| 5 | useMemo | 계산된 값 |
+| 6 | useEffect | 부수 효과 |
 
-## Page Hook 예시
+</hook_order>
+
+---
+
+<patterns>
+
+## Page Hook 패턴
 
 ```typescript
 // routes/users/-hooks/use-users.ts
@@ -28,13 +44,10 @@ interface UseUsersReturn {
   users: User[] | undefined
   filteredUsers: User[]
   isLoading: boolean
-  error: Error | null
   search: string
   setSearch: (value: string) => void
   handleCreate: (data: { email: string; name: string }) => void
   handleDelete: (id: string) => void
-  isCreating: boolean
-  isDeleting: boolean
 }
 
 export const useUsers = (): UseUsersReturn => {
@@ -54,7 +67,7 @@ export const useUsers = (): UseUsersReturn => {
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   // 3. React Query
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  const { data: users, isLoading, error } = useQuery({
+  const { data: users, isLoading } = useQuery({
     queryKey: ['users'],
     queryFn: () => getUsers(),
   })
@@ -110,35 +123,15 @@ export const useUsers = (): UseUsersReturn => {
     users,
     filteredUsers,
     isLoading,
-    error,
     search,
     setSearch,
     handleCreate,
     handleDelete,
-    isCreating: createMutation.isPending,
-    isDeleting: deleteMutation.isPending,
   }
 }
 ```
 
-## 잘못된 순서 (금지)
-
-```typescript
-// ❌ 순서가 뒤섞인 잘못된 예시
-export const useBadHook = () => {
-  const queryClient = useQueryClient()  // ❌ Global Hook이 먼저
-
-  useEffect(() => { /* ... */ }, [])    // ❌ useEffect가 중간에
-
-  const [state, setState] = useState()  // ❌ State가 나중에
-
-  const { data } = useQuery({ /* ... */ })  // ❌ Query가 Effect 다음에
-
-  const computed = useMemo(() => {}, [])  // ❌ useMemo 위치 잘못됨
-}
-```
-
-## Filter Hook 예시
+## Filter Hook 패턴
 
 ```typescript
 // routes/users/-hooks/use-user-filter.ts
@@ -164,3 +157,215 @@ export const useUserFilter = (): UseUserFilterReturn => {
   return { search, setSearch, role, setRole, clearFilters }
 }
 ```
+
+## Form Hook 패턴
+
+```typescript
+// routes/users/-hooks/use-user-form.ts
+import { useState } from 'react'
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { createUser } from '@/services/user'
+import type { CreateUserInput } from '@/services/user'
+
+interface UseUserFormReturn {
+  email: string
+  setEmail: (value: string) => void
+  name: string
+  setName: (value: string) => void
+  handleSubmit: (e: React.FormEvent) => void
+  isSubmitting: boolean
+  error: Error | null
+}
+
+export const useUserForm = (): UseUserFormReturn => {
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 1. State
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const [email, setEmail] = useState('')
+  const [name, setName] = useState('')
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 2. Global Hooks
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const queryClient = useQueryClient()
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 3. React Query
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const { mutate, isPending, error } = useMutation({
+    mutationFn: createUser,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] })
+      setEmail('')
+      setName('')
+    },
+  })
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // 4. Event Handlers
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    mutate({ data: { email, name } })
+  }
+
+  return {
+    email,
+    setEmail,
+    name,
+    setName,
+    handleSubmit,
+    isSubmitting: isPending,
+    error,
+  }
+}
+```
+
+</patterns>
+
+---
+
+<anti_patterns>
+
+## ❌ 잘못된 순서
+
+```typescript
+// ❌ 순서가 뒤섞인 잘못된 예시
+export const useBadHook = () => {
+  const queryClient = useQueryClient()  // ❌ Global Hook이 먼저
+
+  useEffect(() => { /* ... */ }, [])    // ❌ useEffect가 중간에
+
+  const [state, setState] = useState()  // ❌ State가 나중에
+
+  const { data } = useQuery({ /* ... */ })  // ❌ Query가 Effect 다음에
+
+  const computed = useMemo(() => {}, [])  // ❌ useMemo 위치 잘못됨
+}
+```
+
+## ✅ 올바른 순서
+
+```typescript
+export const useGoodHook = () => {
+  // 1. State
+  const [state, setState] = useState()
+
+  // 2. Global Hooks
+  const queryClient = useQueryClient()
+
+  // 3. React Query
+  const { data } = useQuery({ /* ... */ })
+
+  // 4. Event Handlers
+  const handleClick = useCallback(() => {}, [])
+
+  // 5. useMemo
+  const computed = useMemo(() => {}, [])
+
+  // 6. useEffect
+  useEffect(() => { /* ... */ }, [])
+
+  return { state, data, handleClick, computed }
+}
+```
+
+</anti_patterns>
+
+---
+
+<router_hooks>
+
+## TanStack Router Hooks
+
+| Hook | 용도 | 예시 |
+|------|------|------|
+| `useParams` | URL 파라미터 | `const { id } = useParams({ from: '/users/$id' })` |
+| `useNavigate` | 프로그래밍 방식 네비게이션 | `navigate({ to: '/users' })` |
+| `useSearch` | Search params | `const { page } = useSearch({ from: '/users' })` |
+| `useLoaderData` | Loader 데이터 | `const user = Route.useLoaderData()` |
+| `useRouteContext` | Route context | `const { auth } = useRouteContext({ from: '__root__' })` |
+
+```typescript
+// routes/users/$id.tsx Hook
+import { useParams, useNavigate, useLoaderData } from '@tanstack/react-router'
+
+export const useUserDetail = () => {
+  const { id } = useParams({ from: '/users/$id' })
+  const navigate = useNavigate()
+  const user = Route.useLoaderData()
+
+  const handleBack = () => navigate({ to: '/users' })
+  const handleEdit = () => navigate({ to: '/users/$id/edit', params: { id } })
+
+  return {
+    user,
+    handleBack,
+    handleEdit,
+  }
+}
+```
+
+</router_hooks>
+
+---
+
+<query_hooks>
+
+## TanStack Query Hooks
+
+| Hook | 용도 | 특징 |
+|------|------|------|
+| `useQuery` | 데이터 조회 (GET) | 자동 캐싱, 재검증 |
+| `useMutation` | 데이터 변경 (POST/PUT/DELETE) | 성공 시 캐시 무효화 |
+| `useQueryClient` | 캐시 제어 | `invalidateQueries`, `setQueryData` |
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { getUsers, createUser } from '@/services/user'
+
+export const useUsers = () => {
+  const queryClient = useQueryClient()
+
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['users'],
+    queryFn: () => getUsers(),
+    staleTime: 60 * 1000,  // 1분
+  })
+
+  const { mutate, isPending } = useMutation({
+    mutationFn: createUser,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] })
+    },
+  })
+
+  return { data, isLoading, error, mutate, isPending }
+}
+```
+
+</query_hooks>
+
+---
+
+<best_practices>
+
+| 원칙 | 설명 |
+|------|------|
+| **순서 준수** | State → Global → Query → Handlers → Memo → Effect |
+| **타입 정의** | Return 타입 명시 (interface) |
+| **단일 책임** | 하나의 Hook은 하나의 관심사 |
+| **useCallback** | Event handler는 useCallback으로 메모이제이션 |
+| **명확한 네이밍** | `use-users.ts`, `use-user-filter.ts` |
+
+</best_practices>
+
+---
+
+<sources>
+
+- [TanStack Router Hooks](https://tanstack.com/router/latest/docs/framework/react/guide/router-hooks)
+- [TanStack Query useQuery](https://tanstack.com/query/latest/docs/framework/react/guides/queries)
+- [TanStack Query useMutation](https://tanstack.com/query/latest/docs/framework/react/guides/mutations)
+
+</sources>

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

@@ -1,38 +1,63 @@
 # 라우트 구조
 
-TanStack Start 파일 기반 라우팅 패턴.
+> TanStack Start 파일 기반 라우팅
 
-## Route 폴더 구조
+<instructions>
+@../library/tanstack-router/index.md
+</instructions>
 
-```
-routes/<route-name>/
-├── index.tsx              # 페이지 컴포넌트
-├── route.tsx              # route 설정 (필요시)
-├── -components/           # 페이지 전용 컴포넌트
-│   ├── user-card.tsx
-│   └── user-form.tsx
-├── -sections/             # 섹션 분리 (복잡한 경우)
-│   ├── user-list-section.tsx
-│   └── user-filter-section.tsx
-└── -hooks/                # 페이지 전용 훅
-    ├── use-users.ts
-    └── use-user-filter.ts
-```
+---
 
-## `-` 접두사
+<route_structure>
 
-`-` 접두사가 있는 폴더는 라우트에서 제외:
+## 라우트 폴더 구조
 
 ```
-routes/users/
-├── index.tsx          # /users ✅ 라우트
-├── $id.tsx            # /users/:id ✅ 라우트
-├── -components/       # ❌ 라우트 아님
-├── -sections/         # ❌ 라우트 아님
-└── -hooks/            # ❌ 라우트 아님
+routes/
+├── __root.tsx           # Root Layout
+├── index.tsx            # / (Home)
+├── users/
+│   ├── index.tsx        # /users (List)
+│   ├── $id.tsx          # /users/:id (Detail)
+│   ├── -components/     # 페이지 전용 컴포넌트
+│   ├── -sections/       # 섹션 분리 (복잡한 경우)
+│   └── -hooks/          # 페이지 전용 Hook
+└── posts/
+    ├── index.tsx
+    └── $slug.tsx
 ```
 
-## 기본 Route 패턴
+| 접두사 | 용도 | 라우트 생성 |
+|--------|------|-----------|
+| `-` | 라우트 제외 폴더 | ❌ 제외 |
+| `$` | 동적 파라미터 | ✅ 생성 |
+| `_` | Pathless Layout | ✅ 생성 (경로 없음) |
+
+</route_structure>
+
+---
+
+<file_naming>
+
+## 라우트 파일명 규칙
+
+| 경로 | 파일명 | 설명 |
+|------|--------|------|
+| `/` | `index.tsx` | 인덱스 라우트 |
+| `/users` | `users/index.tsx` | 목록 페이지 |
+| `/users/:id` | `users/$id.tsx` | 동적 파라미터 |
+| `/posts/:slug` | `posts/$slug.tsx` | URL 파라미터 |
+| `/dashboard/*` | `dashboard/$.tsx` | Catch-all 라우트 |
+| Layout | `__root.tsx` | Root 레이아웃 |
+| Pathless | `_layout.tsx` | 경로 없는 레이아웃 |
+
+</file_naming>
+
+---
+
+<patterns>
+
+## 기본 라우트 패턴
 
 ```tsx
 // routes/users/index.tsx
@@ -55,6 +80,105 @@ const UsersPage = (): JSX.Element => {
 }
 ```
 
+## 동적 라우트 + Loader
+
+```tsx
+// routes/users/$id.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { getUserById } from '@/services/user'
+
+export const Route = createFileRoute('/users/$id')({
+  loader: ({ params: { id } }) => getUserById({ data: id }),
+  component: UserDetailPage,
+})
+
+const UserDetailPage = (): JSX.Element => {
+  const user = Route.useLoaderData()
+
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <p>{user.email}</p>
+    </div>
+  )
+}
+```
+
+## Loader with Dependencies
+
+```tsx
+// routes/posts/index.tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { getPosts } from '@/services/post'
+import { z } from 'zod'
+
+const postsSearchSchema = z.object({
+  offset: z.number().default(0),
+  limit: z.number().default(10),
+})
+
+export const Route = createFileRoute('/posts/')({
+  validateSearch: postsSearchSchema,
+  loaderDeps: ({ search: { offset, limit } }) => ({ offset, limit }),
+  loader: ({ deps: { offset, limit } }) => getPosts({ data: { offset, limit } }),
+  component: PostsPage,
+})
+
+const PostsPage = (): JSX.Element => {
+  const posts = Route.useLoaderData()
+  const { offset, limit } = Route.useSearch()
+
+  return (
+    <div>
+      <h1>Posts (offset: {offset}, limit: {limit})</h1>
+      {posts.map((post) => (
+        <div key={post.id}>{post.title}</div>
+      ))}
+    </div>
+  )
+}
+```
+
+## Deferred Data Loading
+
+```tsx
+// routes/dashboard/index.tsx
+import { createFileRoute, Await } from '@tanstack/react-router'
+import { Suspense } from 'react'
+import { getFastData, getSlowData } from '@/services/dashboard'
+
+export const Route = createFileRoute('/dashboard/')({
+  loader: async () => {
+    const slowDataPromise = getSlowData()
+    const fastData = await getFastData()
+
+    return {
+      fastData,
+      deferredSlowData: slowDataPromise,
+    }
+  },
+  component: DashboardPage,
+})
+
+const DashboardPage = (): JSX.Element => {
+  const { fastData, deferredSlowData } = Route.useLoaderData()
+
+  return (
+    <div>
+      <h1>Fast Data</h1>
+      <pre>{JSON.stringify(fastData, null, 2)}</pre>
+
+      <h1>Slow Data (Deferred)</h1>
+      <Suspense fallback={<div>Loading slow data...</div>}>
+        <Await promise={deferredSlowData}>
+          {(slowData) => <pre>{JSON.stringify(slowData, null, 2)}</pre>}
+        </Await>
+      </Suspense>
+    </div>
+  )
+}
+```
+
 ## Section 패턴
 
 ```tsx
@@ -84,42 +208,6 @@ export const UserListSection = (): JSX.Element => {
 }
 ```
 
-## Filter Section 패턴
-
-```tsx
-// routes/users/-sections/user-filter-section.tsx
-import { useUserFilter } from '../-hooks/use-user-filter'
-import { Input } from '@/components/ui/input'
-import { Button } from '@/components/ui/button'
-
-export const UserFilterSection = (): JSX.Element => {
-  const { search, setSearch, role, setRole, clearFilters } = useUserFilter()
-
-  return (
-    <div className="flex gap-4 mb-6">
-      <Input
-        placeholder="Search users..."
-        value={search}
-        onChange={(e) => setSearch(e.target.value)}
-        className="max-w-xs"
-      />
-      <select
-        value={role}
-        onChange={(e) => setRole(e.target.value)}
-        className="border rounded px-3 py-2"
-      >
-        <option value="">All Roles</option>
-        <option value="USER">User</option>
-        <option value="ADMIN">Admin</option>
-      </select>
-      <Button variant="outline" onClick={clearFilters}>
-        Clear
-      </Button>
-    </div>
-  )
-}
-```
-
 ## 컴포넌트 패턴
 
 ```tsx
@@ -164,3 +252,67 @@ export const UserCard = ({
   )
 }
 ```
+
+</patterns>
+
+---
+
+<page_size_rules>
+
+| 페이지 크기 | 구조 | 예시 |
+|------------|------|------|
+| ~100줄 | 단일 파일 | 간단한 페이지, 폼 |
+| 100-200줄 | `-components/` 분리 | 목록 + 필터 |
+| 200줄+ | `-sections/` + `-components/` | 대시보드, 복잡한 UI |
+
+</page_size_rules>
+
+---
+
+<loader_execution>
+
+## Loader 실행 순서
+
+| 단계 | 실행 방식 | 설명 |
+|------|----------|------|
+| 1. `beforeLoad` | 순차 (outermost → innermost) | 인증 체크, 컨텍스트 설정 |
+| 2. `loader` | 병렬 (모든 loader 동시) | 데이터 페칭 |
+
+```tsx
+// Parent Route
+export const Route = createFileRoute('/dashboard')({
+  beforeLoad: async () => {
+    // 1. 먼저 실행 (순차)
+    const auth = await checkAuth()
+    return { auth }
+  },
+  loader: async () => {
+    // 2. 나중에 실행 (병렬)
+    return getDashboardData()
+  },
+})
+
+// Child Route
+export const Route = createFileRoute('/dashboard/users')({
+  beforeLoad: async () => {
+    // 1. Parent beforeLoad 다음 실행
+    return {}
+  },
+  loader: async () => {
+    // 2. Parent loader와 병렬 실행
+    return getUsers()
+  },
+})
+```
+
+</loader_execution>
+
+---
+
+<sources>
+
+- [TanStack Router Data Loading](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading)
+- [TanStack Router Deferred Data Loading](https://tanstack.com/router/latest/docs/framework/react/guide/deferred-data-loading)
+- [TanStack Router File-Based Routing](https://tanstack.com/router/latest/docs/framework/react/guide/file-based-routing)
+
+</sources>