@kood/claude-code 0.3.6 → 0.3.8

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

@@ -1,26 +1,26 @@
-# 코드 컨벤션
+# Code Conventions
 
-> TanStack Start 프로젝트 코드 작성 규칙
+> TanStack Start project coding rules
 
 ---
 
 <naming>
 
-## 파일 네이밍
+## File Naming
 
-> ⚠️ **camelCase 파일명 금지** - 모든 파일명은 **kebab-case** 사용
+> ⚠️ **No camelCase filenames** - All filenames must use **kebab-case**
 
-| 타입 | 규칙 | 예시 |
+| Type | Rule | Example |
 |------|------|------|
-| **일반 파일** | kebab-case | `user-profile.tsx`, `auth-service.ts` |
-| **Route 파일** | TanStack Router 규칙 | `__root.tsx`, `index.tsx`, `$id.tsx` |
-| **Hook 파일** | `use-` 접두사 + kebab-case | `use-user-filter.ts`, `use-auth.ts` |
-| **Component** | PascalCase 컴포넌트, kebab-case 파일 | `UserCard` in `user-card.tsx` |
+| **General Files** | kebab-case | `user-profile.tsx`, `auth-service.ts` |
+| **Route Files** | TanStack Router rules | `__root.tsx`, `index.tsx`, `$id.tsx` |
+| **Hook Files** | `use-` prefix + kebab-case | `use-user-filter.ts`, `use-auth.ts` |
+| **Component** | PascalCase component, kebab-case file | `UserCard` in `user-card.tsx` |
 | **Server Function** | kebab-case | `get-users.ts`, `create-post.ts` |
 
 ```
-❌ camelCase 금지: getUserById.ts, authService.ts, useUserFilter.ts
-✅ kebab-case 필수: get-user-by-id.ts, auth-service.ts, use-user-filter.ts
+❌ No camelCase: getUserById.ts, authService.ts, useUserFilter.ts
+✅ kebab-case required: get-user-by-id.ts, auth-service.ts, use-user-filter.ts
 ```
 
 </naming>
@@ -29,39 +29,39 @@
 
 <typescript>
 
-## TypeScript 규칙
+## TypeScript Rules
 
-| 규칙 | 설명 | 예시 |
+| Rule | Description | Example |
 |------|------|------|
-| **함수 선언** | const 함수, 명시적 return type | `const fn = (): ReturnType => {}` |
-| **타입 정의** | interface (객체), type (유니온) | `interface User {}`, `type Status = 'a' \| 'b'` |
-| **any 금지** | unknown 사용 | `const data: unknown = JSON.parse(str)` |
-| **Import 타입** | type import 분리 | `import type { User } from '@/types'` |
+| **Function Declaration** | const function, explicit return type | `const fn = (): ReturnType => {}` |
+| **Type Definition** | interface (objects), type (unions) | `interface User {}`, `type Status = 'a' \| 'b'` |
+| **No any** | Use unknown | `const data: unknown = JSON.parse(str)` |
+| **Import Types** | Separate type imports | `import type { User } from '@/types'` |
 
-## 패턴
+## Patterns
 
 ```typescript
-// ✅ const 함수, 명시적 타입
+// ✅ const function, explicit type
 const getUserById = async (id: string): Promise<User> => {
   return prisma.user.findUnique({ where: { id } })
 }
 
-// ✅ 간단한 함수도 명시적 타입
+// ✅ Simple functions also need explicit types
 const formatDate = (date: Date): string => {
   return date.toISOString()
 }
 
-// ✅ any 금지 → unknown 사용
+// ✅ No any → use unknown
 const parseJSON = (data: string): unknown => {
   return JSON.parse(data)
 }
 
-// ❌ any 사용 금지
+// ❌ No any
 const badParse = (data: string): any => {  // ❌
   return JSON.parse(data)
 }
 
-// ❌ function 키워드 금지
+// ❌ No function keyword
 function badFunction() {  // ❌
   return 'use const arrow function'
 }
@@ -73,7 +73,7 @@ function badFunction() {  // ❌
 
 <imports>
 
-## Import 순서
+## Import Order
 
 ```typescript
 // 1. External libraries
@@ -101,19 +101,19 @@ import type { UseUsersReturn } from './-hooks/use-users'
 
 <comments>
 
-## 한글 주석 (묶음 단위)
+## Korean Comments (Code Blocks)
 
 ```typescript
-// ✅ 코드 묶음 단위 주석
+// ✅ Comments per code block
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// 사용자 관련 상태
+// User-related state
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 const [user, setUser] = useState<User | null>(null)
 const [isLoading, setIsLoading] = useState(false)
 const [error, setError] = useState<Error | null>(null)
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// 데이터 조회
+// Data fetching
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 const { data: users } = useQuery({
   queryKey: ['users'],
@@ -122,10 +122,10 @@ const { data: users } = useQuery({
 ```
 
 ```typescript
-// ❌ 세세한 주석 (금지)
-const [user, setUser] = useState(null)  // 사용자 상태
-const [isLoading, setIsLoading] = useState(false)  // 로딩 상태
-const [error, setError] = useState(null)  // 에러 상태
+// ❌ Line-by-line comments (forbidden)
+const [user, setUser] = useState(null)  // User state
+const [isLoading, setIsLoading] = useState(false)  // Loading state
+const [error, setError] = useState(null)  // Error state
 ```
 
 </comments>
@@ -134,7 +134,7 @@ const [error, setError] = useState(null)  // 에러 상태
 
 <error_handling>
 
-## 에러 처리 패턴
+## Error Handling Pattern
 
 ```typescript
 // lib/errors.ts
@@ -168,7 +168,7 @@ export class UnauthorizedError extends AppError {
 }
 ```
 
-## 사용 예시
+## Usage Example
 
 ```typescript
 // services/user/queries.ts
@@ -188,9 +188,9 @@ export const getUserById = createServerFn({ method: 'GET' })
 
 <examples>
 
-## 파일명 예시
+## Filename Examples
 
-| 타입 | ❌ 잘못된 예시 | ✅ 올바른 예시 |
+| Type | ❌ Wrong | ✅ Correct |
 |------|---------------|---------------|
 | Component | `UserProfile.tsx` | `user-profile.tsx` |
 | Service | `authService.ts` | `auth-service.ts` |
@@ -198,14 +198,14 @@ export const getUserById = createServerFn({ method: 'GET' })
 | Utility | `formatUtils.ts` | `format-utils.ts` |
 | Type | `UserTypes.ts` | `user-types.ts` |
 
-## Route 파일명
+## Route Filenames
 
-| 경로 | 파일명 | 설명 |
+| Path | Filename | Description |
 |------|--------|------|
-| `/` | `index.tsx` | 인덱스 라우트 |
-| `/users` | `users/index.tsx` | 사용자 목록 |
-| `/users/:id` | `users/$id.tsx` | 동적 라우트 |
-| `/posts/:slug` | `posts/$slug.tsx` | URL 파라미터 |
-| Layout | `__root.tsx` | Root 레이아웃 |
+| `/` | `index.tsx` | Index route |
+| `/users` | `users/index.tsx` | User list |
+| `/users/:id` | `users/$id.tsx` | Dynamic route |
+| `/posts/:slug` | `posts/$slug.tsx` | URL parameter |
+| Layout | `__root.tsx` | Root layout |
 
 </examples>

package/templates/tanstack-start/docs/guides/env-setup.md

@@ -1,6 +1,6 @@
-# 환경 변수 설정
+# Environment Variables Setup
 
-> TanStack Start (Vite 기반) 환경 변수 관리
+> TanStack Start (Vite-based) Environment Variables Management
 
 <instructions>
 @../library/t3-env/index.md
@@ -10,10 +10,10 @@
 
 <environment_types>
 
-| 접근 방식 | 위치 | 용도 | 노출 |
-|-----------|------|------|------|
-| `process.env.*` | Server Function | DB, API 키, 시크릿 | ❌ 서버만 |
-| `import.meta.env.VITE_*` | 클라이언트 + 서버 | 공개 설정 | ✅ 브라우저 노출 |
+| Access Method | Location | Purpose | Exposure |
+|---------------|----------|---------|----------|
+| `process.env.*` | Server Function | DB, API keys, secrets | ❌ Server only |
+| `import.meta.env.VITE_*` | Client + Server | Public configuration | ✅ Browser exposed |
 
 </environment_types>
 
@@ -21,22 +21,22 @@
 
 <file_structure>
 
-## 환경 파일 구조
+## Environment File Structure
 
 ```
-├── .env                    # 기본 (커밋 O)
-├── .env.development        # 개발 (커밋 O)
-├── .env.production         # 프로덕션 (커밋 O)
-├── .env.local              # 로컬 오버라이드 (커밋 X)
-└── src/lib/env.ts          # 검증 및 타입 (t3-env)
+├── .env                    # Default (commit ✓)
+├── .env.development        # Development (commit ✓)
+├── .env.production         # Production (commit ✓)
+├── .env.local              # Local override (commit ✗)
+└── src/lib/env.ts          # Validation and types (t3-env)
 ```
 
-| 우선순위 | 파일 | 설명 |
-|----------|------|------|
-| 1 | `.env.{mode}.local` | 최우선 (gitignore) |
-| 2 | `.env.local` | 로컬 오버라이드 |
-| 3 | `.env.{mode}` | 환경별 설정 |
-| 4 | `.env` | 기본 설정 |
+| Priority | File | Description |
+|----------|------|-------------|
+| 1 | `.env.{mode}.local` | Highest priority (gitignore) |
+| 2 | `.env.local` | Local override |
+| 3 | `.env.{mode}` | Environment-specific config |
+| 4 | `.env` | Default config |
 
 </file_structure>
 
@@ -44,9 +44,9 @@
 
 <patterns>
 
-## 환경 파일 예시
+## Environment File Examples
 
-### .env.local (gitignore, 시크릿)
+### .env.local (gitignore, secrets)
 
 ```env
 DATABASE_URL=postgresql://user:password@localhost:5432/myapp
@@ -70,7 +70,7 @@ VITE_APP_NAME=My App
 VITE_API_URL=https://api.myapp.com
 ```
 
-## 타입 안전한 환경 변수 (t3-env)
+## Type-Safe Environment Variables (t3-env)
 
 ```typescript
 // src/lib/env.ts
@@ -106,7 +106,7 @@ export const env = createEnv({
 })
 ```
 
-## 사용 예시
+## Usage Examples
 
 ### Server Function
 
@@ -118,13 +118,13 @@ import { prisma } from '@/database/prisma'
 
 export const getUsers = createServerFn({ method: 'GET' })
   .handler(async () => {
-    // env.DATABASE_URL은 서버에서만 사용 가능
+    // env.DATABASE_URL is only available on server
     console.log('DB URL:', env.DATABASE_URL)
     return prisma.user.findMany()
   })
 ```
 
-### 클라이언트 컴포넌트
+### Client Component
 
 ```tsx
 // components/app-header.tsx
@@ -149,11 +149,11 @@ export const AppHeader = (): JSX.Element => {
 ## .gitignore
 
 ```gitignore
-# 시크릿 포함 (절대 커밋 X)
+# Contains secrets (never commit)
 .env.local
 .env.*.local
 
-# 공개 설정 (커밋 O)
+# Public config (safe to commit)
 !.env
 !.env.development
 !.env.production
@@ -165,7 +165,7 @@ export const AppHeader = (): JSX.Element => {
 
 <typescript_types>
 
-## TypeScript 타입 (Vite)
+## TypeScript Types (Vite)
 
 ```typescript
 // src/vite-env.d.ts
@@ -181,7 +181,7 @@ interface ImportMeta {
 }
 ```
 
-**참고:** t3-env 사용 시 자동으로 타입 추론됨
+**Note:** Types are automatically inferred when using t3-env
 
 </typescript_types>
 
@@ -189,13 +189,13 @@ interface ImportMeta {
 
 <best_practices>
 
-| 원칙 | 설명 |
-|------|------|
-| **시크릿 분리** | `.env.local`에만 시크릿 저장, 커밋 금지 |
-| **공개 변수** | `VITE_` 접두사 사용, 브라우저 노출 허용 |
-| **타입 안전성** | t3-env 또는 Zod로 검증 |
-| **기본값** | `.env`에 안전한 기본값 설정 |
-| **문서화** | `.env.example` 파일로 필수 변수 목록 제공 |
+| Principle | Description |
+|-----------|-------------|
+| **Separate Secrets** | Store secrets only in `.env.local`, never commit |
+| **Public Variables** | Use `VITE_` prefix, safe for browser exposure |
+| **Type Safety** | Validate with t3-env or Zod |
+| **Default Values** | Set safe defaults in `.env` |
+| **Documentation** | Provide required variable list in `.env.example` |
 
 </best_practices>
 

package/templates/tanstack-start/docs/guides/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-> TanStack Start 프로젝트 빠른 시작
+> TanStack Start project quick start
 
 <instructions>
 @conventions.md
@@ -12,10 +12,10 @@
 
 <prerequisites>
 
-| 요구사항 | 버전 |
+| Requirement | Version |
 |----------|------|
 | Node.js | 18+ |
-| 패키지 관리자 | Yarn / npm / pnpm |
+| Package Manager | Yarn / npm / pnpm |
 
 </prerequisites>
 
@@ -23,7 +23,7 @@
 
 <installation>
 
-## 프로젝트 생성
+## Create Project
 
 ```bash
 npx create-tsrouter-app@latest my-app --template start
@@ -31,7 +31,7 @@ cd my-app
 yarn install
 ```
 
-## 필수 패키지
+## Required Packages
 
 ```bash
 # Database (Prisma 7.x)
@@ -51,7 +51,7 @@ yarn add @tanstack/react-query
 
 <project_setup>
 
-## 프로젝트 구조
+## Project Structure
 
 ```
 src/
@@ -59,8 +59,8 @@ src/
 │   ├── __root.tsx       # Root Layout
 │   └── index.tsx        # Home Page
 ├── lib/
-│   └── query-client.ts  # Query Client 설정
-└── app.config.ts        # TanStack Start 설정
+│   └── query-client.ts  # Query Client setup
+└── app.config.ts        # TanStack Start config
 ```
 
 ## app.config.ts
@@ -121,7 +121,7 @@ const HomePage = (): JSX.Element => {
 }
 ```
 
-## Query Client 설정
+## Query Client Setup
 
 ```typescript
 // src/lib/query-client.ts
@@ -131,7 +131,7 @@ export const createQueryClient = (): QueryClient => {
   return new QueryClient({
     defaultOptions: {
       queries: {
-        staleTime: 60 * 1000,  // 1분
+        staleTime: 60 * 1000,  // 1 minute
         retry: 1,
       },
     },
@@ -147,9 +147,9 @@ export const createQueryClient = (): QueryClient => {
 
 | Command | Description |
 |---------|-------------|
-| `yarn dev` | 개발 서버 시작 (http://localhost:3000) |
-| `yarn build` | 프로덕션 빌드 |
-| `yarn start` | 프로덕션 서버 실행 |
+| `yarn dev` | Start development server (http://localhost:3000) |
+| `yarn build` | Production build |
+| `yarn start` | Start production server |
 
 </commands>
 
@@ -157,13 +157,13 @@ export const createQueryClient = (): QueryClient => {
 
 <next_steps>
 
-| 문서 | 내용 |
+| Document | Content |
 |------|------|
-| [conventions.md](./conventions.md) | 코드 컨벤션, 파일명 규칙 |
-| [env-setup.md](./env-setup.md) | 환경 변수 설정 |
-| [routes.md](./routes.md) | 라우트 구조, 파일 기반 라우팅 |
-| [services.md](./services.md) | Server Functions, 데이터 레이어 |
-| [hooks.md](./hooks.md) | Custom Hook 패턴 |
+| [conventions.md](./conventions.md) | Code conventions, naming rules |
+| [env-setup.md](./env-setup.md) | Environment variable setup |
+| [routes.md](./routes.md) | Route structure, file-based routing |
+| [services.md](./services.md) | Server Functions, data layer |
+| [hooks.md](./hooks.md) | Custom Hook patterns |
 
 </next_steps>
 

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

@@ -1,6 +1,6 @@
-# Custom Hook 패턴
+# Custom Hook Patterns
 
-> 페이지/섹션의 모든 로직, 상태, 라이프사이클 중앙화
+> Centralize all logic, state, and lifecycle for pages/sections
 
 <instructions>
 @../library/tanstack-router/hooks.md
@@ -10,18 +10,46 @@
 
 ---
 
+<mandatory_separation>
+
+## ⚠️ Required Rule: Custom Hook Separation
+
+**All pages must separate Custom Hooks into `-hooks/` folder.**
+
+- Must be separated **regardless of page size** (line count)
+- Even simple 10-line pages require Hook separation
+- Page components should only handle UI rendering
+
+```typescript
+// ✅ Correct structure
+routes/users/
+├── index.tsx              // UI only
+├── -hooks/
+│   └── use-users.ts       // All logic
+├── -components/
+└── -functions/
+
+// ❌ Wrong structure
+routes/users/
+└── index.tsx              // UI + logic mixed
+```
+
+</mandatory_separation>
+
+---
+
 <hook_order>
 
-## Hook 내부 순서 (필수)
+## Hook Internal Order (Required)
 
-| 순서 | Hook 타입 | 예시 |
-|------|-----------|------|
+| Order | Hook Type | Examples |
+|-------|-----------|----------|
 | 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 | 부수 효과 |
+| 5 | useMemo | Computed values |
+| 6 | useEffect | Side effects |
 
 </hook_order>
 
@@ -29,7 +57,7 @@
 
 <patterns>
 
-## Page Hook 패턴
+## Page Hook Pattern
 
 ```typescript
 // routes/users/-hooks/use-users.ts
@@ -131,7 +159,7 @@ export const useUsers = (): UseUsersReturn => {
 }
 ```
 
-## Filter Hook 패턴
+## Filter Hook Pattern
 
 ```typescript
 // routes/users/-hooks/use-user-filter.ts
@@ -158,7 +186,7 @@ export const useUserFilter = (): UseUserFilterReturn => {
 }
 ```
 
-## Form Hook 패턴
+## Form Hook Pattern
 
 ```typescript
 // routes/users/-hooks/use-user-form.ts
@@ -227,24 +255,24 @@ export const useUserForm = (): UseUserFormReturn => {
 
 <anti_patterns>
 
-## ❌ 잘못된 순서
+## ❌ Wrong Order
 
 ```typescript
-// ❌ 순서가 뒤섞인 잘못된 예시
+// ❌ Mixed order (wrong example)
 export const useBadHook = () => {
-  const queryClient = useQueryClient()  // ❌ Global Hook이 먼저
+  const queryClient = useQueryClient()  // ❌ Global Hook first
 
-  useEffect(() => { /* ... */ }, [])    // ❌ useEffect가 중간에
+  useEffect(() => { /* ... */ }, [])    // ❌ useEffect in the middle
 
-  const [state, setState] = useState()  // ❌ State가 나중에
+  const [state, setState] = useState()  // ❌ State later
 
-  const { data } = useQuery({ /* ... */ })  // ❌ Query가 Effect 다음에
+  const { data } = useQuery({ /* ... */ })  // ❌ Query after Effect
 
-  const computed = useMemo(() => {}, [])  // ❌ useMemo 위치 잘못됨
+  const computed = useMemo(() => {}, [])  // ❌ useMemo wrong position
 }
 ```
 
-## ✅ 올바른 순서
+## ✅ Correct Order
 
 ```typescript
 export const useGoodHook = () => {
@@ -278,12 +306,12 @@ export const useGoodHook = () => {
 
 ## TanStack Router Hooks
 
-| Hook | 용도 | 예시 |
-|------|------|------|
-| `useParams` | URL 파라미터 | `const { id } = useParams({ from: '/users/$id' })` |
-| `useNavigate` | 프로그래밍 방식 네비게이션 | `navigate({ to: '/users' })` |
+| Hook | Purpose | Example |
+|------|---------|---------|
+| `useParams` | URL parameters | `const { id } = useParams({ from: '/users/$id' })` |
+| `useNavigate` | Programmatic navigation | `navigate({ to: '/users' })` |
 | `useSearch` | Search params | `const { page } = useSearch({ from: '/users' })` |
-| `useLoaderData` | Loader 데이터 | `const user = Route.useLoaderData()` |
+| `useLoaderData` | Loader data | `const user = Route.useLoaderData()` |
 | `useRouteContext` | Route context | `const { auth } = useRouteContext({ from: '__root__' })` |
 
 ```typescript
@@ -314,11 +342,11 @@ export const useUserDetail = () => {
 
 ## TanStack Query Hooks
 
-| Hook | 용도 | 특징 |
-|------|------|------|
-| `useQuery` | 데이터 조회 (GET) | 자동 캐싱, 재검증 |
-| `useMutation` | 데이터 변경 (POST/PUT/DELETE) | 성공 시 캐시 무효화 |
-| `useQueryClient` | 캐시 제어 | `invalidateQueries`, `setQueryData` |
+| Hook | Purpose | Features |
+|------|---------|----------|
+| `useQuery` | Data fetching (GET) | Auto caching, revalidation |
+| `useMutation` | Data modification (POST/PUT/DELETE) | Cache invalidation on success |
+| `useQueryClient` | Cache control | `invalidateQueries`, `setQueryData` |
 
 ```typescript
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
@@ -350,13 +378,13 @@ export const useUsers = () => {
 
 <best_practices>
 
-| 원칙 | 설명 |
-|------|------|
-| **순서 준수** | State → Global → Query → Handlers → Memo → Effect |
-| **타입 정의** | Return 타입 명시 (interface) |
-| **단일 책임** | 하나의 Hook은 하나의 관심사 |
-| **useCallback** | Event handler는 useCallback으로 메모이제이션 |
-| **명확한 네이밍** | `use-users.ts`, `use-user-filter.ts` |
+| Principle | Description |
+|-----------|-------------|
+| **Order Compliance** | State → Global → Query → Handlers → Memo → Effect |
+| **Type Definition** | Explicit return type (interface) |
+| **Single Responsibility** | One Hook, one concern |
+| **useCallback** | Memoize event handlers with useCallback |
+| **Clear Naming** | `use-users.ts`, `use-user-filter.ts` |
 
 </best_practices>