@kood/claude-code 0.6.5 → 0.6.7

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/client-optimistic-updates.md

@@ -0,0 +1,109 @@
+---
+title: Use useOptimistic for Instant UI Feedback
+impact: MEDIUM-HIGH
+impactDescription: eliminates perceived latency on mutations
+tags: client, react-19, useOptimistic, mutations, optimistic-ui
+---
+
+## useOptimistic으로 즉각적인 UI 피드백
+
+React 19의 `useOptimistic`으로 서버 응답 대기 없이 UI를 즉시 업데이트하고, 실패 시 자동 롤백합니다.
+
+**❌ 잘못된 예시 (서버 응답까지 대기):**
+
+```tsx
+function TodoList({ todos }: { todos: Todo[] }) {
+  const mutation = useMutation({
+    mutationFn: createTodo,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] })
+  })
+
+  return (
+    <form onSubmit={(e) => {
+      e.preventDefault()
+      mutation.mutate({ title: inputValue })
+      // 사용자는 서버 응답까지 기다려야 아이템을 볼 수 있음
+    }}>
+      {mutation.isPending && <Spinner />}
+      {todos.map(todo => <TodoItem key={todo.id} todo={todo} />)}
+    </form>
+  )
+}
+```
+
+**✅ 올바른 예시 (useOptimistic으로 즉시 반영):**
+
+```tsx
+import { useOptimistic, startTransition } from 'react'
+
+function TodoList({ todos }: { todos: Todo[] }) {
+  const [optimisticTodos, addOptimistic] = useOptimistic(
+    todos,
+    (current, newTodo: Todo) => [...current, { ...newTodo, pending: true }]
+  )
+
+  const handleAdd = async (formData: FormData) => {
+    const newTodo = {
+      id: crypto.randomUUID(),
+      title: formData.get('title') as string,
+      completed: false
+    }
+
+    startTransition(async () => {
+      addOptimistic(newTodo) // 즉시 UI에 반영
+      await createTodo({ data: newTodo }) // 서버에 저장
+      // 실패 시 자동으로 이전 상태로 롤백
+    })
+  }
+
+  return (
+    <form action={handleAdd}>
+      <input name="title" />
+      <button type="submit">추가</button>
+      {optimisticTodos.map(todo => (
+        <TodoItem
+          key={todo.id}
+          todo={todo}
+          style={{ opacity: todo.pending ? 0.5 : 1 }}
+        />
+      ))}
+    </form>
+  )
+}
+```
+
+**TanStack Query와 조합:**
+
+```tsx
+function LikeButton({ postId, liked, count }: Props) {
+  const [optimistic, setOptimistic] = useOptimistic(
+    { liked, count },
+    (curr) => ({
+      liked: !curr.liked,
+      count: curr.liked ? curr.count - 1 : curr.count + 1
+    })
+  )
+
+  const mutation = useMutation({
+    mutationFn: () => toggleLike({ data: { postId } }),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['post', postId] })
+  })
+
+  return (
+    <button onClick={() => {
+      startTransition(async () => {
+        setOptimistic(null)
+        await mutation.mutateAsync()
+      })
+    }}>
+      {optimistic.liked ? '❤️' : '🤍'} {optimistic.count}
+    </button>
+  )
+}
+```
+
+**사용 시점:** 좋아요/투표, 댓글 추가, 장바구니 아이템 추가/삭제, 토글 스위치 등 사용자가 즉각적인 피드백을 기대하는 모든 액션.
+
+**주의:** `startTransition` 내에서 사용해야 자동 롤백이 작동합니다.
+
+참고: [React 19 useOptimistic](https://react.dev/reference/react/useOptimistic)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/client-suspense-query.md

@@ -0,0 +1,74 @@
+---
+title: Use useSuspenseQuery for Declarative Data Loading
+impact: MEDIUM-HIGH
+impactDescription: eliminates loading state boilerplate
+tags: client, tanstack-query, suspense, data-fetching
+---
+
+## useSuspenseQuery로 선언적 데이터 로딩
+
+TanStack Query v5의 `useSuspenseQuery`는 Suspense를 기본 지원하여 로딩/에러 상태 보일러플레이트를 제거합니다.
+
+**❌ 잘못된 예시 (수동 로딩/에러 처리):**
+
+```tsx
+import { useQuery } from '@tanstack/react-query'
+
+function UserProfile({ userId }: { userId: string }) {
+  const { data: user, isLoading, error } = useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => getUser({ data: { id: userId } })
+  })
+
+  if (isLoading) return <UserSkeleton />
+  if (error) return <ErrorMessage error={error} />
+  if (!user) return null
+
+  return <div>{user.name}</div>
+}
+```
+
+**✅ 올바른 예시 (Suspense + ErrorBoundary):**
+
+```tsx
+import { useSuspenseQuery } from '@tanstack/react-query'
+import { Suspense } from 'react'
+import { ErrorBoundary } from 'react-error-boundary'
+
+function UserProfile({ userId }: { userId: string }) {
+  // data는 항상 존재 (undefined 아님), 타입 안전
+  const { data: user } = useSuspenseQuery({
+    queryKey: ['user', userId],
+    queryFn: () => getUser({ data: { id: userId } })
+  })
+
+  return <div>{user.name}</div>
+}
+
+// 부모에서 Suspense + ErrorBoundary로 감싸기
+function UserPage({ userId }: { userId: string }) {
+  return (
+    <ErrorBoundary fallback={<ErrorMessage />}>
+      <Suspense fallback={<UserSkeleton />}>
+        <UserProfile userId={userId} />
+      </Suspense>
+    </ErrorBoundary>
+  )
+}
+```
+
+**장점:**
+- `data`가 `undefined`가 아닌 확정 타입 (타입 가드 불필요)
+- 로딩/에러 처리가 컴포넌트 트리 상위로 위임 (관심사 분리)
+- 여러 쿼리의 로딩 상태를 하나의 Suspense로 통합 가능
+
+**TanStack Query v5 주요 변경 (v4 대비):**
+
+| v4 | v5 |
+|----|-----|
+| `cacheTime` | `gcTime` |
+| `keepPreviousData` | `placeholderData` |
+| `isLoading` | `isPending` |
+| `useSuspenseQuery` (실험적) | `useSuspenseQuery` (안정적) |
+
+참고: [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/client-use-hook.md

@@ -0,0 +1,81 @@
+---
+title: Use React 19 use() Hook for Promise Handling
+impact: MEDIUM
+impactDescription: replaces useEffect fetch patterns
+tags: client, react-19, use-hook, promises, suspense
+---
+
+## React 19 use() Hook으로 Promise 처리
+
+React 19의 `use()` 훅은 렌더링 중 Promise를 읽어 Suspense와 자동 통합됩니다. `useEffect` + `useState` 조합을 대체합니다.
+
+**❌ 잘못된 예시 (useEffect + useState 패턴):**
+
+```tsx
+function Comments({ postId }: { postId: string }) {
+  const [comments, setComments] = useState<Comment[] | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<Error | null>(null)
+
+  useEffect(() => {
+    setLoading(true)
+    getComments({ data: { postId } })
+      .then(setComments)
+      .catch(setError)
+      .finally(() => setLoading(false))
+  }, [postId])
+
+  if (loading) return <CommentsSkeleton />
+  if (error) return <ErrorMessage error={error} />
+  return <CommentList comments={comments!} />
+}
+```
+
+**✅ 올바른 예시 (use() + Suspense):**
+
+```tsx
+import { use, Suspense } from 'react'
+import { ErrorBoundary } from 'react-error-boundary'
+
+function Comments({ commentsPromise }: { commentsPromise: Promise<Comment[]> }) {
+  const comments = use(commentsPromise)
+  return <CommentList comments={comments} />
+}
+
+// 부모에서 Promise 전달
+function PostPage() {
+  const { post, deferredComments } = Route.useLoaderData()
+
+  return (
+    <div>
+      <PostContent post={post} />
+      <ErrorBoundary fallback={<ErrorMessage />}>
+        <Suspense fallback={<CommentsSkeleton />}>
+          <Comments commentsPromise={deferredComments} />
+        </Suspense>
+      </ErrorBoundary>
+    </div>
+  )
+}
+```
+
+**use()로 Context 읽기:**
+
+```tsx
+// 조건부 Context 읽기 (useContext와 달리 조건부 호출 가능)
+function ThemeButton({ override }: { override?: Theme }) {
+  if (override) return <Button theme={override} />
+
+  const theme = use(ThemeContext)
+  return <Button theme={theme} />
+}
+```
+
+**use() 사용 규칙:**
+- ✅ 조건문/루프 내에서 호출 가능 (일반 Hook과 다름)
+- ❌ 컴포넌트 내에서 `new Promise()` 생성 후 전달 금지 (매 렌더링마다 재생성)
+- ✅ loader, server function, 부모 컴포넌트에서 생성된 Promise 전달
+
+**TanStack Start와 조합:** loader에서 deferred Promise를 반환하고, 컴포넌트에서 `use()` 또는 `<Await>`로 처리합니다. 두 패턴 모두 유효하며, `<Await>`가 TanStack Router의 공식 패턴입니다.
+
+참고: [React use() API](https://react.dev/reference/react/use)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/rerender-react-compiler.md

@@ -0,0 +1,81 @@
+---
+title: Leverage React Compiler for Automatic Memoization
+impact: MEDIUM
+impactDescription: eliminates manual memo/useMemo/useCallback
+tags: rerender, react-compiler, memoization, react-19
+---
+
+## React Compiler로 자동 메모이제이션
+
+React Compiler가 활성화되어 있다면 `memo()`, `useMemo()`, `useCallback()`을 수동으로 작성할 필요가 없습니다. 컴파일러가 빌드 타임에 자동으로 최적화합니다.
+
+**React Compiler 없을 때 (수동 메모이제이션):**
+
+```tsx
+import { memo, useMemo, useCallback } from 'react'
+
+const UserList = memo(function UserList({ users, onSelect }: Props) {
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+
+  const handleSelect = useCallback((id: string) => {
+    onSelect(id)
+  }, [onSelect])
+
+  return (
+    <ul>
+      {sorted.map(user => (
+        <UserItem key={user.id} user={user} onSelect={handleSelect} />
+      ))}
+    </ul>
+  )
+})
+```
+
+**React Compiler 있을 때 (자동 최적화):**
+
+```tsx
+function UserList({ users, onSelect }: Props) {
+  const sorted = users.toSorted((a, b) => a.name.localeCompare(b.name))
+
+  const handleSelect = (id: string) => {
+    onSelect(id)
+  }
+
+  return (
+    <ul>
+      {sorted.map(user => (
+        <UserItem key={user.id} user={user} onSelect={handleSelect} />
+      ))}
+    </ul>
+  )
+  // Compiler가 자동으로 memo, useMemo, useCallback 삽입
+}
+```
+
+**Compiler 활성화 확인:**
+
+```typescript
+// vite.config.ts (TanStack Start)
+import { defineConfig } from '@tanstack/react-start/config'
+
+export default defineConfig({
+  react: {
+    babel: {
+      plugins: [['babel-plugin-react-compiler', {}]]
+    }
+  }
+})
+```
+
+**수동 메모이제이션이 여전히 필요한 경우:**
+- React Compiler가 비활성화된 프로젝트
+- 써드파티 라이브러리가 `===` 참조 비교를 요구하는 경우
+- Effect 의존성에 대한 정확한 제어가 필요한 경우
+- 함수형 setState는 정확성(stale closure 방지)을 위해 Compiler와 무관하게 권장
+
+**성능:** Meta 프로덕션에서 평균 12% 더 빠른 로드, 2.5배 빠른 상호작용 측정.
+
+참고: [React Compiler](https://react.dev/learn/react-compiler)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/routing-beforeload-auth.md

@@ -0,0 +1,121 @@
+---
+title: Use beforeLoad for Authentication Guards
+impact: HIGH
+impactDescription: prevents unauthorized access before data loading
+tags: routing, beforeLoad, authentication, redirect, guards
+---
+
+## beforeLoad로 인증 가드 구현
+
+`beforeLoad`는 loader보다 먼저 순차 실행되며, 인증 체크/리다이렉트에 최적입니다. Pathless layout(`_prefix`)과 조합하면 하위 라우트 전체를 보호합니다.
+
+**❌ 잘못된 예시 (loader에서 인증 체크):**
+
+```tsx
+export const Route = createFileRoute('/dashboard')({
+  loader: async () => {
+    const user = await getSession()
+    if (!user) throw redirect({ to: '/login' })  // 데이터 로딩 후 체크 (늦음)
+    const data = await fetchDashboard(user.id)
+    return { data }
+  },
+})
+```
+
+**✅ 올바른 예시 (beforeLoad + pathless layout):**
+
+```tsx
+// src/routes/_authenticated.tsx - 인증 가드 레이아웃
+import { createFileRoute, redirect, Outlet } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_authenticated')({
+  beforeLoad: async ({ location }) => {
+    const user = await verifySession()
+
+    if (!user) {
+      throw redirect({
+        to: '/login',
+        search: { redirect: location.href },  // 원래 위치 보존
+      })
+    }
+
+    return { user }  // context로 하위 라우트에 전달
+  },
+  component: () => <Outlet />,
+})
+
+// src/routes/_authenticated/dashboard.tsx - 보호된 라우트
+export const Route = createFileRoute('/_authenticated/dashboard')({
+  loader: async ({ context }) => {
+    // context.user는 beforeLoad에서 타입 안전하게 전달됨
+    return { stats: await fetchDashboard(context.user.id) }
+  },
+  component: Dashboard,
+})
+
+function Dashboard() {
+  const { stats } = Route.useLoaderData()
+  return <DashboardView stats={stats} />
+}
+```
+
+**실행 순서:**
+
+```
+1. Root.beforeLoad()            ← 순차 실행
+2. _authenticated.beforeLoad()  ← 인증 실패 시 여기서 redirect
+3. Dashboard.beforeLoad()       ← 인증 통과 후 실행
+4. Root.loader()                ← 모든 loader 병렬 실행
+5. _authenticated.loader()
+6. Dashboard.loader()
+```
+
+**beforeLoad vs loader:**
+
+| 항목 | beforeLoad | loader |
+|------|-----------|--------|
+| 실행 | 순차 (부모→자식) | 병렬 (모든 라우트 동시) |
+| 시점 | loader 전 | beforeLoad 후 |
+| 용도 | 인증, 리다이렉트, context 설정 | 데이터 페칭 |
+| 반환값 | context 객체 (하위 라우트 접근 가능) | 라우트 데이터 |
+| 성능 | 가볍게 유지 (모든 네비게이션에서 실행) | 무거운 작업 가능 |
+
+**선택적 인증 (인증 없어도 페이지 렌더링):**
+
+```tsx
+export const Route = createFileRoute('/profile')({
+  beforeLoad: async () => {
+    try {
+      const user = await verifySession()
+      return { user }
+    } catch {
+      return { user: null }  // 리다이렉트 없이 null 반환
+    }
+  },
+  component: Profile,
+})
+
+function Profile() {
+  const { user } = Route.useRouteContext()
+  return user ? <UserProfile user={user} /> : <LoginPrompt />
+}
+```
+
+**redirect에서 isRedirect 사용:**
+
+```tsx
+import { redirect, isRedirect } from '@tanstack/react-router'
+
+beforeLoad: async ({ location }) => {
+  try {
+    const user = await verifySession()
+    if (!user) throw redirect({ to: '/login' })
+    return { user }
+  } catch (error) {
+    if (isRedirect(error)) throw error  // redirect는 그대로 전파
+    throw redirect({ to: '/login' })    // 다른 에러도 로그인으로
+  }
+}
+```
+
+참고: [Authenticated Routes](https://tanstack.com/router/latest/docs/framework/react/guide/authenticated-routes)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/routing-file-conventions.md

@@ -0,0 +1,104 @@
+---
+title: Follow File-Based Routing Conventions
+impact: HIGH
+impactDescription: ensures correct route generation and code splitting
+tags: routing, file-conventions, file-based-routing, code-splitting
+---
+
+## 파일 기반 라우팅 컨벤션
+
+TanStack Router의 파일 이름 컨벤션을 따르면 라우트 트리가 자동 생성됩니다.
+
+**파일 이름 규칙:**
+
+| 패턴 | 파일명 | URL | 설명 |
+|------|--------|-----|------|
+| **Root** | `__root.tsx` | - | 앱 최상위 레이아웃 (필수) |
+| **Index** | `index.tsx` | `/` | 디렉토리 인덱스 |
+| **Static** | `about.tsx` | `/about` | 정적 경로 |
+| **Dynamic** | `$postId.tsx` | `/posts/:postId` | 동적 파라미터 |
+| **Pathless Layout** | `_layout.tsx` | - | URL 없는 레이아웃 래퍼 |
+| **Route Group** | `(group)/` | - | 파일 정리용 (URL 영향 없음) |
+| **Excluded** | `-helpers.tsx` | - | 라우트 생성 제외 |
+| **Lazy** | `route.lazy.tsx` | - | 코드 스플릿 컴포넌트 |
+
+**디렉토리 구조 예시:**
+
+```
+src/routes/
+├── __root.tsx                 # 루트 레이아웃 (필수)
+├── index.tsx                  # / (홈)
+├── about.tsx                  # /about
+├── posts.tsx                  # /posts (레이아웃)
+├── posts/
+│   ├── index.tsx              # /posts (목록)
+│   └── $postId.tsx            # /posts/:postId
+├── _authenticated.tsx         # pathless 인증 가드
+├── _authenticated/
+│   ├── dashboard.tsx          # /dashboard
+│   └── settings.tsx           # /settings
+├── (marketing)/               # route group (정리용)
+│   ├── pricing.tsx            # /pricing
+│   └── features.tsx           # /features
+└── -components/               # 제외 (라우트 아님)
+    └── Sidebar.tsx
+```
+
+**코드 스플리팅 (lazy route):**
+
+```tsx
+// src/routes/posts.$postId.tsx - 크리티컬 설정만
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    return { post: await fetchPost(params.postId) }
+  },
+  validateSearch: zodValidator(searchSchema),
+  beforeLoad: async ({ context }) => { /* auth */ },
+})
+
+// src/routes/posts.$postId.lazy.tsx - 컴포넌트만 (코드 스플릿)
+import { createLazyFileRoute } from '@tanstack/react-router'
+
+export const Route = createLazyFileRoute('/posts/$postId')({
+  component: PostDetail,
+  pendingComponent: PostSkeleton,
+  errorComponent: PostError,
+})
+```
+
+**Flat vs Directory 스타일:**
+
+```
+# Flat (점 구분자)
+posts.tsx                → /posts
+posts.index.tsx          → /posts (index)
+posts.$postId.tsx        → /posts/:postId
+
+# Directory (폴더)
+posts/
+  route.tsx              → /posts
+  index.tsx              → /posts (index)
+  $postId.tsx            → /posts/:postId
+```
+
+**tsr.config.json 설정:**
+
+```json
+{
+  "routesDirectory": "./src/routes",
+  "generatedRouteTree": "./src/routeTree.gen.ts",
+  "routeFileIgnorePrefix": "-",
+  "indexToken": "index",
+  "routeToken": "route"
+}
+```
+
+**주의사항:**
+- `routeTree.gen.ts`는 자동 생성 파일 → 직접 수정 금지
+- `__root.tsx`는 반드시 존재해야 함
+- `_prefix`는 pathless layout, `(group)`은 정리 전용 (레이아웃 불가)
+- lazy 파일에는 `loader`, `beforeLoad`, `validateSearch` 넣지 않음
+
+참고: [File-Based Routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing), [File Naming Conventions](https://tanstack.com/router/latest/docs/framework/react/routing/file-naming-conventions)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/routing-link-navigation.md

@@ -0,0 +1,119 @@
+---
+title: Use Link Component and useNavigate for Type-Safe Navigation
+impact: HIGH
+impactDescription: type-safe navigation prevents runtime route errors
+tags: routing, navigation, link, useNavigate, type-safety
+---
+
+## Link와 useNavigate로 타입 안전한 네비게이션
+
+TanStack Router는 `<Link>`(선언적)와 `useNavigate()`(명령적) 두 가지 네비게이션 방식을 제공합니다. 모든 라우트 경로, params, search가 자동 타입 추론됩니다.
+
+**❌ 잘못된 예시 (타입 안전성 없는 네비게이션):**
+
+```tsx
+// 문자열 하드코딩 - 오타 감지 불가
+<a href="/posts/123">Post</a>
+
+// useNavigate에서 from 없이 사용
+const navigate = useNavigate()
+navigate({ to: '/posts/$postId', params: { postId: '123' } })
+```
+
+**✅ 올바른 예시 (Link 컴포넌트):**
+
+```tsx
+import { Link } from '@tanstack/react-router'
+
+// 기본 네비게이션 - to, params 모두 타입 추론
+<Link to="/posts/$postId" params={{ postId: '123' }}>
+  Post Detail
+</Link>
+
+// search params 병합 (함수형 - 기존 params 유지)
+<Link to="/posts" search={(prev) => ({ ...prev, page: 2 })}>
+  Next Page
+</Link>
+
+// 활성 링크 스타일링
+<Link
+  to="/dashboard"
+  activeProps={{ className: 'font-bold text-blue-600' }}
+  activeOptions={{ exact: true }}
+>
+  Dashboard
+</Link>
+
+// 프리로딩 - hover 시 미리 로드
+<Link to="/posts/$postId" params={{ postId: '123' }} preload="intent">
+  View Post
+</Link>
+```
+
+**✅ 올바른 예시 (useNavigate):**
+
+```tsx
+import { useNavigate } from '@tanstack/react-router'
+
+function PostActions({ postId }: { postId: string }) {
+  // from을 지정하면 상대 경로 + 타입 추론 향상
+  const navigate = useNavigate({ from: '/posts/$postId' })
+
+  const handleDelete = async () => {
+    await deletePost(postId)
+    navigate({ to: '/posts', replace: true })
+  }
+
+  const handleEdit = () => {
+    navigate({
+      to: '/posts/$postId/edit',
+      params: { postId },
+    })
+  }
+
+  return (
+    <div>
+      <button onClick={handleEdit}>Edit</button>
+      <button onClick={handleDelete}>Delete</button>
+    </div>
+  )
+}
+```
+
+**search params 주의사항:**
+
+```tsx
+// ❌ 기존 search params 덮어쓰기
+<Link to="/posts" search={{ page: 2 }}>Next</Link>
+
+// ✅ 기존 search params 유지 + 병합
+<Link to="/posts" search={(prev) => ({ ...prev, page: 2 })}>Next</Link>
+
+// ✅ 모든 search params 유지
+<Link to="/about" search={true}>About</Link>
+```
+
+**activeOptions 설정:**
+
+```tsx
+<Link
+  to="/products"
+  search={{ category: 'electronics' }}
+  activeOptions={{
+    exact: false,           // 하위 경로도 활성 처리
+    includeSearch: true,    // search params도 매칭 조건에 포함
+  }}
+  activeProps={{ className: 'active' }}
+>
+  Electronics
+</Link>
+
+// children render function으로 동적 콘텐츠
+<Link to="/profile">
+  {({ isActive }) => (
+    <span className={isActive ? 'font-bold' : ''}>Profile</span>
+  )}
+</Link>
+```
+
+참고: [Navigation Guide](https://tanstack.com/router/latest/docs/framework/react/guide/navigation), [Link Options](https://tanstack.com/router/latest/docs/framework/react/guide/link-options)