@kood/claude-code 0.1.4 → 0.1.6

package/dist/index.js

@@ -460,7 +460,7 @@ var installAllCommands = async (templates, targetDir) => {
 
 // src/index.ts
 var program = new Command();
-program.name("claude-code").description("Claude Code documentation installer for projects").version("0.1.4");
+program.name("claude-code").description("Claude Code documentation installer for projects").version("0.1.5");
 program.option(
   "-t, --template <names>",
   "template names (comma-separated: tanstack-start,hono)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kood/claude-code",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Claude Code documentation installer for projects",
   "type": "module",
   "bin": "./dist/index.js",

package/templates/hono/docs/commands/git.md

@@ -1,4 +1,21 @@
-# Git 워크플로우
+현재 git 상태를 확인하고, 아래 규칙에 따라 작업을 진행해주세요.
+
+**추가 지시사항**: $ARGUMENTS
+
+---
+
+## 실행 절차
+
+### 추가 지시사항이 없는 경우 (기본 동작)
+1. `git status`로 현재 상태 확인
+2. `git diff`로 변경 내용 분석
+3. 스테이징 안 된 변경사항 → `git add`
+4. 커밋 안 된 변경사항 → 논리적 단위로 분리하여 `git commit`
+5. 최종 `git status`로 완료 확인
+
+### 추가 지시사항이 있는 경우
+- 사용자의 지시사항을 우선적으로 따름
+- 예: `/git push` → push 진행, `/git 특정파일만 커밋` → 해당 파일만 처리
 
 ---
 
@@ -19,12 +36,13 @@
 
 ## ✅ ALWAYS (필수)
 
-### 작업 완료 후 반드시 실행
+### 커밋 형식
 
-```bash
-git add <관련 파일들>
-git commit -m "<prefix>: <설명>"
 ```
+<prefix>: <설명>
+```
+
+**한 줄로 간결하게** 작성합니다. 본문이나 푸터는 작성하지 않습니다.
 
 ### ⭐ 커밋 분리 원칙
 
@@ -48,16 +66,6 @@ git commit -m "docs: API 문서 업데이트"
 
 ---
 
-## 📝 커밋 형식
-
-```
-<prefix>: <설명>
-```
-
-**한 줄로 간결하게** 작성합니다. 본문이나 푸터는 작성하지 않습니다.
-
----
-
 ## 🏷 Prefix 목록
 
 | Prefix | 용도 | 예시 |
@@ -123,30 +131,6 @@ 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
-```
-
----
-
 ## 📦 커밋 분리 가이드
 
 ### 언제 커밋을 분리해야 하나요?
@@ -159,117 +143,3 @@ 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
-```

package/templates/npx/docs/commands/git.md

@@ -1,4 +1,21 @@
-# Git 워크플로우
+현재 git 상태를 확인하고, 아래 규칙에 따라 작업을 진행해주세요.
+
+**추가 지시사항**: $ARGUMENTS
+
+---
+
+## 실행 절차
+
+### 추가 지시사항이 없는 경우 (기본 동작)
+1. `git status`로 현재 상태 확인
+2. `git diff`로 변경 내용 분석
+3. 스테이징 안 된 변경사항 → `git add`
+4. 커밋 안 된 변경사항 → 논리적 단위로 분리하여 `git commit`
+5. 최종 `git status`로 완료 확인
+
+### 추가 지시사항이 있는 경우
+- 사용자의 지시사항을 우선적으로 따름
+- 예: `/git push` → push 진행, `/git 특정파일만 커밋` → 해당 파일만 처리
 
 ---
 
@@ -19,12 +36,13 @@
 
 ## ✅ ALWAYS (필수)
 
-### 작업 완료 후 반드시 실행
+### 커밋 형식
 
-```bash
-git add <관련 파일들>
-git commit -m "<prefix>: <설명>"
 ```
+<prefix>: <설명>
+```
+
+**한 줄로 간결하게** 작성합니다. 본문이나 푸터는 작성하지 않습니다.
 
 ### ⭐ 커밋 분리 원칙
 
@@ -48,16 +66,6 @@ git commit -m "docs: API 문서 업데이트"
 
 ---
 
-## 📝 커밋 형식
-
-```
-<prefix>: <설명>
-```
-
-**한 줄로 간결하게** 작성합니다. 본문이나 푸터는 작성하지 않습니다.
-
----
-
 ## 🏷 Prefix 목록
 
 | Prefix | 용도 | 예시 |
@@ -123,30 +131,6 @@ 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
-```
-
----
-
 ## 📦 커밋 분리 가이드
 
 ### 언제 커밋을 분리해야 하나요?
@@ -159,117 +143,3 @@ 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
-```

package/templates/tanstack-start/CLAUDE.md

@@ -277,21 +277,19 @@ export const Route = createFileRoute('/users')({
 ### TanStack Query (서버 연동 시 필수)
 ```tsx
 // ✅ 데이터 조회: useQuery 필수
-const getPosts = useServerFn(getServerPosts)
 const { data } = useQuery({
-  queryKey: ['users'],
-  queryFn: () => getPosts(),
+  queryKey: ['posts'],
+  queryFn: () => getServerPosts(),
 })
 
 // ✅ 데이터 변경: useMutation 필수
-const createPostFn = useServerFn(createPost)
 const mutation = useMutation({
-  mutationFn: createPostFn,
-  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
+  mutationFn: createPost,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['posts'] }),
 })
 
-// ❌ 금지: Server Function 직접 호출
-// useEffect(() => { getPosts().then(setData) }, [])
+// ❌ 금지: Server Function을 TanStack Query 없이 직접 호출
+// useEffect(() => { getServerPosts().then(setData) }, [])
 ```
 
 ---

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

@@ -1,4 +1,21 @@
-# Git 워크플로우
+현재 git 상태를 확인하고, 아래 규칙에 따라 작업을 진행해주세요.
+
+**추가 지시사항**: $ARGUMENTS
+
+---
+
+## 실행 절차
+
+### 추가 지시사항이 없는 경우 (기본 동작)
+1. `git status`로 현재 상태 확인
+2. `git diff`로 변경 내용 분석
+3. 스테이징 안 된 변경사항 → `git add`
+4. 커밋 안 된 변경사항 → 논리적 단위로 분리하여 `git commit`
+5. 최종 `git status`로 완료 확인
+
+### 추가 지시사항이 있는 경우
+- 사용자의 지시사항을 우선적으로 따름
+- 예: `/git push` → push 진행, `/git 특정파일만 커밋` → 해당 파일만 처리
 
 ---
 
@@ -19,12 +36,13 @@
 
 ## ✅ ALWAYS (필수)
 
-### 작업 완료 후 반드시 실행
+### 커밋 형식
 
-```bash
-git add <관련 파일들>
-git commit -m "<prefix>: <설명>"
 ```
+<prefix>: <설명>
+```
+
+**한 줄로 간결하게** 작성합니다. 본문이나 푸터는 작성하지 않습니다.
 
 ### ⭐ 커밋 분리 원칙
 
@@ -48,16 +66,6 @@ git commit -m "docs: API 문서 업데이트"
 
 ---
 
-## 📝 커밋 형식
-
-```
-<prefix>: <설명>
-```
-
-**한 줄로 간결하게** 작성합니다. 본문이나 푸터는 작성하지 않습니다.
-
----
-
 ## 🏷 Prefix 목록
 
 | Prefix | 용도 | 예시 |
@@ -123,30 +131,6 @@ 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
-```
-
----
-
 ## 📦 커밋 분리 가이드
 
 ### 언제 커밋을 분리해야 하나요?
@@ -159,117 +143,3 @@ 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
-```

package/templates/tanstack-start/docs/guides/best-practices.md

@@ -304,7 +304,6 @@ const UsersPage = (): JSX.Element => {
 import { useState, useMemo, useEffect, useCallback } from 'react'
 import { useParams, useNavigate } from '@tanstack/react-router'
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
-import { useServerFn } from '@tanstack/react-start'
 import { useAuthStore } from '@/stores/auth'
 import { getUsers, createUser, deleteUser } from '@/services/user'
 import type { User } from '@/types'
@@ -339,24 +338,20 @@ export const useUsers = (): UseUsersReturn => {
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   // 3. React Query (useQuery → useMutation)
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  const getUsersFn = useServerFn(getUsers)
-  const createUserFn = useServerFn(createUser)
-  const deleteUserFn = useServerFn(deleteUser)
-
   const { data: users, isLoading, error } = useQuery({
     queryKey: ['users'],
-    queryFn: () => getUsersFn(),
+    queryFn: () => getUsers(),
   })
 
   const createMutation = useMutation({
-    mutationFn: createUserFn,
+    mutationFn: createUser,
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['users'] })
     },
   })
 
   const deleteMutation = useMutation({
-    mutationFn: deleteUserFn,
+    mutationFn: deleteUser,
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: ['users'] })
     },

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

@@ -226,7 +226,7 @@ export const clientEnv = parseClientEnv()
 ```typescript
 // app/server-functions/users.ts
 import { createServerFn } from '@tanstack/react-start'
-import { getServerEnv } from '~/config/env'
+import { getServerEnv } from '@/config/env'
 
 export const getUsers = createServerFn({ method: 'GET' })
   .handler(async () => {
@@ -248,7 +248,7 @@ export const getUsers = createServerFn({ method: 'GET' })
 
 ```tsx
 // app/components/AppHeader.tsx
-import { clientEnv } from '~/config/env'
+import { clientEnv } from '@/config/env'
 
 export const AppHeader = () => {
   return (
@@ -282,7 +282,7 @@ const appName = import.meta.env.VITE_APP_NAME  // ✅ VITE_ 접두사만
 
 ```typescript
 // app/lib/auth.ts
-import { getServerEnv } from '~/config/env'
+import { getServerEnv } from '@/config/env'
 
 export const getAuthConfig = () => {
   const env = getServerEnv()

package/templates/tanstack-start/docs/library/better-auth/2fa.md

@@ -103,7 +103,7 @@ await authClient.twoFactor.disable({
 ```tsx
 // pages/two-factor.tsx
 import { useState } from 'react'
-import { authClient } from '~/lib/auth-client'
+import { authClient } from '@/lib/auth-client'
 
 export default function TwoFactorPage() {
   const [code, setCode] = useState('')

package/templates/tanstack-start/docs/library/better-auth/setup.md

@@ -111,7 +111,7 @@ export const auth = betterAuth({
 
 // Server Function에서 사용
 import { createServerFn } from '@tanstack/react-start'
-import { auth } from '~/lib/auth'
+import { auth } from '@/lib/auth'
 
 export const getSession = createServerFn({ method: 'GET' })
   .handler(async ({ request }) => {

package/templates/tanstack-start/docs/library/prisma/setup.md

@@ -113,7 +113,7 @@ if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma
 
 // Server Function에서 사용
 import { createServerFn } from '@tanstack/react-start'
-import { prisma } from '~/lib/prisma'
+import { prisma } from '@/lib/prisma'
 
 export const getUsers = createServerFn({ method: 'GET' })
   .handler(async () => {

package/templates/tanstack-start/docs/library/tanstack-query/setup.md

@@ -52,15 +52,12 @@ const queryClient = new QueryClient({
 
 ```tsx
 import { useQuery } from '@tanstack/react-query'
-import { useServerFn } from '@tanstack/react-start'
-import { getServerPosts } from '~/lib/server-functions'
+import { getServerPosts } from '@/lib/server-functions'
 
 function PostList() {
-  const getPosts = useServerFn(getServerPosts)
-
   const { data, isLoading, error } = useQuery({
     queryKey: ['posts'],
-    queryFn: () => getPosts(),
+    queryFn: () => getServerPosts(),
   })
 
   if (isLoading) return <div>Loading...</div>

package/templates/tanstack-start/docs/library/tanstack-start/auth-patterns.md

@@ -159,7 +159,7 @@ export const auth = betterAuth({
 
 // Server Function에서 사용
 import { createServerFn } from '@tanstack/react-start'
-import { auth } from '~/lib/auth'
+import { auth } from '@/lib/auth'
 
 export const getSession = createServerFn({ method: 'GET' })
   .handler(async ({ request }) => {

package/templates/tanstack-start/docs/library/tanstack-start/server-functions.md

@@ -93,16 +93,13 @@ export const submitForm = createServerFn({ method: 'POST' })
 ### ✅ 올바른 패턴: useQuery 사용 (데이터 조회)
 
 ```tsx
-import { useServerFn } from '@tanstack/react-start'
 import { useQuery } from '@tanstack/react-query'
-import { getServerPosts } from '~/lib/server-functions'
+import { getServerPosts } from '@/lib/server-functions'
 
 function PostList() {
-  const getPosts = useServerFn(getServerPosts)
-
   const { data, isLoading, error } = useQuery({
     queryKey: ['posts'],
-    queryFn: () => getPosts(),
+    queryFn: () => getServerPosts(),
   })
 
   if (isLoading) return <div>Loading...</div>
@@ -121,16 +118,14 @@ function PostList() {
 ### ✅ 올바른 패턴: useMutation 사용 (데이터 변경)
 
 ```tsx
-import { useServerFn } from '@tanstack/react-start'
 import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { createPost, deletePost } from '~/lib/server-functions'
+import { createPost, deletePost } from '@/lib/server-functions'
 
 function PostForm() {
   const queryClient = useQueryClient()
-  const createPostFn = useServerFn(createPost)
 
   const mutation = useMutation({
-    mutationFn: (data: { title: string; content: string }) => createPostFn({ data }),
+    mutationFn: (data: { title: string; content: string }) => createPost({ data }),
     onSuccess: () => {
       // 관련 쿼리 무효화로 데이터 동기화
       queryClient.invalidateQueries({ queryKey: ['posts'] })
@@ -181,6 +176,92 @@ function BadExample() {
 }
 ```
 
+## ⚠️ 함수 분리 시 유의사항
+
+Server Function 내부 로직을 별도 함수로 분리할 때 반드시 아래 규칙을 따르세요.
+
+### 규칙
+
+```
+1. 분리한 함수는 createServerFn 내부에서만 호출
+2. 분리한 함수는 createServerFn으로 감싸지 않음
+3. 분리한 함수는 index.ts에서 export 금지 (프론트엔드 import 방지)
+```
+
+### ✅ 올바른 패턴
+
+```typescript
+// services/user/mutations.ts
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 내부 헬퍼 함수 (export 금지!)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+const validateUserData = async (email: string) => {
+  const existing = await prisma.user.findUnique({ where: { email } })
+  if (existing) throw new Error('Email already exists')
+  return true
+}
+
+const sendWelcomeEmail = async (userId: string, email: string) => {
+  await emailService.send({
+    to: email,
+    template: 'welcome',
+    data: { userId },
+  })
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Server Function (export 가능)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+export const createUser = createServerFn({ method: 'POST' })
+  .inputValidator(createUserSchema)
+  .handler(async ({ data }) => {
+    // 내부 헬퍼 함수 호출
+    await validateUserData(data.email)
+
+    const user = await prisma.user.create({ data })
+
+    // 내부 헬퍼 함수 호출
+    await sendWelcomeEmail(user.id, user.email)
+
+    return user
+  })
+```
+
+```typescript
+// services/user/index.ts
+
+// ✅ Server Function만 export
+export { createUser, updateUser, deleteUser } from './mutations'
+export { getUsers, getUserById } from './queries'
+
+// ❌ 내부 헬퍼 함수는 export 금지!
+// export { validateUserData, sendWelcomeEmail } from './mutations'
+```
+
+### ❌ 잘못된 패턴
+
+```typescript
+// ❌ 분리한 함수를 createServerFn으로 감싸지 마세요
+export const validateUserData = createServerFn({ method: 'POST' })
+  .handler(async ({ data }) => {
+    // ...
+  })
+
+// ❌ 내부 헬퍼 함수를 export 하지 마세요
+export const sendWelcomeEmail = async (userId: string) => {
+  // 프론트엔드에서 import 가능해져 보안 위험!
+}
+```
+
+### 이유
+
+- **보안**: 내부 로직이 프론트엔드 번들에 포함되지 않음
+- **명확한 API**: Server Function만 외부에 노출되어 API 경계가 명확함
+- **트리 쉐이킹**: export하지 않은 함수는 번들에서 제거됨
+
+---
+
 ## 보안 패턴
 
 ### 서버 전용 데이터 보호

package/templates/tanstack-start/docs/library/tanstack-start/setup.md

@@ -45,7 +45,7 @@ export default defineConfig({
     "jsx": "react-jsx",
     "baseUrl": ".",
     "paths": {
-      "~/*": ["./src/*"]
+      "@/*": ["./src/*"]
     }
   },
   "include": ["src/**/*"]