@kood/claude-code 0.1.2 → 0.1.4

package/templates/tanstack-start/CLAUDE.md

@@ -44,6 +44,7 @@
 ❌ Server Function에 middleware 누락 금지 (인증 필요 시)
 ❌ handler 내부에서 수동 검증 금지 (inputValidator 사용)
 ❌ handler 내부에서 수동 인증 체크 금지 (middleware 사용)
+❌ 클라이언트에서 Server Function 직접 호출 금지 → TanStack Query 필수
 ```
 
 ### 코드 검색 금지 사항
@@ -53,6 +54,36 @@
 ✅ 코드베이스 검색 시 sgrep 사용 필수
 ```
 
+### Custom Hook 순서 금지 사항
+```
+❌ Custom Hook 내부 순서 무시 금지
+✅ 반드시 아래 순서 준수:
+   1. State (useState, zustand store)
+   2. Global Hooks (useParams, useNavigate, useQueryClient 등)
+   3. React Query (useQuery → useMutation 순서)
+   4. Event Handlers & Functions
+   5. useMemo
+   6. useEffect
+```
+
+### 코드 작성 규칙
+```
+✅ 모든 한글 텍스트는 UTF-8 인코딩 유지
+✅ 코드 묶음 단위로 한글 주석 작성 (너무 세세하게 X)
+✅ Prisma Multi-File 모든 요소에 한글 주석 필수
+```
+
+### Prisma Multi-File 구조 (필수)
+```
+prisma/
+├── schema/
+│   ├── +base.prisma      # datasource, generator 설정
+│   ├── +enum.prisma      # 모든 enum 정의
+│   ├── user.prisma       # User 모델
+│   ├── post.prisma       # Post 모델
+│   └── ...               # 기타 모델별 파일
+```
+
 ---
 
 ## ✅ ALWAYS DO (필수 실행)
@@ -112,7 +143,7 @@ docs: API 문서 업데이트
 | 작업 | 문서 경로 | 필독 여부 |
 |------|----------|----------|
 | **전체 가이드** | `docs/README.md` | 🔴 필수 |
-| **Git 규칙** | `docs/git/index.md` | 🔴 필수 |
+| **Git 규칙** | `docs/git/git.md` | 🔴 필수 |
 | **MCP 도구** | `docs/mcp/` | 🔴 필수 |
 | **Gemini Review** | `docs/skills/gemini-review/` | 🟡 복잡한 작업 시 |
 | **UI 개발** | `docs/design/` | 🟡 해당 시 |
@@ -243,17 +274,24 @@ export const Route = createFileRoute('/users')({
 })
 ```
 
-### TanStack Query
+### TanStack Query (서버 연동 시 필수)
 ```tsx
+// ✅ 데이터 조회: useQuery 필수
+const getPosts = useServerFn(getServerPosts)
 const { data } = useQuery({
   queryKey: ['users'],
-  queryFn: () => getUsers(),
+  queryFn: () => getPosts(),
 })
 
+// ✅ 데이터 변경: useMutation 필수
+const createPostFn = useServerFn(createPost)
 const mutation = useMutation({
-  mutationFn: createUser,
+  mutationFn: createPostFn,
   onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
 })
+
+// ❌ 금지: Server Function 직접 호출
+// useEffect(() => { getPosts().then(setData) }, [])
 ```
 
 ---
@@ -273,7 +311,7 @@ const mutation = useMutation({
 ## 🔗 Quick Links
 
 - [문서 가이드](./docs/README.md)
-- [Git 규칙](./docs/git/index.md)
+- [Git 규칙](./docs/git/git.md)
 - [MCP 가이드](./docs/mcp/index.md)
 - [디자인 가이드](./docs/design/index.md)
 - [아키텍처](./docs/architecture/architecture.md)

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

@@ -21,8 +21,9 @@ TanStack Start 애플리케이션의 기술 아키텍처 가이드입니다.
 │                                                                  │
 │  ┌────────────────────────────────────────────────────────────┐ │
 │  │                    Server Functions                         │ │
-│  │   - createServerFn({ method: 'GET' })  → Queries           │ │
-│  │   - createServerFn({ method: 'POST' }) → Mutations         │ │
+│  │   - src/functions/          → 글로벌 서버 함수             │ │
+│  │   - routes/-functions/      → 페이지 전용 서버 함수        │ │
+│  │   - middlewares/            → 공통 미들웨어                │ │
 │  └────────────────────────────┬───────────────────────────────┘ │
 │                               │                                  │
 │  ┌────────────────────────────▼───────────────────────────────┐ │
@@ -54,10 +55,17 @@ my-app/
 │   ├── routes/                     # 파일 기반 라우팅
 │   │   ├── __root.tsx              # Root layout
 │   │   ├── index.tsx               # Home (/)
+│   │   ├── -functions/             # 글로벌 라우트 레벨 서버 함수
+│   │   │   ├── index.ts            # re-export
+│   │   │   └── get-session.ts      # 세션 조회 함수
 │   │   └── users/
 │   │       ├── index.tsx           # /users
 │   │       ├── $id.tsx             # /users/:id
 │   │       ├── route.tsx           # route 설정 (선택)
+│   │       ├── -functions/         # 페이지 전용 서버 함수
+│   │       │   ├── index.ts        # re-export
+│   │       │   ├── get-users.ts    # 사용자 목록 조회
+│   │       │   └── create-user.ts  # 사용자 생성
 │   │       ├── -components/        # 페이지 전용 컴포넌트
 │   │       │   └── user-card.tsx
 │   │       ├── -sections/          # 섹션 분리
@@ -65,6 +73,14 @@ my-app/
 │   │       │   └── user-filter-section.tsx
 │   │       └── -hooks/             # 페이지 전용 훅
 │   │           └── use-users.ts
+│   ├── functions/                  # 글로벌 서버 함수
+│   │   ├── index.ts                # re-export
+│   │   ├── get-current-user.ts     # 현재 사용자 조회
+│   │   ├── validate-session.ts     # 세션 검증
+│   │   └── middlewares/            # 서버 함수 미들웨어
+│   │       ├── index.ts            # re-export
+│   │       ├── auth.ts             # 인증 미들웨어
+│   │       └── rate-limit.ts       # 레이트 리밋 미들웨어
 │   ├── components/                 # 공통 컴포넌트
 │   │   └── ui/
 │   │       ├── button.tsx
@@ -117,6 +133,7 @@ my-app/
 routes/<route-name>/
 ├── index.tsx              # 페이지 컴포넌트
 ├── route.tsx              # route 설정 (loader, beforeLoad)
+├── -functions/            # 페이지 전용 서버 함수
 ├── -components/           # 페이지 전용 컴포넌트
 ├── -sections/             # 섹션 분리 (복잡한 경우)
 └── -hooks/                # 페이지 전용 훅
@@ -124,8 +141,9 @@ routes/<route-name>/
 
 **특징**:
 - `-` 접두사 폴더는 라우트에서 제외
-- 페이지별로 컴포넌트, 섹션, 훅을 분리
+- 페이지별로 서버 함수, 컴포넌트, 섹션, 훅을 분리
 - Section은 UI 영역 단위, Component는 재사용 단위
+- `-functions/`는 해당 페이지에서만 사용하는 서버 함수
 
 ```tsx
 // routes/users/index.tsx
@@ -204,7 +222,119 @@ export const createUser = createServerFn({ method: 'POST' })
   })
 ```
 
-### 3. Database Layer (Data Access)
+### 3. Server Functions Layer
+
+서버 함수를 체계적으로 구성합니다. 파일당 하나의 서버 함수만 정의합니다.
+
+```
+src/functions/                    # 글로벌 서버 함수
+├── index.ts                      # re-export
+├── <function-name>.ts            # 개별 서버 함수
+└── middlewares/                  # 서버 함수 미들웨어
+    ├── index.ts                  # re-export
+    └── <middleware-name>.ts      # 개별 미들웨어
+
+routes/<route-name>/-functions/   # 페이지 전용 서버 함수
+├── index.ts                      # re-export
+└── <function-name>.ts            # 개별 서버 함수
+```
+
+**규칙**:
+- **파일당 하나의 함수**: 각 파일에는 하나의 서버 함수만 정의
+- **명확한 네이밍**: 파일명이 곧 함수의 역할 (`get-users.ts`, `create-user.ts`)
+- **글로벌 vs 로컬**: 여러 페이지에서 사용 → `src/functions/`, 특정 페이지 전용 → `-functions/`
+
+**글로벌 서버 함수** - 여러 페이지에서 공유:
+
+```typescript
+// src/functions/get-current-user.ts
+import { createServerFn } from '@tanstack/react-start'
+import { prisma } from '@/database/prisma'
+import { authMiddleware } from './middlewares'
+
+export const getCurrentUser = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    return prisma.user.findUnique({
+      where: { id: context.userId },
+    })
+  })
+```
+
+```typescript
+// src/functions/index.ts
+export { getCurrentUser } from './get-current-user'
+export { validateSession } from './validate-session'
+```
+
+**페이지 전용 서버 함수** - 특정 페이지에서만 사용:
+
+```typescript
+// routes/users/-functions/get-users.ts
+import { createServerFn } from '@tanstack/react-start'
+import { prisma } from '@/database/prisma'
+
+export const getUsers = createServerFn({ method: 'GET' })
+  .handler(async () => {
+    return prisma.user.findMany({
+      orderBy: { createdAt: 'desc' },
+    })
+  })
+```
+
+```typescript
+// routes/users/-functions/create-user.ts
+import { createServerFn } from '@tanstack/react-start'
+import { prisma } from '@/database/prisma'
+import { createUserSchema } from '@/services/user/schemas'
+
+export const createUser = createServerFn({ method: 'POST' })
+  .inputValidator(createUserSchema)
+  .handler(async ({ data }) => {
+    return prisma.user.create({ data })
+  })
+```
+
+```typescript
+// routes/users/-functions/index.ts
+export { getUsers } from './get-users'
+export { createUser } from './create-user'
+```
+
+**미들웨어** - 공통 로직 재사용:
+
+```typescript
+// src/functions/middlewares/auth.ts
+import { createMiddleware } from '@tanstack/react-start'
+
+export const authMiddleware = createMiddleware()
+  .server(async ({ next }) => {
+    const session = await getSession()
+    if (!session) {
+      throw new Error('Unauthorized')
+    }
+    return next({ context: { userId: session.userId } })
+  })
+```
+
+```typescript
+// src/functions/middlewares/rate-limit.ts
+import { createMiddleware } from '@tanstack/react-start'
+
+export const rateLimitMiddleware = createMiddleware()
+  .server(async ({ next }) => {
+    // 레이트 리밋 로직
+    return next()
+  })
+```
+
+```typescript
+// src/functions/middlewares/index.ts
+export { authMiddleware } from './auth'
+export { rateLimitMiddleware } from './rate-limit'
+```
+
+### 4. Database Layer (Data Access)
 
 Prisma를 통한 데이터 액세스를 담당합니다.
 

package/templates/tanstack-start/docs/commands/git.md

@@ -0,0 +1,275 @@
+# Git 워크플로우
+
+---
+
+## ⛔ NEVER (절대 금지)
+
+```
+❌ 커밋에 "Generated with Claude Code" 포함
+❌ 커밋에 "🤖" 또는 AI 관련 이모지 포함
+❌ 커밋에 "Co-Authored-By:" 헤더 포함
+❌ 커밋에 AI/봇이 작성했다는 어떤 표시도 포함
+❌ 커밋 메시지 여러 줄 작성
+❌ 커밋 메시지에 이모지 사용
+❌ 커밋 메시지에 마침표(.) 사용
+❌ 여러 작업을 하나의 커밋으로 퉁치기
+```
+
+---
+
+## ✅ ALWAYS (필수)
+
+### 작업 완료 후 반드시 실행
+
+```bash
+git add <관련 파일들>
+git commit -m "<prefix>: <설명>"
+```
+
+### ⭐ 커밋 분리 원칙
+
+**하나의 커밋 = 하나의 논리적 변경 단위**
+
+```bash
+# ❌ 잘못된 방식: 모든 작업을 하나로 퉁침
+git add .
+git commit -m "feat: 여러 기능 추가"
+
+# ✅ 올바른 방식: 논리적 단위로 분리
+git add src/auth/
+git commit -m "feat: 사용자 인증 기능 추가"
+
+git add src/users/
+git commit -m "feat: 사용자 관리 기능 추가"
+
+git add docs/
+git commit -m "docs: API 문서 업데이트"
+```
+
+---
+
+## 📝 커밋 형식
+
+```
+<prefix>: <설명>
+```
+
+**한 줄로 간결하게** 작성합니다. 본문이나 푸터는 작성하지 않습니다.
+
+---
+
+## 🏷 Prefix 목록
+
+| Prefix | 용도 | 예시 |
+|--------|------|------|
+| `feat` | 새로운 기능 | `feat: 사용자 인증 기능 추가` |
+| `fix` | 버그 수정 | `fix: 토큰 검증 오류 수정` |
+| `refactor` | 리팩토링 | `refactor: 인증 로직 분리` |
+| `style` | 코드 스타일 | `style: prettier 적용` |
+| `docs` | 문서 수정 | `docs: API 문서 업데이트` |
+| `test` | 테스트 | `test: 인증 테스트 추가` |
+| `chore` | 빌드/설정 | `chore: 의존성 업데이트` |
+| `perf` | 성능 개선 | `perf: 쿼리 최적화` |
+| `ci` | CI/CD | `ci: GitHub Actions 추가` |
+
+---
+
+## ✅ 올바른 예시
+
+```bash
+feat: 사용자 로그인 기능 추가
+fix: 세션 만료 오류 수정
+refactor: 서비스 클래스 구조 개선
+docs: README 설치 가이드 추가
+chore: 의존성 버전 업그레이드
+```
+
+---
+
+## ❌ 잘못된 예시
+
+```bash
+# prefix 없음
+사용자 인증 기능 추가함
+
+# 마침표 불필요
+feat: 사용자 인증 추가.
+
+# 대문자 사용
+FEAT: 사용자 인증 추가
+
+# scope 불필요
+feat(auth): 인증 추가
+
+# AI 작성 표시 (절대 금지!)
+feat: 로그인 기능 추가
+
+🤖 Generated with Claude Code
+
+# Co-Author 표시 (절대 금지!)
+feat: 로그인 기능 추가
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+
+# 여러 줄 본문 (금지)
+feat: 로그인 기능 추가
+
+- 이메일 인증 추가
+- 세션 관리 구현
+
+# 여러 작업을 하나로 퉁침 (금지)
+feat: 로그인, 회원가입, 프로필 기능 추가
+```
+
+---
+
+## 🔄 작업 흐름
+
+```bash
+# 1. 작업 전 최신 코드 동기화
+git pull origin main
+
+# 2. 기능 A 작업 완료 → 커밋
+git add src/feature-a/
+git commit -m "feat: 기능 A 구현"
+
+# 3. 기능 B 작업 완료 → 커밋
+git add src/feature-b/
+git commit -m "feat: 기능 B 구현"
+
+# 4. 문서 작업 완료 → 커밋
+git add docs/
+git commit -m "docs: 기능 문서 추가"
+
+# 5. 푸시
+git push origin main
+```
+
+---
+
+## 📦 커밋 분리 가이드
+
+### 언제 커밋을 분리해야 하나요?
+
+| 상황 | 커밋 분리 |
+|------|----------|
+| 서로 다른 기능 구현 | ✅ 분리 |
+| 버그 수정 + 새 기능 | ✅ 분리 |
+| 코드 변경 + 문서 변경 | ✅ 분리 |
+| 리팩토링 + 기능 추가 | ✅ 분리 |
+| 동일 기능의 관련 파일들 | 🔄 묶어도 됨 |
+| 동일 기능의 타입 + 구현 | 🔄 묶어도 됨 |
+
+### 예시: 사용자 관리 기능 개발
+
+```bash
+# 1. 인증 기능 커밋
+git add src/auth/
+git commit -m "feat: 사용자 인증 기능 추가"
+
+# 2. 사용자 관리 커밋
+git add src/users/
+git commit -m "feat: 사용자 CRUD 기능 추가"
+
+# 3. 유효성 검사 커밋
+git add src/validators/
+git commit -m "feat: 입력값 유효성 검사 추가"
+
+# 4. 테스트 커밋
+git add tests/
+git commit -m "test: 사용자 관리 테스트 추가"
+
+# 5. 문서 커밋
+git add docs/
+git commit -m "docs: 사용자 API 문서 추가"
+```
+
+---
+
+## 🌿 브랜치 전략
+
+### 간단한 프로젝트
+```
+main ← 모든 작업 직접 커밋
+```
+
+### 팀 프로젝트
+```
+main
+  └── feature/기능명
+  └── fix/버그명
+  └── hotfix/긴급수정
+```
+
+### 브랜치 명명
+```bash
+feature/user-authentication
+feature/payment-integration
+fix/session-error
+hotfix/security-patch
+```
+
+---
+
+## 📋 자주 사용하는 명령어
+
+```bash
+# 상태 확인
+git status
+
+# 변경 내용 확인
+git diff
+
+# 최근 커밋 로그
+git log --oneline -10
+
+# 커밋 취소 (작업 내용 유지)
+git reset --soft HEAD~1
+
+# 스테이징 취소
+git restore --staged .
+
+# 변경사항 임시 저장
+git stash
+git stash pop
+
+# 특정 파일만 스테이징
+git add <파일경로>
+
+# 대화형 스테이징 (부분 커밋용)
+git add -p
+```
+
+---
+
+## 📚 .gitignore
+
+```gitignore
+# Dependencies
+node_modules/
+
+# Build
+dist/
+.output/
+build/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+
+# Cache
+.cache/
+.turbo/
+
+# Logs
+*.log
+```