@kood/claude-code 0.6.6 → 0.7.0

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)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/routing-nested-layouts.md

@@ -0,0 +1,155 @@
+---
+title: Use Outlet and Pathless Layouts for Nested UI
+impact: HIGH
+impactDescription: enables shared UI structure without prop drilling
+tags: routing, outlet, layouts, createRootRoute, nesting
+---
+
+## Outlet과 Pathless Layout으로 중첩 UI 구현
+
+`<Outlet />`으로 하위 라우트를 렌더링하고, pathless layout(`_prefix`)으로 URL 변경 없이 공유 UI를 적용합니다.
+
+**❌ 잘못된 예시 (레이아웃 중복):**
+
+```tsx
+// routes/dashboard/overview.tsx
+function OverviewPage() {
+  return (
+    <div className="dashboard">
+      <Sidebar />       {/* 중복 */}
+      <main><Overview /></main>
+    </div>
+  )
+}
+
+// routes/dashboard/analytics.tsx
+function AnalyticsPage() {
+  return (
+    <div className="dashboard">
+      <Sidebar />       {/* 중복 */}
+      <main><Analytics /></main>
+    </div>
+  )
+}
+```
+
+**✅ 올바른 예시 (Outlet으로 레이아웃 공유):**
+
+```tsx
+// src/routes/__root.tsx
+import { createRootRoute, Outlet } from '@tanstack/react-router'
+
+export const Route = createRootRoute({
+  component: () => (
+    <div>
+      <Header />
+      <Outlet />   {/* 하위 라우트가 여기에 렌더링 */}
+      <Footer />
+    </div>
+  ),
+})
+
+// src/routes/dashboard.tsx - 레이아웃 라우트
+export const Route = createFileRoute('/dashboard')({
+  component: DashboardLayout,
+})
+
+function DashboardLayout() {
+  return (
+    <div className="dashboard">
+      <Sidebar />
+      <main>
+        <Outlet />  {/* dashboard/overview, dashboard/analytics 렌더링 */}
+      </main>
+    </div>
+  )
+}
+
+// src/routes/dashboard/overview.tsx
+export const Route = createFileRoute('/dashboard/overview')({
+  component: () => <Overview />,  // DashboardLayout 안에 렌더링
+})
+
+// src/routes/dashboard/analytics.tsx
+export const Route = createFileRoute('/dashboard/analytics')({
+  component: () => <Analytics />,
+})
+```
+
+**Pathless Layout (URL 없는 레이아웃):**
+
+```
+src/routes/
+├── _public.tsx              ← /없음 (pathless, navbar+footer만)
+├── _public/
+│   ├── index.tsx            → /
+│   ├── about.tsx            → /about
+│   └── pricing.tsx          → /pricing
+├── _dashboard.tsx           ← /없음 (pathless, sidebar 레이아웃)
+└── _dashboard/
+    ├── overview.tsx         → /overview
+    ├── analytics.tsx        → /analytics
+    └── settings.tsx         → /settings
+```
+
+```tsx
+// src/routes/_dashboard.tsx
+export const Route = createFileRoute('/_dashboard')({
+  component: () => (
+    <div className="flex">
+      <Sidebar />
+      <main className="flex-1">
+        <Outlet />
+      </main>
+    </div>
+  ),
+})
+
+// src/routes/_dashboard/overview.tsx
+export const Route = createFileRoute('/_dashboard/overview')({
+  component: () => <h1>Overview</h1>,  // URL: /overview
+})
+```
+
+**Route Group vs Pathless Layout:**
+
+| 패턴 | 문법 | URL 영향 | 레이아웃 |
+|------|------|---------|---------|
+| **Route Group** | `(groupName)/` | 없음 | ❌ 불가 |
+| **Pathless Layout** | `_layoutName.tsx` | 없음 | ✅ 가능 |
+
+- Route Group `(public)/`: 파일 정리용, 레이아웃 없음
+- Pathless Layout `_public.tsx`: 공유 UI 래핑 가능
+
+**createRootRouteWithContext:**
+
+```tsx
+// 타입 안전한 전역 context
+interface RouterContext {
+  queryClient: QueryClient
+  auth: AuthState
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  component: () => <Outlet />,
+})
+
+// 하위 라우트에서 context 접근
+export const Route = createFileRoute('/dashboard')({
+  beforeLoad: ({ context }) => {
+    // context.queryClient, context.auth 타입 안전
+  },
+})
+```
+
+**component 생략 시 자동 Outlet:**
+
+```tsx
+// component를 지정하지 않으면 자동으로 <Outlet /> 렌더링
+export const Route = createFileRoute('/app')({
+  // component 생략 → Outlet 자동 렌더링
+  beforeLoad: async ({ context }) => { /* ... */ },
+})
+```
+
+참고: [Outlets Guide](https://tanstack.com/router/latest/docs/framework/react/guide/outlets), [Route Trees](https://tanstack.com/router/latest/docs/framework/react/guide/route-trees)

package/templates/.claude/skills/tanstack-start-react-best-practices/rules/routing-path-params.md

@@ -0,0 +1,89 @@
+---
+title: Use Type-Safe Path Params with useParams and getRouteApi
+impact: HIGH
+impactDescription: ensures correct param types across code-split components
+tags: routing, path-params, useParams, getRouteApi, type-safety
+---
+
+## useParams와 getRouteApi로 타입 안전한 Path Params
+
+TanStack Router의 `useParams`와 `getRouteApi`로 동적 라우트 파라미터를 타입 안전하게 접근합니다.
+
+**❌ 잘못된 예시 (타입 안전성 없음):**
+
+```tsx
+// strict: false는 타입 추론 약화
+function PostDetail() {
+  const params = useParams({ strict: false })
+  const postId = params.postId  // any 타입
+}
+```
+
+**✅ 올바른 예시 (Route 바인딩):**
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/posts/$postId')({
+  loader: async ({ params }) => {
+    // params.postId는 string 타입으로 자동 추론
+    return { post: await getPost(params.postId) }
+  },
+  component: PostDetail,
+})
+
+function PostDetail() {
+  // Route에 바인딩된 useParams - 완전한 타입 추론
+  const { postId } = Route.useParams()
+  const { post } = Route.useLoaderData()
+
+  return <div>{post.title}</div>
+}
+```
+
+**✅ 올바른 예시 (getRouteApi - 코드 스플릿 컴포넌트):**
+
+```tsx
+// components/PostDetail.tsx (별도 파일)
+import { getRouteApi } from '@tanstack/react-router'
+
+// Route import 없이 타입 안전하게 접근
+const routeApi = getRouteApi('/posts/$postId')
+
+export function PostDetail() {
+  const { postId } = routeApi.useParams()
+  const { post } = routeApi.useLoaderData()
+  const search = routeApi.useSearch()
+  const context = routeApi.useRouteContext()
+
+  return <div>{post.title}</div>
+}
+```
+
+**select로 리렌더 최적화:**
+
+```tsx
+// postId만 변경 시 리렌더
+const postId = useParams({
+  from: '/posts/$postId',
+  select: (params) => params.postId,
+})
+```
+
+**from으로 타입 컨텍스트 지정:**
+
+```tsx
+// 다른 라우트의 params 접근
+const { postId } = useParams({ from: '/posts/$postId' })
+
+// 현재 라우트 컨텍스트에서 접근 (Route 바인딩)
+const { postId } = Route.useParams()
+```
+
+**타입 안전성 순위:**
+1. `Route.useParams()` - 라우트에 직접 바인딩, 최고 타입 안전성
+2. `getRouteApi('/path').useParams()` - 코드 스플릿 시 사용, 순환 의존성 방지
+3. `useParams({ from: '/path' })` - from으로 타입 컨텍스트 지정
+4. `useParams({ strict: false })` - 전역 접근, 타입 약화 (비권장)
+
+참고: [Path Params Guide](https://tanstack.com/router/latest/docs/framework/react/guide/path-params), [getRouteApi](https://tanstack.com/router/latest/docs/framework/react/api/router/getRouteApiFunction)