@kood/claude-code 0.2.4 → 0.3.0

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

@@ -1,31 +1,82 @@
 # 코드 컨벤션
 
-TanStack Start 프로젝트의 코드 작성 규칙.
+> TanStack Start 프로젝트 코드 작성 규칙
+
+---
+
+<naming>
 
 ## 파일 네이밍
 
-**모든 파일은 kebab-case**:
+| 타입 | 규칙 | 예시 |
+|------|------|------|
+| **일반 파일** | kebab-case | `user-profile.tsx`, `auth-service.ts` |
+| **Route 파일** | TanStack Router 규칙 | `__root.tsx`, `index.tsx`, `$id.tsx` |
+| **Hook 파일** | `use-` 접두사 | `use-user-filter.ts`, `use-auth.ts` |
+| **Component** | PascalCase (파일은 kebab) | `UserCard` in `user-card.tsx` |
 
-```
-✅ user-profile.tsx
-✅ auth-service.ts
-✅ use-user-filter.ts
+</naming>
+
+---
+
+<typescript>
+
+## TypeScript 규칙
+
+| 규칙 | 설명 | 예시 |
+|------|------|------|
+| **함수 선언** | 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'` |
+
+## 패턴
 
-❌ UserProfile.tsx
-❌ authService.ts
-❌ useUserFilter.ts
+```typescript
+// ✅ const 함수, 명시적 타입
+const getUserById = async (id: string): Promise<User> => {
+  return prisma.user.findUnique({ where: { id } })
+}
+
+// ✅ 간단한 함수도 명시적 타입
+const formatDate = (date: Date): string => {
+  return date.toISOString()
+}
+
+// ✅ any 금지 → unknown 사용
+const parseJSON = (data: string): unknown => {
+  return JSON.parse(data)
+}
+
+// ❌ any 사용 금지
+const badParse = (data: string): any => {  // ❌
+  return JSON.parse(data)
+}
+
+// ❌ function 키워드 금지
+function badFunction() {  // ❌
+  return 'use const arrow function'
+}
 ```
 
+</typescript>
+
+---
+
+<imports>
+
 ## Import 순서
 
 ```typescript
 // 1. External libraries
 import { createFileRoute } from '@tanstack/react-router'
 import { useQuery } from '@tanstack/react-query'
+import { z } from 'zod'
 
-// 2. Internal packages
+// 2. Internal packages (@/)
 import { Button } from '@/components/ui/button'
-import { prisma } from '@/lib/prisma'
+import { prisma } from '@/database/prisma'
+import { getUsers } from '@/services/user'
 
 // 3. Relative imports (route-specific)
 import { UserCard } from './-components/user-card'
@@ -33,37 +84,25 @@ import { useUsers } from './-hooks/use-users'
 
 // 4. Type imports
 import type { User } from '@/types'
+import type { UseUsersReturn } from './-hooks/use-users'
 ```
 
-## 함수 스타일
-
-```typescript
-// ✅ const 함수
-const getUserById = async (id: string): Promise<User> => {
-  return prisma.user.findUnique({ where: { id } })
-}
-
-// ✅ 명시적 반환 타입
-const formatDate = (date: Date): string => {
-  return date.toISOString()
-}
+</imports>
 
-// ❌ any 금지 → unknown 사용
-const parseJSON = (data: string): unknown => {
-  return JSON.parse(data)
-}
-```
+---
 
-## 한글 주석
+<comments>
 
-**묶음 단위로 작성** (너무 세세하게 X):
+## 한글 주석 (묶음 단위)
 
 ```typescript
+// ✅ 코드 묶음 단위 주석
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // 사용자 관련 상태
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 const [user, setUser] = useState<User | null>(null)
 const [isLoading, setIsLoading] = useState(false)
+const [error, setError] = useState<Error | null>(null)
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // 데이터 조회
@@ -75,12 +114,19 @@ const { data: users } = useQuery({
 ```
 
 ```typescript
-// ❌ 너무 세세한 주석 (금지)
+// ❌ 세세한 주석 (금지)
 const [user, setUser] = useState(null)  // 사용자 상태
 const [isLoading, setIsLoading] = useState(false)  // 로딩 상태
+const [error, setError] = useState(null)  // 에러 상태
 ```
 
-## 에러 처리
+</comments>
+
+---
+
+<error_handling>
+
+## 에러 처리 패턴
 
 ```typescript
 // lib/errors.ts
@@ -100,4 +146,58 @@ export class NotFoundError extends AppError {
     super(`${resource} not found`, 404, 'NOT_FOUND')
   }
 }
+
+export class ValidationError extends AppError {
+  constructor(message: string) {
+    super(message, 400, 'VALIDATION_ERROR')
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor() {
+    super('Unauthorized', 401, 'UNAUTHORIZED')
+  }
+}
+```
+
+## 사용 예시
+
+```typescript
+// services/user/queries.ts
+import { NotFoundError } from '@/lib/errors'
+
+export const getUserById = createServerFn({ method: 'GET' })
+  .handler(async ({ data: id }: { data: string }) => {
+    const user = await prisma.user.findUnique({ where: { id } })
+    if (!user) throw new NotFoundError('User')
+    return user
+  })
 ```
+
+</error_handling>
+
+---
+
+<examples>
+
+## 파일명 예시
+
+| 타입 | ❌ 잘못된 예시 | ✅ 올바른 예시 |
+|------|---------------|---------------|
+| Component | `UserProfile.tsx` | `user-profile.tsx` |
+| Service | `authService.ts` | `auth-service.ts` |
+| Hook | `useUserFilter.ts` | `use-user-filter.ts` |
+| Utility | `formatUtils.ts` | `format-utils.ts` |
+| Type | `UserTypes.ts` | `user-types.ts` |
+
+## Route 파일명
+
+| 경로 | 파일명 | 설명 |
+|------|--------|------|
+| `/` | `index.tsx` | 인덱스 라우트 |
+| `/users` | `users/index.tsx` | 사용자 목록 |
+| `/users/:id` | `users/$id.tsx` | 동적 라우트 |
+| `/posts/:slug` | `posts/$slug.tsx` | URL 파라미터 |
+| Layout | `__root.tsx` | Root 레이아웃 |
+
+</examples>

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

@@ -1,18 +1,25 @@
 # 환경 변수 설정
 
-TanStack Start (Vite 기반) 환경 변수 관리.
+> TanStack Start (Vite 기반) 환경 변수 관리
 
-## 핵심 개념
+<instructions>
+@../library/t3-env/index.md
+</instructions>
 
-```
-서버 전용     → process.env.DATABASE_URL     (노출 X)
-클라이언트용  → import.meta.env.VITE_*       (노출 O)
-```
+---
+
+<environment_types>
+
+| 접근 방식 | 위치 | 용도 | 노출 |
+|-----------|------|------|------|
+| `process.env.*` | Server Function | DB, API 키, 시크릿 | ❌ 서버만 |
+| `import.meta.env.VITE_*` | 클라이언트 + 서버 | 공개 설정 | ✅ 브라우저 노출 |
+
+</environment_types>
 
-| 접근 방식 | 위치 | 용도 |
-|-----------|------|------|
-| `process.env.*` | Server Function | DB, API 키, 시크릿 |
-| `import.meta.env.VITE_*` | 클라이언트 + 서버 | 공개 설정 |
+---
+
+<file_structure>
 
 ## 환경 파일 구조
 
@@ -21,17 +28,21 @@ TanStack Start (Vite 기반) 환경 변수 관리.
 ├── .env.development        # 개발 (커밋 O)
 ├── .env.production         # 프로덕션 (커밋 O)
 ├── .env.local              # 로컬 오버라이드 (커밋 X)
-└── app/config/env.ts       # 검증 및 타입
+└── src/lib/env.ts          # 검증 및 타입 (t3-env)
 ```
 
-### 로드 우선순위
+| 우선순위 | 파일 | 설명 |
+|----------|------|------|
+| 1 | `.env.{mode}.local` | 최우선 (gitignore) |
+| 2 | `.env.local` | 로컬 오버라이드 |
+| 3 | `.env.{mode}` | 환경별 설정 |
+| 4 | `.env` | 기본 설정 |
 
-```
-1. .env.{mode}.local    # 최우선 (gitignore)
-2. .env.local           # 로컬 오버라이드
-3. .env.{mode}          # 환경별 설정
-4. .env                 # 기본 설정
-```
+</file_structure>
+
+---
+
+<patterns>
 
 ## 환경 파일 예시
 
@@ -49,45 +60,50 @@ OPENAI_API_KEY=sk-xxx
 NODE_ENV=development
 VITE_APP_NAME=My App (Dev)
 VITE_API_URL=http://localhost:3001/api
-DATABASE_URL=postgresql://localhost:5432/myapp_dev
 ```
 
-## 타입 안전한 환경 변수 (Zod)
+### .env.production
+
+```env
+NODE_ENV=production
+VITE_APP_NAME=My App
+VITE_API_URL=https://api.myapp.com
+```
+
+## 타입 안전한 환경 변수 (t3-env)
 
 ```typescript
-// app/config/env.ts
+// src/lib/env.ts
+import { createEnv } from '@t3-oss/env-core'
 import { z } from 'zod'
 
-const serverEnvSchema = z.object({
-  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
-  DATABASE_URL: z.string().url(),
-  JWT_SECRET: z.string().min(32),
-  OPENAI_API_KEY: z.string().optional(),
+export const env = createEnv({
+  server: {
+    NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+    DATABASE_URL: z.string().url(),
+    JWT_SECRET: z.string().min(32),
+    OPENAI_API_KEY: z.string().optional(),
+  },
+
+  client: {
+    VITE_APP_NAME: z.string(),
+    VITE_API_URL: z.string().url(),
+  },
+
+  runtimeEnv: {
+    // Server
+    NODE_ENV: process.env.NODE_ENV,
+    DATABASE_URL: process.env.DATABASE_URL,
+    JWT_SECRET: process.env.JWT_SECRET,
+    OPENAI_API_KEY: process.env.OPENAI_API_KEY,
+
+    // Client
+    VITE_APP_NAME: import.meta.env.VITE_APP_NAME,
+    VITE_API_URL: import.meta.env.VITE_API_URL,
+  },
+
+  clientPrefix: 'VITE_',
 })
-
-const clientEnvSchema = z.object({
-  VITE_APP_NAME: z.string(),
-  VITE_API_URL: z.string().url(),
-})
-
-export type ServerEnv = z.infer<typeof serverEnvSchema>
-export type ClientEnv = z.infer<typeof clientEnvSchema>
-
-let _serverEnv: ServerEnv | null = null
-
-export const getServerEnv = (): ServerEnv => {
-  if (!_serverEnv) {
-    const result = serverEnvSchema.safeParse(process.env)
-    if (!result.success) {
-      console.error('❌ 서버 환경 변수 검증 실패:', result.error.format())
-      throw new Error('Server environment validation failed')
-    }
-    _serverEnv = result.data
-  }
-  return _serverEnv
-}
-
-export const clientEnv = clientEnvSchema.parse(import.meta.env)
 ```
 
 ## 사용 예시
@@ -95,42 +111,64 @@ export const clientEnv = clientEnvSchema.parse(import.meta.env)
 ### Server Function
 
 ```typescript
+// services/user/queries.ts
 import { createServerFn } from '@tanstack/react-start'
-import { getServerEnv } from '@/config/env'
+import { env } from '@/lib/env'
+import { prisma } from '@/database/prisma'
 
 export const getUsers = createServerFn({ method: 'GET' })
   .handler(async () => {
-    const env = getServerEnv()
-    // env.DATABASE_URL 사용
+    // env.DATABASE_URL은 서버에서만 사용 가능
+    console.log('DB URL:', env.DATABASE_URL)
+    return prisma.user.findMany()
   })
 ```
 
-### 클라이언트
+### 클라이언트 컴포넌트
 
 ```tsx
-import { clientEnv } from '@/config/env'
-
-export const AppHeader = () => (
-  <h1>{clientEnv.VITE_APP_NAME}</h1>
-)
+// components/app-header.tsx
+import { env } from '@/lib/env'
+
+export const AppHeader = (): JSX.Element => {
+  return (
+    <header>
+      <h1>{env.VITE_APP_NAME}</h1>
+      <p>API: {env.VITE_API_URL}</p>
+    </header>
+  )
+}
 ```
 
+</patterns>
+
+---
+
+<gitignore>
+
 ## .gitignore
 
 ```gitignore
+# 시크릿 포함 (절대 커밋 X)
 .env.local
 .env.*.local
 
-# 커밋해도 되는 파일 (시크릿 없음)
+# 공개 설정 (커밋 O)
 !.env
 !.env.development
 !.env.production
 ```
 
-## TypeScript 타입
+</gitignore>
+
+---
+
+<typescript_types>
+
+## TypeScript 타입 (Vite)
 
 ```typescript
-// app/vite-env.d.ts
+// src/vite-env.d.ts
 /// <reference types="vite/client" />
 
 interface ImportMetaEnv {
@@ -142,3 +180,30 @@ interface ImportMeta {
   readonly env: ImportMetaEnv
 }
 ```
+
+**참고:** t3-env 사용 시 자동으로 타입 추론됨
+
+</typescript_types>
+
+---
+
+<best_practices>
+
+| 원칙 | 설명 |
+|------|------|
+| **시크릿 분리** | `.env.local`에만 시크릿 저장, 커밋 금지 |
+| **공개 변수** | `VITE_` 접두사 사용, 브라우저 노출 허용 |
+| **타입 안전성** | t3-env 또는 Zod로 검증 |
+| **기본값** | `.env`에 안전한 기본값 설정 |
+| **문서화** | `.env.example` 파일로 필수 변수 목록 제공 |
+
+</best_practices>
+
+---
+
+<sources>
+
+- [Vite Environment Variables](https://vitejs.dev/guide/env-and-mode.html)
+- [t3-env Documentation](https://env.t3.gg/docs/introduction)
+
+</sources>

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

@@ -1,11 +1,27 @@
 # Getting Started
 
-TanStack Start 프로젝트 시작 가이드.
+> TanStack Start 프로젝트 빠른 시작
 
-## Prerequisites
+<instructions>
+@conventions.md
+@routes.md
+@services.md
+</instructions>
 
-- Node.js 18+
-- Yarn
+---
+
+<prerequisites>
+
+| 요구사항 | 버전 |
+|----------|------|
+| Node.js | 18+ |
+| 패키지 관리자 | Yarn / npm / pnpm |
+
+</prerequisites>
+
+---
+
+<installation>
 
 ## 프로젝트 생성
 
@@ -15,7 +31,7 @@ cd my-app
 yarn install
 ```
 
-## 필수 패키지 설치
+## 필수 패키지
 
 ```bash
 # Database (Prisma 7.x)
@@ -29,9 +45,25 @@ yarn add zod
 yarn add @tanstack/react-query
 ```
 
-## 초기 설정
+</installation>
+
+---
+
+<project_setup>
+
+## 프로젝트 구조
+
+```
+src/
+├── routes/
+│   ├── __root.tsx       # Root Layout
+│   └── index.tsx        # Home Page
+├── lib/
+│   └── query-client.ts  # Query Client 설정
+└── app.config.ts        # TanStack Start 설정
+```
 
-### app.config.ts
+## app.config.ts
 
 ```typescript
 import { defineConfig } from '@tanstack/react-start/config'
@@ -43,7 +75,7 @@ export default defineConfig({
 })
 ```
 
-### Root Route
+## Root Route
 
 ```tsx
 // src/routes/__root.tsx
@@ -67,7 +99,7 @@ const RootComponent = (): JSX.Element => {
 }
 ```
 
-### Home Route
+## Home Route
 
 ```tsx
 // src/routes/index.tsx
@@ -80,13 +112,16 @@ export const Route = createFileRoute('/')({
 const HomePage = (): JSX.Element => {
   return (
     <div>
-      <h1 className="text-2xl font-bold">Welcome</h1>
+      <h1 className="text-2xl font-bold">Welcome to TanStack Start</h1>
+      <p className="mt-4 text-gray-600">
+        Full-stack React framework powered by TanStack Router
+      </p>
     </div>
   )
 }
 ```
 
-### Query Client
+## Query Client 설정
 
 ```typescript
 // src/lib/query-client.ts
@@ -95,23 +130,49 @@ import { QueryClient } from '@tanstack/react-query'
 export const createQueryClient = (): QueryClient => {
   return new QueryClient({
     defaultOptions: {
-      queries: { staleTime: 60 * 1000, retry: 1 },
+      queries: {
+        staleTime: 60 * 1000,  // 1분
+        retry: 1,
+      },
     },
   })
 }
 ```
 
-## 개발 명령어
+</project_setup>
+
+---
+
+<commands>
 
 | Command | Description |
 |---------|-------------|
-| `yarn dev` | 개발 서버 시작 |
+| `yarn dev` | 개발 서버 시작 (http://localhost:3000) |
 | `yarn build` | 프로덕션 빌드 |
-| `yarn start` | 프로덕션 서버 |
+| `yarn start` | 프로덕션 서버 실행 |
+
+</commands>
+
+---
+
+<next_steps>
+
+| 문서 | 내용 |
+|------|------|
+| [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 패턴 |
+
+</next_steps>
+
+---
+
+<sources>
 
-## 다음 단계
+- [TanStack Start Server Functions](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions)
+- [TanStack Router Data Loading](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading)
+- [TanStack Start Middleware](https://tanstack.com/start/latest/docs/framework/react/guide/middleware)
 
-- [conventions.md](./conventions.md) - 코드 컨벤션
-- [routes.md](./routes.md) - 라우트 구조
-- [hooks.md](./hooks.md) - Custom Hook 패턴
-- [services.md](./services.md) - Service Layer
+</sources>