@kood/claude-code 0.6.6 → 0.7.0

package/templates/.claude/skills/tanstack-start-react-best-practices/AGENTS.md

@@ -1,8 +1,8 @@
 # TanStack Start React 베스트 프랙티스
 
-**Version 1.0.0**
-TanStack Start 최적화 가이드
-January 2026
+**Version 3.0.0**
+TanStack Start v1 + TanStack Router + React 19 최적화 가이드
+February 2026
 
 > **참고:**
 > 이 문서는 주로 에이전트와 LLM이 React 및 TanStack Start 코드베이스를 유지보수, 생성, 리팩토링할 때 따르기 위한 것입니다. 사람도 유용하게 사용할 수 있지만, AI 지원 워크플로의 자동화 및 일관성을 위해 최적화되어 있습니다.
@@ -11,7 +11,7 @@ January 2026
 
 ## 요약
 
-AI 에이전트와 LLM을 위한 React 및 TanStack Start 애플리케이션 종합 성능 최적화 가이드. 7개 카테고리에 걸쳐 38개 규칙을 포함하며, 영향도별로 우선순위를 매겼습니다 (critical: waterfall 제거, 번들 크기 감소 → incremental: JavaScript 성능). 각 규칙은 자동 리팩토링 및 코드 생성을 위한 상세한 설명, 올바른 구현 대 잘못된 구현을 비교하는 실제 예시, 구체적인 영향 지표를 포함합니다.
+AI 에이전트와 LLM을 위한 React 19 및 TanStack Start v1 애플리케이션 종합 성능 최적화 가이드. 8개 카테고리에 걸쳐 55개 규칙을 포함하며, 영향도별로 우선순위를 매겼습니다 (critical: waterfall 제거, 번들 크기 감소 → incremental: JavaScript 성능). TanStack Router 라우팅 패턴(Link, useNavigate, useSearch, useParams, beforeLoad, Outlet, pendingComponent, 프리로딩, 파일 컨벤션), React Compiler 자동 메모이제이션, use() hook, useOptimistic, createMiddleware, inputValidator, 데이터 스트리밍 등 최신 패턴 반영. 각 규칙은 자동 리팩토링 및 코드 생성을 위한 상세한 설명, 올바른 구현 대 잘못된 구현을 비교하는 실제 예시, 구체적인 영향 지표를 포함합니다.
 
 ---
 
@@ -32,10 +32,27 @@ AI 에이전트와 LLM을 위한 React 및 TanStack Start 애플리케이션 종
 @rules/server-serialization.md
 @rules/server-parallel-fetching.md
 @rules/server-deferred-data.md
+@rules/server-middleware.md
+@rules/server-validator.md
+@rules/server-streaming.md
+@rules/server-error-boundaries.md
 @rules/client-tanstack-query.md
+@rules/client-suspense-query.md
+@rules/client-optimistic-updates.md
+@rules/client-use-hook.md
 @rules/client-event-listeners.md
+@rules/routing-file-conventions.md
+@rules/routing-link-navigation.md
+@rules/routing-search-params.md
+@rules/routing-path-params.md
+@rules/routing-beforeload-auth.md
+@rules/routing-nested-layouts.md
+@rules/routing-router-context.md
+@rules/routing-preload-strategy.md
+@rules/routing-pending-component.md
 @rules/rerender-defer-reads.md
 @rules/rerender-memo.md
+@rules/rerender-react-compiler.md
 @rules/rerender-dependencies.md
 @rules/rerender-derived-state.md
 @rules/rerender-functional-setstate.md
@@ -71,11 +88,12 @@ AI 에이전트와 LLM을 위한 React 및 TanStack Start 애플리케이션 종
 |---------|---------|--------|------|
 | 1 | Waterfall 제거 | **CRITICAL** | 순차 await를 병렬로 전환. 가장 큰 성능 향상 제공 |
 | 2 | 번들 크기 최적화 | **CRITICAL** | TTI와 LCP 개선. 초기 로딩 속도 향상 |
-| 3 | 서버 사이드 성능 | HIGH | 서버 사이드 waterfall 제거, 응답 시간 단축 |
-| 4 | 클라이언트 데이터 페칭 | MEDIUM-HIGH | 자동 중복 제거, 효율적 데이터 페칭 |
-| 5 | Re-render 최적화 | MEDIUM | 불필요한 re-render 최소화, UI 반응성 향상 |
-| 6 | 렌더링 성능 | MEDIUM | 브라우저 렌더링 작업 최적화 |
-| 7 | JavaScript 성능 | LOW-MEDIUM | Hot path 마이크로 최적화 |
+| 3 | TanStack Router 라우팅 | **HIGH** | 타입 안전 네비게이션, 인증 가드, 레이아웃, 프리로딩 |
+| 4 | 서버 사이드 성능 | HIGH | 서버 사이드 waterfall 제거, 응답 시간 단축 |
+| 5 | 클라이언트 데이터 페칭 | MEDIUM-HIGH | 자동 중복 제거, 효율적 데이터 페칭 |
+| 6 | Re-render 최적화 | MEDIUM | 불필요한 re-render 최소화, UI 반응성 향상 |
+| 7 | 렌더링 성능 | MEDIUM | 브라우저 렌더링 작업 최적화 |
+| 8 | JavaScript 성능 | LOW-MEDIUM | Hot path 마이크로 최적화 |
 
 </categories>
 
@@ -718,13 +736,34 @@ function UserList({ users }: { users: User[] }) {
 2. [TanStack Start Overview](https://tanstack.com/start/latest/docs/framework/react/overview)
 3. [TanStack Start Quick Start](https://tanstack.com/start/latest/docs/framework/react/quick-start)
 4. [TanStack Router](https://tanstack.com/router)
-5. [TanStack Router Deferred Data Loading](https://tanstack.com/router/v1/docs/framework/react/guide/deferred-data-loading)
-6. [TanStack Query](https://tanstack.com/query)
+5. [TanStack Router Deferred Data Loading](https://tanstack.com/router/latest/docs/framework/react/guide/deferred-data-loading)
+6. [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview)
 7. [Server Functions Guide](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions)
+8. [Middleware Guide](https://tanstack.com/start/latest/docs/framework/react/guide/middleware)
+9. [Streaming Data Guide](https://tanstack.com/start/latest/docs/framework/react/guide/streaming-data-from-server-functions)
+
+### TanStack Router
+10. [Navigation Guide](https://tanstack.com/router/latest/docs/framework/react/guide/navigation)
+11. [Link Options](https://tanstack.com/router/latest/docs/framework/react/guide/link-options)
+12. [Search Params](https://tanstack.com/router/latest/docs/framework/react/guide/search-params)
+13. [Path Params](https://tanstack.com/router/latest/docs/framework/react/guide/path-params)
+14. [Authenticated Routes](https://tanstack.com/router/latest/docs/framework/react/guide/authenticated-routes)
+15. [Outlets](https://tanstack.com/router/latest/docs/framework/react/guide/outlets)
+16. [Route Trees](https://tanstack.com/router/latest/docs/framework/react/guide/route-trees)
+17. [File-Based Routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing)
+18. [Router Context](https://tanstack.com/router/latest/docs/framework/react/guide/router-context)
+19. [Preloading](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)
+20. [Data Loading](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading)
+
+### React 19
+21. [React 19 Blog](https://react.dev/blog/2024/12/05/react-19)
+22. [React use() API](https://react.dev/reference/react/use)
+23. [React useOptimistic](https://react.dev/reference/react/useOptimistic)
+24. [React Compiler](https://react.dev/learn/react-compiler)
 
 ### 외부 자료
-8. [better-all](https://github.com/shuding/better-all)
-9. [node-lru-cache](https://github.com/isaacs/node-lru-cache)
-10. [Using Server Functions and TanStack Query](https://www.brenelz.com/posts/using-server-functions-and-tanstack-query/)
+25. [better-all](https://github.com/shuding/better-all)
+26. [node-lru-cache](https://github.com/isaacs/node-lru-cache)
+27. [Using Server Functions and TanStack Query](https://www.brenelz.com/posts/using-server-functions-and-tanstack-query/)
 
 </references>

package/templates/.claude/skills/tanstack-start-react-best-practices/SKILL.md

@@ -5,11 +5,12 @@ license: MIT
 framework: tanstack-start
 metadata:
   author: vercel
-  version: "1.0.0"
+  version: "3.0.0"
   adapted_for: tanstack-start
 ---
 
 @../../instructions/agent-patterns/read-parallelization.md
+@../../instructions/agent-patterns/agent-teams-usage.md
 @../../instructions/validation/forbidden-patterns.md
 @../../instructions/validation/required-behaviors.md
 @../../instructions/multi-agent/coordination-guide.md
@@ -17,7 +18,7 @@ metadata:
 
 # TanStack Start React 베스트 프랙티스
 
-React와 TanStack Start 애플리케이션 성능 최적화 가이드. 7개 카테고리, 38개 규칙 포함. 영향도별 우선순위로 자동 리팩토링과 코드 생성 가이드 제공.
+React 19와 TanStack Start v1 애플리케이션 성능 최적화 가이드. 8개 카테고리, 55개 규칙 포함. 영향도별 우선순위로 자동 리팩토링과 코드 생성 가이드 제공. TanStack Router 라우팅 패턴(Link, useNavigate, useSearch, useParams, beforeLoad, Outlet, pendingComponent, 프리로딩), React Compiler, use() hook, useOptimistic, Middleware, Streaming 등 최신 패턴 반영.
 
 ---
 
@@ -188,11 +189,12 @@ Task(subagent_type="implementation-executor", model="sonnet",
 |---------|---------|--------|--------|
 | 1 | Waterfall 제거 | **CRITICAL** | `async-` |
 | 2 | 번들 크기 최적화 | **CRITICAL** | `bundle-` |
-| 3 | 서버 사이드 성능 | HIGH | `server-` |
-| 4 | 클라이언트 데이터 페칭 | MEDIUM-HIGH | `client-` |
-| 5 | Re-render 최적화 | MEDIUM | `rerender-` |
-| 6 | 렌더링 성능 | MEDIUM | `rendering-` |
-| 7 | JavaScript 성능 | LOW-MEDIUM | `js-` |
+| 3 | TanStack Router 라우팅 | **HIGH** | `routing-` |
+| 4 | 서버 사이드 성능 | HIGH | `server-` |
+| 5 | 클라이언트 데이터 페칭 | MEDIUM-HIGH | `client-` |
+| 6 | Re-render 최적화 | MEDIUM | `rerender-` |
+| 7 | 렌더링 성능 | MEDIUM | `rendering-` |
+| 8 | JavaScript 성능 | LOW-MEDIUM | `js-` |
 
 </categories>
 
@@ -221,35 +223,57 @@ Task(subagent_type="implementation-executor", model="sonnet",
 | `bundle-conditional` | 기능 활성화 시에만 모듈 로드 |
 | `bundle-preload` | hover/focus 시 preload로 체감 속도 향상 |
 
-### 3. 서버 사이드 성능 (HIGH)
+### 3. TanStack Router 라우팅 (HIGH)
+
+| 규칙 | 설명 |
+|------|------|
+| `routing-file-conventions` | 파일 기반 라우팅 컨벤션 (__root, $param, _layout, lazy) |
+| `routing-link-navigation` | Link 컴포넌트와 useNavigate로 타입 안전 네비게이션 |
+| `routing-search-params` | useSearch + Zod 스키마로 search params 검증 |
+| `routing-path-params` | useParams와 getRouteApi로 타입 안전 path params |
+| `routing-beforeload-auth` | beforeLoad로 인증 가드, pathless layout 조합 |
+| `routing-nested-layouts` | Outlet과 pathless layout으로 중첩 UI |
+| `routing-router-context` | createRootRouteWithContext로 의존성 주입 |
+| `routing-preload-strategy` | Link preload="intent"로 즉각적 네비게이션 |
+| `routing-pending-component` | pendingComponent로 로딩 상태 (pendingMs/pendingMinMs) |
+
+### 4. 서버 사이드 성능 (HIGH)
 
 | 규칙 | 설명 |
 |------|------|
 | `server-cache-lru` | LRU 캐시로 요청 간 캐싱 |
-| `server-serialization` | 클라이언트로 전달 데이터 최소화 |
+| `server-serialization` | loader 데이터 직렬화 최소화 |
 | `server-parallel-fetching` | loader에서 병렬 데이터 페칭 |
-| `server-deferred-data` | defer()로 비차단 데이터 로딩 |
+| `server-deferred-data` | Promise 반환으로 비차단 데이터 로딩 |
+| `server-middleware` | createMiddleware()로 인증/로깅 중앙화 |
+| `server-validator` | inputValidator()로 타입 안전한 Server Functions |
+| `server-streaming` | async generator/ReadableStream으로 데이터 스트리밍 |
+| `server-error-boundaries` | 라우트 레벨 errorComponent/notFoundComponent |
 
-### 4. 클라이언트 데이터 페칭 (MEDIUM-HIGH)
+### 5. 클라이언트 데이터 페칭 (MEDIUM-HIGH)
 
 | 규칙 | 설명 |
 |------|------|
 | `client-tanstack-query` | TanStack Query로 자동 캐싱/중복 제거 |
+| `client-suspense-query` | useSuspenseQuery로 선언적 데이터 로딩 (v5) |
+| `client-optimistic-updates` | useOptimistic으로 즉각적 UI 피드백 (React 19) |
+| `client-use-hook` | use() hook으로 Promise 처리 (React 19) |
 | `client-event-listeners` | 전역 이벤트 리스너 중복 제거 |
 
-### 5. Re-render 최적화 (MEDIUM)
+### 6. Re-render 최적화 (MEDIUM)
 
 | 규칙 | 설명 |
 |------|------|
 | `rerender-defer-reads` | 콜백 전용 상태는 구독 안 함 |
 | `rerender-memo` | 비싼 작업은 memoized 컴포넌트로 추출 |
+| `rerender-react-compiler` | React Compiler로 자동 메모이제이션 (React 19) |
 | `rerender-dependencies` | effect에 원시값 의존성 사용 |
 | `rerender-derived-state` | 파생 boolean 구독, raw 값 구독 회피 |
 | `rerender-functional-setstate` | 안정적 콜백용 함수형 setState |
 | `rerender-lazy-state-init` | 비싼 초기값은 함수로 useState에 전달 |
 | `rerender-transitions` | 비긴급 업데이트는 startTransition |
 
-### 6. 렌더링 성능 (MEDIUM)
+### 7. 렌더링 성능 (MEDIUM)
 
 | 규칙 | 설명 |
 |------|------|
@@ -259,7 +283,7 @@ Task(subagent_type="implementation-executor", model="sonnet",
 | `rendering-svg-precision` | SVG 좌표 정밀도 감소 |
 | `rendering-conditional-render` | 조건부 렌더링은 &&가 아닌 삼항 연산자 |
 
-### 7. JavaScript 성능 (LOW-MEDIUM)
+### 8. JavaScript 성능 (LOW-MEDIUM)
 
 | 규칙 | 설명 |
 |------|------|
@@ -400,26 +424,46 @@ const addItems = useCallback((newItems: Item[]) => {
 import { createServerFn } from '@tanstack/react-start'
 import { z } from 'zod'
 
-// ✅ 기본 Server Function
+// ✅ 기본 Server Function (GET)
 const getUser = createServerFn().handler(async () => {
   // 서버에서만 실행
   return await db.user.findMany()
 })
 
-// ✅ POST + Validation
-const createUserSchema = z.object({
+// ✅ POST + Validation (inputValidator는 함수 형태 필수)
+const UserSchema = z.object({
   name: z.string().min(1),
   email: z.string().email()
 })
 
 const createUser = createServerFn({ method: 'POST' })
-  .inputValidator(createUserSchema)
+  .inputValidator((d: unknown) => UserSchema.parse(d))
   .handler(async ({ data }) => {
-    // data는 완전히 타입 검증됨
+    // data는 자동으로 { name: string; email: string } 타입
     return await db.user.create({ data })
   })
 ```
 
+### Middleware로 인증 중앙화
+
+```typescript
+import { createMiddleware } from '@tanstack/react-start'
+
+const authMiddleware = createMiddleware()
+  .server(async ({ next }) => {
+    const session = await getSession()
+    if (!session?.user) throw redirect({ to: '/login' })
+    return next({ context: { user: session.user } })
+  })
+
+// 보호된 Server Function
+const getMyTodos = createServerFn()
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    return await db.todo.findMany({ where: { userId: context.user.id } })
+  })
+```
+
 ### Loader 최적화
 
 ```typescript
@@ -546,18 +590,41 @@ rules/server-deferred-data.md
 
 ## 참고 자료
 
-### TanStack 공식 문서
+### TanStack Start 공식 문서
 1. [React 공식 문서](https://react.dev)
 2. [TanStack Start Overview](https://tanstack.com/start/latest/docs/framework/react/overview)
 3. [TanStack Start Quick Start](https://tanstack.com/start/latest/docs/framework/react/quick-start)
-4. [TanStack Router](https://tanstack.com/router)
-5. [TanStack Router Deferred Data Loading](https://tanstack.com/router/v1/docs/framework/react/guide/deferred-data-loading)
-6. [TanStack Query](https://tanstack.com/query)
-7. [Server Functions Guide](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions)
+4. [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview)
+5. [Server Functions Guide](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions)
+6. [Middleware Guide](https://tanstack.com/start/latest/docs/framework/react/guide/middleware)
+7. [Streaming Data Guide](https://tanstack.com/start/latest/docs/framework/react/guide/streaming-data-from-server-functions)
+8. [Authentication Guide](https://tanstack.com/start/latest/docs/framework/react/guide/authentication)
+
+### TanStack Router
+9. [TanStack Router](https://tanstack.com/router)
+10. [Navigation Guide](https://tanstack.com/router/latest/docs/framework/react/guide/navigation)
+11. [Link Options](https://tanstack.com/router/latest/docs/framework/react/guide/link-options)
+12. [Search Params](https://tanstack.com/router/latest/docs/framework/react/guide/search-params)
+13. [Path Params](https://tanstack.com/router/latest/docs/framework/react/guide/path-params)
+14. [Authenticated Routes](https://tanstack.com/router/latest/docs/framework/react/guide/authenticated-routes)
+15. [Outlets](https://tanstack.com/router/latest/docs/framework/react/guide/outlets)
+16. [Route Trees](https://tanstack.com/router/latest/docs/framework/react/guide/route-trees)
+17. [File-Based Routing](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing)
+18. [Router Context](https://tanstack.com/router/latest/docs/framework/react/guide/router-context)
+19. [Preloading](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)
+20. [Data Loading](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading)
+21. [Deferred Data Loading](https://tanstack.com/router/latest/docs/framework/react/guide/deferred-data-loading)
+
+### React 19
+22. [React 19 Blog](https://react.dev/blog/2024/12/05/react-19)
+23. [React use() API](https://react.dev/reference/react/use)
+24. [React useOptimistic](https://react.dev/reference/react/useOptimistic)
+25. [React useActionState](https://react.dev/reference/react/useActionState)
+26. [React Compiler](https://react.dev/learn/react-compiler)
 
 ### 외부 자료
-8. [better-all](https://github.com/shuding/better-all)
-9. [node-lru-cache](https://github.com/isaacs/node-lru-cache)
-10. [Using Server Functions and TanStack Query](https://www.brenelz.com/posts/using-server-functions-and-tanstack-query/)
+27. [better-all](https://github.com/shuding/better-all)
+28. [node-lru-cache](https://github.com/isaacs/node-lru-cache)
+29. [Using Server Functions and TanStack Query](https://www.brenelz.com/posts/using-server-functions-and-tanstack-query/)
 
 </references>

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/bundle-defer-third-party.md

@@ -13,37 +13,60 @@ tags: bundle, third-party, analytics, defer
 
 ```tsx
 import { Analytics } from '@vercel/analytics/react'
+import { ErrorTracker } from './error-tracker'
 
-export default function RootLayout({ children }) {
+function RootLayout({ children }: { children: React.ReactNode }) {
   return (
-    <html>
-      <body>
-        {children}
-        <Analytics />
-      </body>
-    </html>
+    <div>
+      {children}
+      <Analytics />
+      <ErrorTracker />
+    </div>
   )
 }
 ```
 
-**✅ 올바른 예시 (하이드레이션 후 로드):**
+**✅ 올바른 예시 (하이드레이션 후 lazy load):**
 
 ```tsx
-import dynamic from 'next/dynamic'
+import { lazy, Suspense, useEffect, useState } from 'react'
 
-const Analytics = dynamic(
-  () => import('@vercel/analytics/react').then(m => m.Analytics),
-  { ssr: false }
+const Analytics = lazy(() =>
+  import('@vercel/analytics/react').then(m => ({ default: m.Analytics }))
 )
 
-export default function RootLayout({ children }) {
+function RootLayout({ children }: { children: React.ReactNode }) {
+  const [hydrated, setHydrated] = useState(false)
+
+  useEffect(() => {
+    setHydrated(true)
+  }, [])
+
   return (
-    <html>
-      <body>
-        {children}
-        <Analytics />
-      </body>
-    </html>
+    <div>
+      {children}
+      {hydrated && (
+        <Suspense fallback={null}>
+          <Analytics />
+        </Suspense>
+      )}
+    </div>
   )
 }
 ```
+
+**✅ 더 간단한 대안 (useEffect로 직접 초기화):**
+
+```tsx
+function RootLayout({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    // 하이드레이션 후 비동기 로드
+    import('./analytics').then(mod => mod.init())
+    import('./error-tracker').then(mod => mod.init())
+  }, [])
+
+  return <div>{children}</div>
+}
+```
+
+TanStack Start에서는 `next/dynamic`을 사용할 수 없으므로, React의 `lazy()` + `Suspense` 또는 `useEffect` 내 동적 `import()`를 사용합니다.

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)