@choblue/claude-code-toolkit 1.0.0

package/.claude/skills/Zustand/SKILL.md

@@ -0,0 +1,285 @@
+# Zustand Skill - 클라이언트 상태 관리 규칙
+
+Zustand를 사용한 클라이언트 상태 관리 규칙을 정의한다.
+서버 상태 관리는 `../TanStackQuery/SKILL.md`를 참고한다.
+
+---
+
+## 1. 기본 패턴
+
+### Store 생성
+
+```typescript
+import { create } from 'zustand';
+
+interface CounterStore {
+  count: number;
+  increment: () => void;
+  decrement: () => void;
+  reset: () => void;
+}
+
+export const useCounterStore = create<CounterStore>((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+  decrement: () => set((state) => ({ count: state.count - 1 })),
+  reset: () => set({ count: 0 }),
+}));
+```
+
+### Selector로 구독
+
+```typescript
+// Good - 필요한 값만 구독 (리렌더링 최소화)
+const count = useCounterStore((state) => state.count);
+const increment = useCounterStore((state) => state.increment);
+
+// Bad - 전체 store 구독 (불필요한 리렌더링 발생)
+const store = useCounterStore();
+```
+
+---
+
+## 2. Store 설계 원칙
+
+### 도메인별 분리
+- 하나의 store는 하나의 관심사만 담당한다
+- 관련 없는 상태를 하나의 store에 넣지 않는다
+
+```typescript
+// Good - 도메인별 분리
+const useAuthStore = create<AuthStore>(() => ({ /* 인증 관련 */ }));
+const useUIStore = create<UIStore>(() => ({ /* UI 상태 관련 */ }));
+const useCartStore = create<CartStore>(() => ({ /* 장바구니 관련 */ }));
+
+// Bad - 모든 것을 하나의 store에
+const useAppStore = create<AppStore>(() => ({
+  user: null,
+  isModalOpen: false,
+  cartItems: [],
+  theme: 'light',
+  // ... 모든 상태가 뒤섞임
+}));
+```
+
+### 서버 상태와 클라이언트 상태 분리
+
+| 상태 유형 | 관리 도구 | 예시 |
+|-----------|-----------|------|
+| 서버 상태 | TanStack Query | 사용자 목록, 게시글, API 응답 |
+| 클라이언트 상태 | Zustand | 모달 열림/닫힘, 테마, 사이드바 상태 |
+
+---
+
+## 3. Selector 패턴
+
+### 개별 Selector
+
+```typescript
+// Good - 각 값을 개별 selector로 구독
+function UserInfo() {
+  const userName = useAuthStore((state) => state.userName);
+  const avatarUrl = useAuthStore((state) => state.avatarUrl);
+  return <div>{userName}</div>;
+}
+```
+
+### Shallow 비교
+
+여러 값을 한 번에 가져올 때 `useShallow`로 불필요한 리렌더링을 방지한다.
+
+```typescript
+import { useShallow } from 'zustand/react/shallow';
+
+// Good - 객체 반환 시 useShallow 사용
+const { userName, avatarUrl } = useAuthStore(
+  useShallow((state) => ({
+    userName: state.userName,
+    avatarUrl: state.avatarUrl,
+  }))
+);
+```
+
+---
+
+## 4. Actions 패턴
+
+### set과 get 사용
+
+```typescript
+interface TodoStore {
+  todos: Todo[];
+  addTodo: (text: string) => void;
+  removeTodo: (id: string) => void;
+  toggleTodo: (id: string) => void;
+}
+
+export const useTodoStore = create<TodoStore>((set, get) => ({
+  todos: [],
+
+  addTodo: (text) =>
+    set((state) => ({
+      todos: [...state.todos, { id: crypto.randomUUID(), text, done: false }],
+    })),
+
+  removeTodo: (id) =>
+    set((state) => ({
+      todos: state.todos.filter((todo) => todo.id !== id),
+    })),
+
+  // get()으로 현재 상태를 읽어야 할 때
+  toggleTodo: (id) => {
+    const todo = get().todos.find((t) => t.id === id);
+    if (!todo) return;
+    set((state) => ({
+      todos: state.todos.map((t) =>
+        t.id === id ? { ...t, done: !t.done } : t
+      ),
+    }));
+  },
+}));
+```
+
+### Action은 Store 안에 정의한다
+
+```typescript
+// Good - action이 store 안에 있음
+export const useCartStore = create<CartStore>((set) => ({
+  items: [],
+  addItem: (item) => set((state) => ({ items: [...state.items, item] })),
+}));
+
+// Bad - action이 store 밖에 있음
+export const useCartStore = create<CartStore>(() => ({
+  items: [],
+}));
+
+export function addItem(item: CartItem) {
+  useCartStore.setState((state) => ({ items: [...state.items, item] }));
+}
+```
+
+---
+
+## 5. Middleware
+
+### persist - localStorage 저장
+
+```typescript
+import { persist } from 'zustand/middleware';
+
+export const useSettingsStore = create<SettingsStore>()(
+  persist(
+    (set) => ({
+      theme: 'light' as const,
+      language: 'ko' as const,
+      setTheme: (theme) => set({ theme }),
+      setLanguage: (language) => set({ language }),
+    }),
+    {
+      name: 'settings-storage', // localStorage key
+      partialize: (state) => ({
+        theme: state.theme,
+        language: state.language,
+      }), // 저장할 상태만 선택
+    }
+  )
+);
+```
+
+### devtools - 개발 도구 연동
+
+```typescript
+import { devtools } from 'zustand/middleware';
+
+export const useAuthStore = create<AuthStore>()(
+  devtools(
+    (set) => ({
+      user: null,
+      login: (user) => set({ user }, false, 'auth/login'),
+      logout: () => set({ user: null }, false, 'auth/logout'),
+    }),
+    { name: 'AuthStore' }
+  )
+);
+```
+
+### immer - 불변 업데이트 간소화
+
+```typescript
+import { immer } from 'zustand/middleware/immer';
+
+export const useTodoStore = create<TodoStore>()(
+  immer((set) => ({
+    todos: [],
+    toggleTodo: (id) =>
+      set((state) => {
+        const todo = state.todos.find((t) => t.id === id);
+        if (todo) todo.done = !todo.done; // 직접 변경 가능
+      }),
+  }))
+);
+```
+
+---
+
+## 6. Slice 패턴
+
+큰 store를 slice로 분리하여 합치는 패턴이다.
+
+```typescript
+// authSlice.ts
+interface AuthSlice {
+  user: User | null;
+  login: (user: User) => void;
+  logout: () => void;
+}
+
+const createAuthSlice: StateCreator<StoreState, [], [], AuthSlice> = (set) => ({
+  user: null,
+  login: (user) => set({ user }),
+  logout: () => set({ user: null }),
+});
+
+// uiSlice.ts
+interface UISlice {
+  isSidebarOpen: boolean;
+  toggleSidebar: () => void;
+}
+
+const createUISlice: StateCreator<StoreState, [], [], UISlice> = (set) => ({
+  isSidebarOpen: true,
+  toggleSidebar: () => set((state) => ({ isSidebarOpen: !state.isSidebarOpen })),
+});
+
+// store.ts - Slice 합치기
+type StoreState = AuthSlice & UISlice;
+
+export const useAppStore = create<StoreState>()((...args) => ({
+  ...createAuthSlice(...args),
+  ...createUISlice(...args),
+}));
+```
+
+---
+
+## 7. 네이밍 컨벤션
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| Store 훅 | `use` + 도메인 + `Store` | `useAuthStore`, `useCartStore` |
+| Store 파일 | 도메인 + `Store.ts` | `authStore.ts`, `cartStore.ts` |
+| Slice 파일 | 도메인 + `Slice.ts` | `authSlice.ts`, `uiSlice.ts` |
+| Action | 동사 + 명사 (camelCase) | `addItem`, `setTheme`, `toggleSidebar` |
+| Store 디렉토리 | `stores/` | `src/stores/authStore.ts` |
+
+---
+
+## 8. 금지 사항
+
+- Store에 서버 데이터 캐싱 금지 - 서버 상태는 TanStack Query를 사용한다
+- 거대한 단일 store 금지 - 도메인별로 분리한다
+- Selector 없이 전체 store 구독 금지 - 필요한 값만 개별 selector로 가져온다
+- Store 밖에서 action 정의 금지 - action은 store 안에 정의한다
+- `any` 타입 사용 금지 - store에 명시적 타입을 정의한다
+- 컴포넌트 안에서 `useStore.setState()` 직접 호출 금지 - store에 정의된 action을 사용한다

package/README.md

@@ -0,0 +1,157 @@
+# my-claude-code-toolkit
+
+매번 새 프로젝트마다 Claude Code 세팅을 처음부터 만드는 비효율을 해결한다.
+`~/.claude/` 글로벌 설정으로 모든 프로젝트에 자동 적용되며, 이 GitHub 레포로 버전 관리한다.
+
+## 기술 스택
+
+- Frontend: React (TypeScript)
+- Backend: NestJS (TypeScript)
+- 방식: 서브에이전트 위임 (Context 절약)
+
+## 구조
+
+```
+.claude/
+├── CLAUDE.md                    ← 핵심 워크플로우/위임 규칙
+├── settings.json                ← hooks 설정
+├── agents/
+│   ├── explore.md               ← 코드베이스 탐색 (haiku)
+│   ├── code-writer/
+│   │   ├── common.md            ← 공통 구현 규칙
+│   │   ├── backend.md           ← NestJS 백엔드 규칙
+│   │   └── frontend.md          ← React 프론트엔드 규칙
+│   ├── code-reviewer.md         ← 코드 품질 리뷰 (opus)
+│   ├── tdd/
+│   │   ├── common.md            ← TDD 공통 규칙
+│   │   ├── backend.md           ← NestJS 테스트 규칙
+│   │   └── frontend.md          ← React 테스트 규칙
+│   └── git-manager.md           ← Git 작업 (sonnet)
+├── skills/
+│   ├── Coding/
+│   │   ├── SKILL.md             ← 공통 코딩 원칙
+│   │   └── backend.md           ← NestJS 코딩 규칙
+│   ├── React/
+│   │   └── SKILL.md             ← React 컴포넌트, 훅, 상태 관리
+│   ├── NextJS/
+│   │   └── SKILL.md             ← Next.js App Router, SSR
+│   ├── TailwindCSS/
+│   │   └── SKILL.md             ← Tailwind CSS 유틸리티 패턴
+│   ├── TanStackQuery/
+│   │   └── SKILL.md             ← TanStack Query 서버 상태
+│   ├── Zustand/
+│   │   └── SKILL.md             ← Zustand 클라이언트 상태
+│   ├── ReactHookForm/
+│   │   └── SKILL.md             ← React Hook Form + Zod
+│   ├── TypeScript/
+│   │   └── SKILL.md             ← TypeScript 고급 패턴
+│   ├── TypeORM/
+│   │   └── SKILL.md             ← TypeORM Entity, Repository
+│   ├── TDD/
+│   │   ├── SKILL.md             ← TDD 핵심 원칙
+│   │   ├── frontend.md          ← React 테스트 규칙
+│   │   └── backend.md           ← NestJS 테스트 규칙
+│   └── Git/
+│       └── SKILL.md             ← 커밋/PR/브랜치 규칙
+└── hooks/
+    └── quality-gate.sh          ← 품질 체크 프로토콜
+```
+
+## 설치
+
+### npx로 설치 (권장)
+
+clone 없이 바로 설치할 수 있다.
+
+```bash
+# 전체 설치 (프로젝트 로컬)
+npx @choblue/claude-code-toolkit
+
+# FE만 설치 (공통 + React, Next.js, TailwindCSS 등)
+npx @choblue/claude-code-toolkit --fe
+
+# BE만 설치 (공통 + NestJS, TypeORM 등)
+npx @choblue/claude-code-toolkit --be
+
+# 글로벌 설치
+npx @choblue/claude-code-toolkit --global
+
+# 글로벌 + FE만
+npx @choblue/claude-code-toolkit --global --fe
+```
+
+### 소스에서 설치
+
+```bash
+# 레포 클론
+git clone https://github.com/choblue/my-claude-code-toolkit.git
+cd my-claude-code-toolkit
+
+# 전체 설치 (프로젝트 로컬)
+./install.sh
+
+# FE만 설치
+./install.sh --fe
+
+# BE만 설치
+./install.sh --be
+
+# 글로벌 설치
+./install.sh --global
+
+# 글로벌 + FE만
+./install.sh --global --fe
+```
+
+| 옵션 | 설명 |
+|------|------|
+| (없음) | 전체 설치 (FE + BE), 프로젝트 로컬 |
+| `--fe` | 공통 + FE 스킬만 설치 |
+| `--be` | 공통 + BE 스킬만 설치 |
+| `--fe --be` | 전체 설치 (기본값과 동일) |
+| `--global` | `~/.claude/`에 글로벌 설치 |
+
+기존 `.claude/` 파일이 있으면 자동으로 백업 후 덮어쓴다.
+
+## 작동 방식
+
+### 워크플로우 (Planning → Test → Implementation → Review)
+
+1. **Planning**: 사용자 요구사항 분석 → `explore` 에이전트로 코드 탐색 → 작업 계획 제시
+2. **Test (Red)**: `tdd` 에이전트로 실패하는 테스트 작성 → Red 상태 확인
+3. **Implementation (Green + Refactor)**: `code-writer` 에이전트에 구현 위임 → 테스트 통과 확인
+4. **Review**: `code-reviewer`로 코드 + 테스트 리뷰 → `git-manager`로 커밋/PR 생성
+
+### 서브에이전트 위임
+
+Main Agent는 직접 코드를 작성하거나 탐색하지 않고, 전문 서브에이전트에 위임한다.
+이를 통해 Context Window를 절약하고 각 작업에 최적화된 프롬프트를 사용한다.
+
+| 에이전트 | 모델 | 역할 |
+|---------|------|------|
+| explore | haiku | 빠른 코드베이스 탐색 |
+| code-writer | opus | FE/BE 코드 구현 |
+| code-reviewer | opus | 코드 품질 리뷰 |
+| tdd | opus | TDD 테스트 작성/실행 |
+| git-manager | sonnet | 커밋, 브랜치, PR |
+
+### Quality Gate Hook
+
+매 프롬프트마다 `quality-gate.sh`가 실행되어 적절한 에이전트/스킬 활용을 상기시킨다.
+
+## 프로젝트별 커스터마이징
+
+프로젝트 루트에 `CLAUDE.md`를 추가하면 글로벌 규칙보다 우선 적용된다.
+프로젝트별 규칙은 글로벌 규칙을 확장하되, 충돌 시 프로젝트 규칙을 따른다.
+
+## 업데이트
+
+```bash
+# npx는 항상 최신 버전을 실행한다
+npx @choblue/claude-code-toolkit
+
+# 소스에서 설치한 경우
+cd my-claude-code-toolkit
+git pull
+./install.sh
+```

package/bin/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+const { execSync } = require("child_process");
+const path = require("path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const installScript = path.join(packageRoot, "install.sh");
+
+const args = process.argv.slice(2).join(" ");
+
+try {
+  execSync(`bash "${installScript}" ${args}`, {
+    stdio: "inherit",
+    env: { ...process.env, PACKAGE_ROOT: packageRoot },
+  });
+} catch (err) {
+  process.exit(err.status || 1);
+}

package/install.sh

@@ -0,0 +1,255 @@
+#!/bin/bash
+# install.sh - my-claude-code-toolkit을 .claude/에 설치한다
+# Usage: ./install.sh [--global] [--fe] [--be]
+#   기본값: 현재 디렉토리의 .claude/에 전체 설치 (프로젝트 로컬)
+#   --global: ~/.claude/에 설치 (글로벌)
+#   --fe: 공통 + 프론트엔드 스킬만 설치
+#   --be: 공통 + 백엔드 스킬만 설치
+#   --fe --be: 전체 설치 (= 기본값)
+
+set -e
+
+# 도움말 출력
+usage() {
+  echo "Usage: $0 [--global] [--fe] [--be]"
+  echo ""
+  echo "스택 선택:"
+  echo "  (기본값)       전체 설치 (공통 + FE + BE)"
+  echo "  --fe           공통 + 프론트엔드만 설치"
+  echo "  --be           공통 + 백엔드만 설치"
+  echo "  --fe --be      전체 설치 (= 기본값)"
+  echo ""
+  echo "설치 위치:"
+  echo "  (기본값)       현재 디렉토리의 .claude/에 설치 (프로젝트 로컬)"
+  echo "  --global       ~/.claude/에 설치 (글로벌)"
+  echo ""
+  echo "예시:"
+  echo "  $0                    # 전체 설치 (로컬)"
+  echo "  $0 --fe               # 공통 + FE만 (로컬)"
+  echo "  $0 --be               # 공통 + BE만 (로컬)"
+  echo "  $0 --global --fe      # 공통 + FE만 (글로벌)"
+  exit 0
+}
+
+# 인자 파싱
+INSTALL_MODE="local"
+INSTALL_FE=false
+INSTALL_BE=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --global)
+      INSTALL_MODE="global"
+      ;;
+    --fe)
+      INSTALL_FE=true
+      ;;
+    --be)
+      INSTALL_BE=true
+      ;;
+    --help|-h)
+      usage
+      ;;
+    *)
+      echo "Error: 알 수 없는 옵션 '$arg'"
+      usage
+      ;;
+  esac
+done
+
+# --fe도 --be도 지정하지 않으면 둘 다 true (전체 설치)
+if [ "$INSTALL_FE" = false ] && [ "$INSTALL_BE" = false ]; then
+  INSTALL_FE=true
+  INSTALL_BE=true
+fi
+
+# 스택 라벨 결정
+if [ "$INSTALL_FE" = true ] && [ "$INSTALL_BE" = true ]; then
+  STACK_LABEL="FE + BE (전체)"
+elif [ "$INSTALL_FE" = true ]; then
+  STACK_LABEL="FE만"
+else
+  STACK_LABEL="BE만"
+fi
+
+if [ -n "$PACKAGE_ROOT" ]; then
+  SOURCE_DIR="$PACKAGE_ROOT/.claude"
+else
+  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+  SOURCE_DIR="$SCRIPT_DIR/.claude"
+fi
+
+if [ "$INSTALL_MODE" = "global" ]; then
+  TARGET_DIR="$HOME/.claude"
+  BACKUP_DIR="$HOME/.claude-backup-$(date +%Y%m%d_%H%M%S)"
+  MODE_LABEL="글로벌 설치 (~/.claude/)"
+else
+  TARGET_DIR="$(pwd)/.claude"
+  BACKUP_DIR="$(pwd)/.claude-backup-$(date +%Y%m%d_%H%M%S)"
+  MODE_LABEL="로컬 설치 ($(pwd)/.claude/)"
+fi
+
+echo "=== my-claude-code-toolkit 설치 ==="
+echo ""
+echo "모드:   $MODE_LABEL"
+echo "스택:   $STACK_LABEL"
+echo "Source: $SOURCE_DIR"
+echo "Target: $TARGET_DIR"
+echo ""
+
+# Source 디렉토리 존재 확인
+if [ ! -d "$SOURCE_DIR" ]; then
+  echo "Error: $SOURCE_DIR 디렉토리를 찾을 수 없습니다."
+  exit 1
+fi
+
+# 기존 파일 백업
+if [ -d "$TARGET_DIR" ]; then
+  # 백업할 파일이 있는지 확인 (agents, skills, hooks, CLAUDE.md, settings.json)
+  HAS_EXISTING=false
+  for item in CLAUDE.md settings.json agents skills hooks; do
+    if [ -e "$TARGET_DIR/$item" ]; then
+      HAS_EXISTING=true
+      break
+    fi
+  done
+
+  if [ "$HAS_EXISTING" = true ]; then
+    echo "기존 설정 파일이 발견되었습니다. 백업합니다..."
+    mkdir -p "$BACKUP_DIR"
+    for item in CLAUDE.md settings.json agents skills hooks; do
+      if [ -e "$TARGET_DIR/$item" ]; then
+        cp -r "$TARGET_DIR/$item" "$BACKUP_DIR/"
+        echo "  백업: $item → $BACKUP_DIR/$item"
+      fi
+    done
+    echo ""
+    echo "백업 완료: $BACKUP_DIR"
+    echo ""
+  fi
+else
+  mkdir -p "$TARGET_DIR"
+fi
+
+# === 헬퍼 함수 ===
+
+# 개별 파일 복사 (상대경로 기준)
+copy_file() {
+  local rel_path="$1"
+  local dir
+  dir="$(dirname "$rel_path")"
+  mkdir -p "$TARGET_DIR/$dir"
+  cp "$SOURCE_DIR/$rel_path" "$TARGET_DIR/$rel_path"
+  echo "  복사: $rel_path"
+}
+
+# 디렉토리 전체 복사 (상대경로 기준)
+copy_dir() {
+  local rel_path="$1"
+  mkdir -p "$TARGET_DIR/$rel_path"
+  cp -r "$SOURCE_DIR/$rel_path/"* "$TARGET_DIR/$rel_path/"
+  echo "  복사: $rel_path/"
+}
+
+# === 복사 함수 ===
+
+# 공통 (항상 설치)
+copy_common() {
+  echo "[공통]"
+
+  # 루트 설정 파일
+  copy_file "CLAUDE.md"
+  copy_file "settings.json"
+
+  # 공통 에이전트
+  copy_file "agents/explore.md"
+  copy_file "agents/code-reviewer.md"
+  copy_file "agents/git-manager.md"
+  copy_file "agents/code-writer/common.md"
+  copy_file "agents/tdd/common.md"
+
+  # 공통 스킬
+  copy_file "skills/Coding/SKILL.md"
+  copy_dir "skills/TypeScript"
+  copy_dir "skills/Git"
+  copy_file "skills/TDD/SKILL.md"
+
+  # hooks
+  copy_dir "hooks"
+  chmod +x "$TARGET_DIR/hooks/"*.sh
+}
+
+# FE (프론트엔드)
+copy_fe() {
+  echo "[FE]"
+
+  # FE 에이전트
+  copy_file "agents/code-writer/frontend.md"
+  copy_file "agents/tdd/frontend.md"
+
+  # FE 스킬 (디렉토리 전체)
+  copy_dir "skills/React"
+  copy_dir "skills/NextJS"
+  copy_dir "skills/TailwindCSS"
+  copy_dir "skills/TanStackQuery"
+  copy_dir "skills/Zustand"
+  copy_dir "skills/ReactHookForm"
+
+  # FE 개별 스킬 파일
+  copy_file "skills/TDD/frontend.md"
+  copy_file "skills/Coding/frontend.md"
+}
+
+# BE (백엔드)
+copy_be() {
+  echo "[BE]"
+
+  # BE 에이전트
+  copy_file "agents/code-writer/backend.md"
+  copy_file "agents/tdd/backend.md"
+
+  # BE 스킬 (디렉토리 전체)
+  copy_dir "skills/TypeORM"
+
+  # BE 개별 스킬 파일
+  copy_file "skills/Coding/backend.md"
+  copy_file "skills/TDD/backend.md"
+}
+
+# === 실행 ===
+
+echo "파일을 복사합니다..."
+echo ""
+
+# 공통은 항상 설치
+copy_common
+echo ""
+
+# 선택된 스택 설치
+if [ "$INSTALL_FE" = true ]; then
+  copy_fe
+  echo ""
+fi
+
+if [ "$INSTALL_BE" = true ]; then
+  copy_be
+  echo ""
+fi
+
+echo "=== 설치 완료 ($MODE_LABEL) ==="
+echo ""
+echo "스택: $STACK_LABEL"
+echo ""
+echo "설치된 파일:"
+echo "  $TARGET_DIR/CLAUDE.md"
+echo "  $TARGET_DIR/settings.json"
+echo "  $TARGET_DIR/agents/"
+echo "  $TARGET_DIR/skills/"
+echo "  $TARGET_DIR/hooks/"
+echo ""
+if [ "$INSTALL_MODE" = "global" ]; then
+  echo "이제 어떤 프로젝트에서든 Claude Code를 실행하면 자동으로 적용됩니다."
+else
+  echo "현재 프로젝트($(pwd))에서 Claude Code를 실행하면 자동으로 적용됩니다."
+  echo "다른 프로젝트에도 적용하려면 --global 옵션을 사용하세요."
+fi