@kood/claude-code 0.5.3 → 0.5.5

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

@@ -1,6 +1,6 @@
 # Architecture
 
-> TanStack Start Application Architecture
+> TanStack Start 애플리케이션 아키텍처
 
 <instructions>
 @../guides/conventions.md
@@ -13,14 +13,14 @@
 
 <forbidden>
 
-| Category | Forbidden |
-|----------|-----------|
-| **Routes** | Flat file routes (`routes/users.tsx`) |
-| **Route Export** | `export const IndexRoute`, `const Route` (without export) |
-| **API** | Creating `/api` routes (use Server Functions) |
-| **Layers** | Skipping Service Layer, direct DB access from Routes |
-| **Validation** | Manual validation inside handler, scattered auth logic |
-| **Barrel Export** | Creating `functions/index.ts` (Tree Shaking fails, server libraries pollute Client bundle) |
+| 분류 | 금지 |
+|------|------|
+| **라우트** | Flat 파일 라우트 (`routes/users.tsx`) |
+| **Route Export** | `export const IndexRoute`, `const Route` (export 안함) |
+| **API** | `/api` 라우터 생성 (Server Functions 사용) |
+| **레이어** | Service Layer 건너뛰기, Routes에서 직접 DB 접근 |
+| **검증** | Handler 내부 수동 검증, 인증 로직 분산 |
+| **Barrel Export** | `functions/index.ts` 생성 (Tree Shaking 실패, 서버 라이브러리 Client 오염) |
 
 </forbidden>
 
@@ -28,20 +28,20 @@
 
 <required>
 
-| Category | Required |
-|----------|----------|
-| **Route Structure** | Create folder per page (`routes/users/index.tsx`) |
-| **Route Export** | `export const Route = createFileRoute(...)` required |
-| **Layer Structure** | Routes → Server Functions → Services → Database |
-| **Route Group** | List pages → `(main)/`, create/edit → outside |
-| **Page Separation** | 100+ lines → `-components`, 200+ lines → `-sections` |
-| **beforeLoad** | Auth check, Context passing, redirects |
-| **loader** | Data loading (runs in parallel after beforeLoad) |
-| **Server Fn** | Use `createServerFn` by default |
-| **Validation** | `inputValidator` (POST/PUT/PATCH), Zod schemas |
-| **Auth** | `middleware` (authMiddleware) |
-| **Error Handling** | `errorComponent` (route), `notFoundComponent` (404) |
-| **Type Safety** | TypeScript strict, Prisma types |
+| 분류 | 필수 |
+|------|------|
+| **라우트 구조** | 페이지마다 폴더 생성 (`routes/users/index.tsx`) |
+| **Route Export** | `export const Route = createFileRoute(...)` 필수 |
+| **계층 구조** | Routes → Server Functions → Services → Database |
+| **Route Group** | 목록 → `(main)/`, 생성/편집 → 외부 |
+| **페이지 분리** | 100줄+ → `-components`, 200줄+ → `-sections` |
+| **beforeLoad** | 인증 체크, Context 전달, 리다이렉트 |
+| **loader** | 데이터 로딩 (beforeLoad 완료 후 병렬 실행) |
+| **Server Fn** | `createServerFn` 기본 사용 |
+| **검증** | `inputValidator` (POST/PUT/PATCH), Zod 스키마 |
+| **인증** | `middleware` (authMiddleware) |
+| **에러 처리** | `errorComponent` (라우트), `notFoundComponent` (404) |
+| **타입 안전** | TypeScript strict, Prisma 타입 |
 
 </required>
 
@@ -64,7 +64,7 @@
 │                    TanStack Start Server                         │
 │  ┌────────────────────────────────────────────────────────────┐ │
 │  │                    Server Functions                         │ │
-│  │   routes/-functions/ → Page-specific | functions/ → Global │ │
+│  │   routes/-functions/ → 페이지 전용 | functions/ → 글로벌   │ │
 │  └────────────────────────────┬───────────────────────────────┘ │
 │  ┌────────────────────────────▼───────────────────────────────┐ │
 │  │                    Services Layer                           │ │
@@ -86,32 +86,32 @@
 
 <route_export_rule>
 
-## Route Export Rules
+## Route Export 규칙
 
-> ⚠️ **`export const Route` Required**
+> ⚠️ **`export const Route` 필수**
 >
-> TanStack Router requires all route files to export **exactly the name `Route`**.
+> TanStack Router는 모든 라우트 파일에서 **정확히 `Route`라는 이름**으로 내보내야 합니다.
 >
-> The `tsr generate` and `tsr watch` commands automatically generate and update routes.
+> `tsr generate` 및 `tsr watch` 명령어가 자동으로 경로를 생성하고 업데이트합니다.
 
-| ❌ Forbidden | ✅ Required |
-|--------------|-------------|
+| ❌ 금지 | ✅ 필수 |
+|--------|--------|
 | `const Route = createFileRoute(...)` | `export const Route = createFileRoute(...)` |
 | `export const IndexRoute = ...` | `export const Route = ...` |
 | `export default createFileRoute(...)` | `export const Route = createFileRoute(...)` |
 
 ```typescript
-// ❌ Forbidden: No export
+// ❌ 금지: export 없음
 const Route = createFileRoute('/users')({
   component: UsersPage,
 })
 
-// ❌ Forbidden: Different name
+// ❌ 금지: 다른 이름
 export const UsersRoute = createFileRoute('/users')({
   component: UsersPage,
 })
 
-// ✅ Required: Export with exactly 'Route' name
+// ✅ 필수: 정확히 'Route' 이름으로 export
 export const Route = createFileRoute('/users')({
   component: UsersPage,
 })
@@ -127,59 +127,59 @@ export const Route = createFileRoute('/users')({
 
 ### 1. Routes Layer
 
-> ⚠️ **Create Folder Per Page (Required)**
+> ⚠️ **페이지마다 폴더 생성 필수**
 >
-> All pages **must use folder structure**. Flat file approach (`routes/users.tsx`) is forbidden.
+> 모든 페이지는 **반드시 폴더 구조**로 만들어야 합니다. Flat 파일 방식(`routes/users.tsx`)은 금지됩니다.
 >
-> **Reason:** To systematically manage page-specific resources like -components/, -functions/, -hooks/.
+> **이유:** -components/, -functions/, -hooks/ 등 페이지 전용 리소스를 체계적으로 관리하기 위함입니다.
 >
-> | ❌ Forbidden | ✅ Required |
-> |--------------|-------------|
+> | ❌ 금지 | ✅ 필수 |
+> |--------|--------|
 > | `routes/users.tsx` | `routes/users/index.tsx` |
 > | `routes/posts.tsx` | `routes/posts/(main)/index.tsx` |
 
 ```
 routes/<route-name>/
-├── (main)/                # Route group (list page)
-│   ├── index.tsx          # Page component
-│   ├── -components/       # Page-specific components
-│   ├── -sections/         # UI section separation (200+ lines)
-│   ├── -tabs/             # Tab content separation
-│   ├── -hooks/            # Page-specific hooks
-│   └── -utils/            # Constants, helpers
-├── new/                   # Create page (outside route group)
+├── (main)/                # route group (목록 페이지)
+│   ├── index.tsx          # 페이지 컴포넌트
+│   ├── -components/       # 페이지 전용 컴포넌트
+│   ├── -sections/         # UI 섹션 분리 (200줄+ 페이지)
+│   ├── -tabs/             # 탭 콘텐츠 분리
+│   ├── -hooks/            # 페이지 전용 훅
+│   └── -utils/            # 상수, 헬퍼
+├── new/                   # 생성 페이지 (route group 외부)
 │   └── index.tsx
-├── route.tsx              # Route config (loader, beforeLoad)
-└── -functions/            # Page-specific server functions
+├── route.tsx              # route 설정 (loader, beforeLoad)
+└── -functions/            # 페이지 전용 서버 함수
 ```
 
-| Pattern | Location | Purpose |
-|---------|----------|---------|
-| **Route Group** | `(main)/` | List pages, excluded from URL |
-| **-components/** | 100-200 lines | Separate page-specific components |
-| **-sections/** | 200+ lines | Logical section separation |
-| **-tabs/** | Tab UI | Tab content separation |
-| **route.tsx** | Layout | Shared layout for child routes |
+| 패턴 | 위치 | 용도 |
+|------|------|------|
+| **Route Group** | `(main)/` | 목록 페이지, URL에 미포함 |
+| **-components/** | 100-200줄 | 페이지 전용 컴포넌트 분리 |
+| **-sections/** | 200줄+ | 논리적 섹션 분리 |
+| **-tabs/** | 탭 UI | 탭 콘텐츠 분리 |
+| **route.tsx** | 레이아웃 | 하위 경로 공통 레이아웃 |
 
-#### Layout Routes Pattern
+#### Layout Routes 패턴
 
-> ⚠️ **Use route.tsx for Layouts**
+> ⚠️ **route.tsx로 레이아웃 구성**
 >
-> `route.tsx` serves as a shared layout for child routes.
-> `index.tsx` must be wrapped with Route Group `()`.
+> `route.tsx`는 하위 경로의 공통 레이아웃 역할을 합니다.
+> `index.tsx`는 Route Group `()`으로 묶어야 합니다.
 >
-> **Required:** `route.tsx` must export a `component`.
+> **필수:** `route.tsx`는 반드시 `component`를 export해야 합니다.
 >
-> | ❌ Forbidden | ✅ Required |
-> |--------------|-------------|
+> | ❌ 금지 | ✅ 필수 |
+> |--------|--------|
 > | `export const Route = createFileRoute(...)({})` | `export const Route = createFileRoute(...)({ component: ... })` |
 
 ```
 routes/
 ├── (auth)/
-│   ├── route.tsx           # Layout (<Outlet />)
+│   ├── route.tsx           # 레이아웃 (<Outlet />)
 │   ├── (main)/
-│   │   └── index.tsx       # /auth (list/main)
+│   │   └── index.tsx       # /auth (목록/메인)
 │   ├── login/
 │   │   └── index.tsx       # /auth/login
 │   └── register/
@@ -187,13 +187,13 @@ routes/
 ```
 
 ```typescript
-// ❌ Forbidden: No component
+// ❌ 금지: component 없음
 export const Route = createFileRoute('/(auth)')({
   beforeLoad: async () => ({ user: await getUser() }),
 })
 
-// ✅ Required: Component must be included
-// routes/(auth)/route.tsx - Layout
+// ✅ 필수: component 반드시 포함
+// routes/(auth)/route.tsx - 레이아웃
 export const Route = createFileRoute('/(auth)')({
   component: () => (
     <div className="auth-container">
@@ -202,7 +202,7 @@ export const Route = createFileRoute('/(auth)')({
   ),
 })
 
-// routes/(auth)/(main)/index.tsx - Main page
+// routes/(auth)/(main)/index.tsx - 메인 페이지
 export const Route = createFileRoute('/(auth)/')({
   component: AuthMainPage,
 })
@@ -217,38 +217,38 @@ export const Route = createFileRoute('/(auth)/login')({
 
 ```
 services/<domain>/
-├── index.ts            # Entry point (re-export)
-├── schemas.ts          # Zod schemas
-├── queries.ts          # GET requests
+├── index.ts            # 진입점 (re-export)
+├── schemas.ts          # Zod 스키마
+├── queries.ts          # GET 요청
 └── mutations.ts        # POST/PUT/PATCH
 ```
 
 ### 3. Server Functions Layer
 
 ```
-functions/                    # Global (reusable)
-├── <function-name>.ts        # One per file
+functions/                    # 글로벌 (재사용)
+├── <function-name>.ts        # 파일당 하나
 └── middlewares/
     └── <middleware-name>.ts
 
-routes/<route>/-functions/    # Page-specific
+routes/<route>/-functions/    # 페이지 전용
 └── <function-name>.ts
 ```
 
-> ⚠️ **Do Not Create `functions/index.ts`**
+> ⚠️ **`functions/index.ts` 생성 금지**
 >
-> Do not create `index.ts` (barrel export) file in `functions/` folder.
+> `functions/` 폴더에 `index.ts` (barrel export) 파일을 만들지 마세요.
 >
-> **Issues:**
-> 1. **Tree Shaking Fails** - Bundler includes unused functions
-> 2. **Client Bundle Pollution** - Server-only libraries like `pg`, `prisma` get imported to client, causing build errors
+> **문제점:**
+> 1. **Tree Shaking 실패** - 번들러가 사용하지 않는 함수도 포함
+> 2. **Client 번들 오염** - `pg`, `prisma` 등 서버 전용 라이브러리가 클라이언트에 import되어 빌드 에러 발생
 >
 > ```typescript
-> // ❌ Do not create functions/index.ts
+> // ❌ functions/index.ts 만들지 말 것
 > export * from './get-users'
-> export * from './create-post'  // pg import → client build fails
+> export * from './create-post'  // pg import → 클라이언트 빌드 실패
 >
-> // ✅ Import directly from individual files
+> // ✅ 개별 파일에서 직접 import
 > import { getUsers } from '@/functions/get-users'
 > import { createPost } from '@/functions/create-post'
 > ```
@@ -278,30 +278,30 @@ if (process.env.NODE_ENV !== 'production') {
 
 ### beforeLoad vs loader
 
-| Item | beforeLoad | loader |
+| 항목 | beforeLoad | loader |
 |------|-----------|--------|
-| **Execution Order** | Sequential (outermost → innermost) | Parallel (after beforeLoad completes) |
-| **Purpose** | Auth, Context passing, redirects | Data loading |
-| **Blocking** | Blocks all loaders | Runs in parallel with other loaders |
-| **Performance Impact** | ⚠️ High | ✅ Low |
+| **실행 순서** | 순차 (outermost → innermost) | 병렬 (beforeLoad 완료 후) |
+| **용도** | 인증, Context 전달, 리다이렉트 | 데이터 로딩 |
+| **블로킹** | 모든 loader 차단 | 다른 loader와 병렬 |
+| **성능 영향** | ⚠️ 높음 | ✅ 낮음 |
 
 ```
-1. Parent beforeLoad (sequential) ──┐
-2. Child beforeLoad (sequential)  ──┼→ After completion
-3. All loaders (parallel) ───────────┘
+1. Parent beforeLoad (순차) ──┐
+2. Child beforeLoad (순차)  ──┼→ 완료 후
+3. All loaders (병렬) ────────┘
 ```
 
-### Code Patterns
+### 코드 패턴
 
 ```typescript
-// ✅ beforeLoad: Auth & Context
+// ✅ beforeLoad: 인증 & Context
 beforeLoad: async () => {
   const user = await getUser()
   if (!user) throw redirect({ to: '/login' })
   return { user }
 }
 
-// ✅ loader: Data Loading
+// ✅ loader: 데이터 로딩
 loader: async () => {
   const [users, roles] = await Promise.all([
     getUsers(),
@@ -311,10 +311,10 @@ loader: async () => {
 }
 ```
 
-| ❌ Avoid | ✅ Recommended |
-|----------|----------------|
-| Data loading in beforeLoad | Data loading in loader |
-| Blocking loaders | Parallel execution |
+| ❌ 금지 | ✅ 권장 |
+|--------|--------|
+| beforeLoad에서 데이터 로딩 | loader에서 데이터 로딩 |
+| loader 차단 | 병렬 실행 |
 
 </route_lifecycle>
 
@@ -324,14 +324,14 @@ loader: async () => {
 
 ## Context Management
 
-| Step | File | Action |
-|------|------|--------|
-| **Create** | `__root.tsx` | `createRootRouteWithContext` |
-| **Extend** | `route.tsx` | Extend Context in `beforeLoad` |
-| **Use** | `component` | `useRouteContext()` |
+| 단계 | 파일 | 작업 |
+|------|------|------|
+| **생성** | `__root.tsx` | `createRootRouteWithContext` |
+| **확장** | `route.tsx` | `beforeLoad` Context 확장 |
+| **사용** | `component` | `useRouteContext()` |
 
 ```typescript
-// 1. Root: Define Context
+// 1. Root: Context 정의
 interface RouterContext {
   user: User | null
 }
@@ -340,16 +340,16 @@ export const Route = createRootRouteWithContext<RouterContext>()({
   beforeLoad: async () => ({ user: await getUser() }),
 })
 
-// 2. Extend: Extend Context
+// 2. 확장: Context 확장
 beforeLoad: async ({ context }) => ({
   ...context,
   permissions: await getPermissions(context.user.id),
 })
 
-// 3. Use: Component
+// 3. 사용: Component
 const { user, permissions } = useRouteContext({ from: '/dashboard' })
 
-// 4. Use: Loader
+// 4. 사용: Loader
 loader: async ({ context }) => {
   if (!context.permissions.includes('users:read')) {
     throw new Error('Unauthorized')
@@ -366,7 +366,7 @@ loader: async ({ context }) => {
 
 ## Data Flow
 
-### Query Flow (Read)
+### Query Flow (읽기)
 
 ```
 Page → useQuery → Server Function → Prisma → Database
@@ -387,7 +387,7 @@ export const getUsers = createServerFn()
   .handler(async () => prisma.user.findMany())
 ```
 
-### Mutation Flow (Write)
+### Mutation Flow (쓰기)
 
 ```
 Form → useMutation → Server Function
@@ -423,17 +423,17 @@ export const createUser = createServerFn({ method: 'POST' })
 
 ## Server Functions (Advanced)
 
-### Server Functions Types
+### Server Functions 타입
 
-| Type | Execution | Use Cases |
-|------|-----------|-----------|
-| **createServerFn** | Server | DB access, secrets, server logic (default) |
-| createClientOnlyFn | Client | localStorage, window |
-| createIsomorphicFn | Both | Environment-specific implementations |
+| 타입 | 실행 위치 | 사용 시나리오 |
+|------|----------|-------------|
+| **createServerFn** | 서버 | DB 접근, 비밀키, 서버 로직 (기본) |
+| createClientOnlyFn | 클라이언트 | localStorage, window |
+| createIsomorphicFn | 양쪽 | 환경별 구현 |
 
-**Default Rule**: Use `createServerFn` unless specified otherwise
+**기본 규칙**: 별도 요청 없으면 `createServerFn` 사용
 
-### Middleware Pattern
+### Middleware 패턴
 
 ```typescript
 // 1. authMiddleware
@@ -444,7 +444,7 @@ export const authMiddleware = createMiddleware()
     return next({ context: { ...context, user: session.user } })
   })
 
-// 2. Usage
+// 2. 사용
 export const createPost = createServerFn({ method: 'POST' })
   .middleware([authMiddleware])
   .inputValidator(createPostSchema)
@@ -455,7 +455,7 @@ export const createPost = createServerFn({ method: 'POST' })
   })
 ```
 
-**Execution Order**: Middleware → inputValidator → handler
+**실행 순서**: Middleware → inputValidator → handler
 
 </server_functions_advanced>
 
@@ -465,11 +465,11 @@ export const createPost = createServerFn({ method: 'POST' })
 
 ## Error Handling
 
-| Component | Scope | Location | Required |
-|-----------|-------|----------|----------|
-| **errorComponent** | Route errors | Each route | ✅ |
+| 컴포넌트 | 처리 범위 | 위치 | 필수 |
+|---------|----------|------|-----|
+| **errorComponent** | 라우트 에러 | 각 route | ✅ |
 | **notFoundComponent** | 404 | __root.tsx | ✅ |
-| **pendingComponent** | Loading | Each route | Optional |
+| **pendingComponent** | 로딩 | 각 route | 선택 |
 
 ```typescript
 // __root.tsx
@@ -478,29 +478,29 @@ export const Route = createRootRoute({
   notFoundComponent: () => <div>404 Not Found</div>,
 })
 
-// Route level
+// Route 레벨
 export const Route = createFileRoute('/dashboard')({
   errorComponent: ({ error }) => <div>{error.message}</div>,
 })
 
-// Loader errors
+// Loader 에러
 loader: async () => {
   try {
     return { users: await getUsers() }
   } catch (error) {
-    throw new Error('Failed to load data')
+    throw new Error('데이터 로딩 실패')
   }
 }
 
-// Server Function errors
+// Server Function 에러
 .handler(async ({ data }) => {
   try {
     return await prisma.user.create({ data })
   } catch (error) {
     if (error.code === 'P2002') {
-      throw new Error('Email already exists')
+      throw new Error('이미 존재하는 이메일')
     }
-    throw new Error('Failed to create user')
+    throw new Error('사용자 생성 실패')
   }
 })
 ```