@choblue/claude-code-toolkit 1.0.0

package/.claude/skills/NextJS/SKILL.md

@@ -0,0 +1,424 @@
+# Next.js Skill - App Router 규칙
+
+Next.js App Router 기반 프로젝트에 적용되는 규칙이다.
+React 핵심 규칙은 `../React/SKILL.md`, 공통 원칙은 `../Coding/SKILL.md`를 함께 참고한다.
+
+---
+
+## 1. App Router 기본 구조
+
+### 예약 파일명
+App Router는 다음 예약 파일명을 사용한다.
+
+| 파일명 | 역할 | 설명 |
+|--------|------|------|
+| `page.tsx` | 페이지 | 해당 라우트의 UI |
+| `layout.tsx` | 레이아웃 | 하위 라우트 공유 레이아웃 |
+| `loading.tsx` | 로딩 UI | Suspense 기반 로딩 상태 |
+| `error.tsx` | 에러 UI | Error Boundary 기반 에러 처리 |
+| `not-found.tsx` | 404 UI | 리소스를 찾을 수 없을 때 |
+| `template.tsx` | 템플릿 | 네비게이션마다 새 인스턴스 생성 |
+| `default.tsx` | 기본 UI | Parallel Routes 기본 폴백 |
+
+### 기본 구조 예시
+```
+app/
+  layout.tsx          # 루트 레이아웃 (필수)
+  page.tsx            # 홈 페이지
+  loading.tsx         # 글로벌 로딩
+  error.tsx           # 글로벌 에러
+  not-found.tsx       # 404 페이지
+  users/
+    page.tsx          # /users
+    [id]/
+      page.tsx        # /users/:id
+      loading.tsx
+      error.tsx
+  api/
+    users/
+      route.ts        # API: /api/users
+```
+
+---
+
+## 2. Server Component vs Client Component
+
+### 기본 원칙
+- **모든 컴포넌트는 기본적으로 Server Component이다**
+- `'use client'`는 실제로 클라이언트 기능이 필요할 때만 선언한다
+- 서버에서 할 수 있는 일은 서버에서 처리한다
+
+### Client Component가 필요한 경우
+- `useState`, `useEffect` 등 React 훅 사용 시
+- 브라우저 API 접근 시 (`window`, `document`, `localStorage`)
+- 이벤트 핸들러 사용 시 (`onClick`, `onChange`)
+- 클라이언트 전용 라이브러리 사용 시
+
+### 분리 전략
+- `'use client'` 경계를 최대한 하위로 밀어내린다
+- 페이지 전체를 Client Component로 만들지 않는다
+
+```typescript
+// Bad - 페이지 전체를 Client Component로 선언
+'use client';
+
+export default function UserPage() {
+  const [tab, setTab] = useState('profile');
+  const users = await fetchUsers(); // Server에서 가능한 작업인데 Client로 선언
+
+  return <div>...</div>;
+}
+
+// Good - 클라이언트 기능만 분리
+// app/users/page.tsx (Server Component)
+export default async function UserPage() {
+  const users = await fetchUsers();
+
+  return (
+    <div>
+      <UserList users={users} />
+      <UserTabs /> {/* 이것만 Client Component */}
+    </div>
+  );
+}
+
+// components/UserTabs.tsx (Client Component)
+'use client';
+
+export function UserTabs() {
+  const [tab, setTab] = useState('profile');
+  return <Tabs value={tab} onChange={setTab} />;
+}
+```
+
+---
+
+## 3. 데이터 페칭
+
+### Server Component에서 직접 fetch
+- Server Component에서 `async/await`로 직접 데이터를 가져온다
+- `useEffect`로 데이터를 가져오지 않는다
+
+```typescript
+// Good - Server Component에서 직접 페칭
+export default async function UserPage({ params }: { params: { id: string } }) {
+  const user = await getUser(params.id);
+  return <UserProfile user={user} />;
+}
+```
+
+### Revalidation 전략
+- **Time-based**: `next: { revalidate: 60 }` - 일정 시간마다 갱신
+- **On-demand**: `revalidateTag()`, `revalidatePath()` - 특정 이벤트 시 갱신
+
+```typescript
+// Time-based revalidation
+const data = await fetch('https://api.example.com/users', {
+  next: { revalidate: 3600 }, // 1시간마다 갱신
+});
+
+// Tag-based revalidation
+const data = await fetch('https://api.example.com/users', {
+  next: { tags: ['users'] },
+});
+
+// Server Action에서 revalidation 트리거
+'use server';
+import { revalidateTag } from 'next/cache';
+
+export async function createUser(formData: FormData) {
+  await saveUser(formData);
+  revalidateTag('users');
+}
+```
+
+---
+
+## 4. Route Handlers
+
+### 위치 및 구조
+- `app/api/` 디렉토리 하위에 `route.ts` 파일로 정의한다
+- HTTP 메서드를 named export로 정의한다
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  const users = await getUsers();
+  return NextResponse.json(users);
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const user = await createUser(body);
+  return NextResponse.json(user, { status: 201 });
+}
+```
+
+### 동적 라우트
+```typescript
+// app/api/users/[id]/route.ts
+export async function GET(
+  request: NextRequest,
+  { params }: { params: { id: string } },
+) {
+  const user = await getUser(params.id);
+  if (!user) {
+    return NextResponse.json({ error: 'Not Found' }, { status: 404 });
+  }
+  return NextResponse.json(user);
+}
+
+export async function PUT(
+  request: NextRequest,
+  { params }: { params: { id: string } },
+) {
+  const body = await request.json();
+  const user = await updateUser(params.id, body);
+  return NextResponse.json(user);
+}
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: { id: string } },
+) {
+  await deleteUser(params.id);
+  return new NextResponse(null, { status: 204 });
+}
+```
+
+---
+
+## 5. Middleware
+
+### 용도
+- 인증/인가 체크
+- 리다이렉트 처리
+- 요청/응답 헤더 수정
+- 국제화(i18n) 라우팅
+
+### 작성 패턴
+```typescript
+// middleware.ts (프로젝트 루트)
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('token')?.value;
+
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/admin/:path*'],
+};
+```
+
+---
+
+## 6. Metadata
+
+### 정적 Metadata
+```typescript
+// app/about/page.tsx
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: '소개 - 서비스명',
+  description: '서비스 소개 페이지입니다.',
+};
+```
+
+### 동적 Metadata
+```typescript
+// app/users/[id]/page.tsx
+import type { Metadata } from 'next';
+
+export async function generateMetadata({
+  params,
+}: {
+  params: { id: string };
+}): Promise<Metadata> {
+  const user = await getUser(params.id);
+
+  return {
+    title: `${user.name} - 프로필`,
+    description: `${user.name}의 프로필 페이지입니다.`,
+  };
+}
+```
+
+---
+
+## 7. Server Actions
+
+### 정의 및 사용
+- `'use server'` 지시문으로 서버 액션을 정의한다
+- form의 `action` 속성이나 이벤트 핸들러에서 호출한다
+
+```typescript
+// actions/user.ts
+'use server';
+
+import { revalidatePath } from 'next/cache';
+
+export async function createUser(formData: FormData) {
+  const name = formData.get('name') as string;
+  const email = formData.get('email') as string;
+
+  await db.user.create({ data: { name, email } });
+  revalidatePath('/users');
+}
+
+export async function deleteUser(userId: string) {
+  await db.user.delete({ where: { id: userId } });
+  revalidatePath('/users');
+}
+```
+
+### Form에서 사용
+```typescript
+// components/CreateUserForm.tsx
+import { createUser } from '@/actions/user';
+
+export function CreateUserForm() {
+  return (
+    <form action={createUser}>
+      <input name="name" type="text" required />
+      <input name="email" type="email" required />
+      <button type="submit">생성</button>
+    </form>
+  );
+}
+```
+
+---
+
+## 8. 디렉토리 구조 패턴
+
+### Route Groups - `(group)`
+- URL에 영향을 주지 않고 라우트를 그룹화한다
+
+```
+app/
+  (marketing)/
+    about/page.tsx      # /about
+    blog/page.tsx       # /blog
+  (dashboard)/
+    layout.tsx          # dashboard 전용 레이아웃
+    settings/page.tsx   # /settings
+    profile/page.tsx    # /profile
+```
+
+### Private Folders - `_folder`
+- 라우팅에서 제외되는 내부 폴더
+
+```
+app/
+  _components/          # 라우팅에 포함되지 않음
+    Header.tsx
+    Footer.tsx
+  _lib/                 # 내부 유틸리티
+    utils.ts
+```
+
+### Parallel Routes - `@slot`
+- 동일 레이아웃에서 여러 페이지를 동시에 렌더링한다
+
+```
+app/
+  layout.tsx            # children + @analytics + @team 동시 렌더링
+  @analytics/
+    page.tsx
+  @team/
+    page.tsx
+```
+
+### Intercepting Routes - `(.)`, `(..)`, `(...)`
+- 현재 레이아웃 내에서 다른 라우트를 가로채서 표시한다
+
+```
+app/
+  feed/
+    page.tsx
+    (..)photo/[id]/     # /photo/:id를 모달로 가로챔
+      page.tsx
+  photo/[id]/
+    page.tsx            # 직접 접근 시 전체 페이지
+```
+
+---
+
+## 9. Image/Font 최적화
+
+### next/image
+- 모든 이미지는 `next/image`를 사용한다
+- `width`, `height`를 명시하거나 `fill` 속성을 사용한다
+
+```typescript
+import Image from 'next/image';
+
+// 크기 지정
+<Image src="/hero.png" alt="히어로 이미지" width={800} height={400} />
+
+// fill 모드 (부모 기준 채움)
+<div className="relative h-64 w-full">
+  <Image src="/banner.png" alt="배너" fill className="object-cover" />
+</div>
+```
+
+### next/font
+- Google Fonts는 `next/font/google`을 사용한다
+- 커스텀 폰트는 `next/font/local`을 사용한다
+
+```typescript
+// app/layout.tsx
+import { Inter } from 'next/font/google';
+
+const inter = Inter({ subsets: ['latin'] });
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="ko" className={inter.className}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+---
+
+## 10. 네이밍 컨벤션
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 페이지 파일 | `page.tsx` (예약) | `app/users/page.tsx` |
+| 레이아웃 파일 | `layout.tsx` (예약) | `app/layout.tsx` |
+| 로딩 파일 | `loading.tsx` (예약) | `app/users/loading.tsx` |
+| 에러 파일 | `error.tsx` (예약) | `app/users/error.tsx` |
+| API 라우트 | `route.ts` (예약) | `app/api/users/route.ts` |
+| Server Action 파일 | `camelCase.ts` | `actions/createUser.ts` |
+| Server Action 함수 | `camelCase` | `createUser`, `deletePost` |
+| Route Group | `(groupName)` | `(marketing)`, `(dashboard)` |
+| Private Folder | `_folderName` | `_components`, `_lib` |
+| Dynamic Segment | `[param]` | `[id]`, `[slug]` |
+| Catch-all Segment | `[...param]` | `[...slug]` |
+
+---
+
+## 11. 금지 사항
+
+- Client Component에서 무거운 데이터 페칭 로직 작성 금지
+- 불필요한 `'use client'` 선언 금지 - 서버에서 가능하면 서버에서 처리
+- Pages Router 패턴 사용 금지 (`getServerSideProps`, `getStaticProps`, `_app.tsx`, `_document.tsx`)
+- `page.tsx`에 `'use client'` 직접 선언 금지 - 클라이언트 로직은 하위 컴포넌트로 분리
+- Server Component에서 `useState`, `useEffect` 등 클라이언트 훅 사용 금지
+- `<img>` 태그 직접 사용 금지 - `next/image` 사용
+- 외부 폰트를 `<link>` 태그로 로드 금지 - `next/font` 사용
+- `router.push()`를 Server Component에서 사용 금지 - `redirect()` 사용
+- API Route에서 비즈니스 로직 직접 구현 금지 - 별도 서비스 레이어로 분리

package/.claude/skills/React/SKILL.md

@@ -0,0 +1,261 @@
+# React Skill - React 핵심 규칙
+
+React 컴포넌트 설계 및 개발에 적용되는 핵심 규칙이다.
+공통 코딩 원칙은 `../Coding/SKILL.md`를 함께 참고한다.
+
+---
+
+## 1. 컴포넌트 설계 원칙
+
+### 함수형 컴포넌트만 사용한다
+- 클래스 컴포넌트를 사용하지 않는다
+- `React.FC`를 사용하지 않는다 - Props를 직접 타이핑한다
+
+### Props interface 명시
+- 모든 컴포넌트는 Props 타입을 `interface`로 선언한다
+- Props 네이밍은 `컴포넌트명 + Props`로 한다
+
+### SRP (Single Responsibility Principle)
+- 하나의 컴포넌트는 하나의 역할만 수행한다
+- "이 컴포넌트가 하는 일"을 한 문장으로 설명할 수 없으면 분리한다
+
+### 크기 제한
+- 컴포넌트는 최대 200줄을 넘기지 않는다
+- 200줄을 초과하면 하위 컴포넌트로 분리한다
+
+```typescript
+// Bad
+const UserPage = () => {
+  // 200줄 이상의 거대한 컴포넌트
+};
+
+// Good
+interface UserPageProps {
+  userId: string;
+}
+
+export function UserPage({ userId }: UserPageProps) {
+  const { user, isLoading } = useUser(userId);
+
+  if (isLoading) return <UserSkeleton />;
+  if (!user) return <UserNotFound />;
+
+  return (
+    <div>
+      <UserHeader user={user} />
+      <UserContent user={user} />
+      <UserActions userId={user.id} />
+    </div>
+  );
+}
+```
+
+---
+
+## 2. Props 설계
+
+### 최소한의 Props
+- 컴포넌트가 실제로 사용하는 값만 전달한다
+- Props가 5개를 초과하면 설계를 재검토한다
+
+### 콜백 네이밍
+- Props로 전달하는 콜백은 `on` + 동사로 네이밍한다
+
+```typescript
+// Bad
+interface ButtonProps {
+  clickHandler: () => void;
+  deleteCallback: () => void;
+}
+
+// Good
+interface ButtonProps {
+  onClick: () => void;
+  onDelete: () => void;
+}
+```
+
+### 객체 통째 전달 지양
+- 필요한 프로퍼티만 개별적으로 전달한다
+- 단, Props가 너무 많아지면 객체 전달을 허용한다
+
+```typescript
+// Bad - 불필요한 데이터까지 전달
+interface UserAvatarProps {
+  user: User; // user.name, user.avatar만 사용하는데 전체 객체 전달
+}
+
+// Good - 필요한 값만 전달
+interface UserAvatarProps {
+  name: string;
+  avatarUrl: string;
+}
+```
+
+---
+
+## 3. 상태 관리 원칙
+
+### 가까운 곳에 배치
+- 상태는 그것을 사용하는 가장 가까운 컴포넌트에 배치한다
+- 상위 컴포넌트로의 lifting은 실제로 필요할 때만 수행한다
+
+### 파생값은 상태가 아니다
+- 기존 상태에서 계산할 수 있는 값은 별도 상태로 만들지 않는다
+
+```typescript
+// Bad - 파생값을 상태로 관리
+const [items, setItems] = useState<Item[]>([]);
+const [itemCount, setItemCount] = useState(0);
+// items가 변경될 때마다 setItemCount를 호출해야 함
+
+// Good - 파생값은 계산
+const [items, setItems] = useState<Item[]>([]);
+const itemCount = items.length;
+```
+
+### 서버 상태와 클라이언트 상태 분리
+- **서버 상태**: API에서 가져온 데이터 -> React Query / SWR 사용
+- **클라이언트 상태**: UI 상태 (모달 열림, 탭 선택 등) -> useState / useReducer 사용
+- 서버 데이터를 `useState`로 복사하지 않는다
+
+---
+
+## 4. 커스텀 훅
+
+### use 접두사
+- 모든 커스텀 훅은 `use`로 시작한다
+
+### 하나의 관심사
+- 하나의 훅은 하나의 관심사만 다룬다
+
+### 데이터 페칭/상태 로직 분리
+- 컴포넌트에서 데이터 페칭과 상태 로직을 커스텀 훅으로 분리한다
+
+```typescript
+// Bad - 컴포넌트에 로직이 섞여 있음
+function UserList() {
+  const [users, setUsers] = useState<User[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    setIsLoading(true);
+    fetchUsers()
+      .then(setUsers)
+      .catch(setError)
+      .finally(() => setIsLoading(false));
+  }, []);
+
+  // ... 렌더링
+}
+
+// Good - 커스텀 훅으로 분리
+function useUserList() {
+  const { data: users = [], isLoading, error } = useQuery({
+    queryKey: ['users'],
+    queryFn: fetchUsers,
+  });
+
+  return { users, isLoading, error };
+}
+
+function UserList() {
+  const { users, isLoading, error } = useUserList();
+  // ... 렌더링만 담당
+}
+```
+
+---
+
+## 5. 렌더링 최적화
+
+### 불필요한 useMemo/useCallback 금지
+- 성능 문제가 실제로 측정된 경우에만 사용한다
+- 참조 동일성이 필요한 경우(의존성 배열, memo된 자식 컴포넌트)에만 사용한다
+
+```typescript
+// Bad - 불필요한 메모이제이션
+const userName = useMemo(() => `${first} ${last}`, [first, last]);
+
+// Good - 단순 계산은 그냥 수행
+const userName = `${first} ${last}`;
+```
+
+### key 올바르게 사용
+- 리스트 렌더링 시 고유한 식별자를 `key`로 사용한다
+- 배열 인덱스를 `key`로 사용하지 않는다 (정적 리스트 제외)
+
+```typescript
+// Bad
+{items.map((item, index) => (
+  <Item key={index} data={item} />
+))}
+
+// Good
+{items.map((item) => (
+  <Item key={item.id} data={item} />
+))}
+```
+
+---
+
+## 6. 조건부 렌더링 패턴
+
+### 단순 조건
+- 2개 이하의 조건은 삼항 연산자 또는 `&&`를 사용한다
+
+```typescript
+// 단순 표시/숨김
+{isVisible && <Modal />}
+
+// 이분기
+{isLoading ? <Skeleton /> : <Content />}
+```
+
+### 복잡한 조건
+- 3개 이상의 분기는 early return 또는 별도 컴포넌트로 분리한다
+
+```typescript
+// Bad - 중첩된 삼항
+{isLoading ? <Skeleton /> : error ? <Error /> : data ? <Content /> : <Empty />}
+
+// Good - early return
+function UserContent({ isLoading, error, data }: UserContentProps) {
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorDisplay error={error} />;
+  if (!data) return <EmptyState />;
+  return <Content data={data} />;
+}
+```
+
+---
+
+## 7. 네이밍 컨벤션
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 컴포넌트 파일 | `PascalCase.tsx` | `UserCard.tsx` |
+| 훅 파일 | `useCamelCase.ts` | `useAuth.ts` |
+| 유틸 파일 | `camelCase.ts` | `formatDate.ts` |
+| 컴포넌트 | `PascalCase` | `UserCard` |
+| 커스텀 훅 | `useCamelCase` | `useUserList` |
+| 이벤트 핸들러 | `handle` + 대상 + 동작 | `handleUserDelete` |
+| Props 콜백 | `on` + 동작 | `onDelete`, `onChange` |
+| Props 타입 | `컴포넌트명 + Props` | `UserCardProps` |
+| Context | `PascalCase + Context` | `AuthContext` |
+| Provider | `PascalCase + Provider` | `AuthProvider` |
+
+---
+
+## 8. 금지 사항
+
+- `any` 타입 사용 금지
+- 인라인 스타일(`style={{}}`) 사용 금지 - 프로젝트 스타일링 방식을 따른다
+- `useEffect` 의존성 배열 누락 금지
+- `index.tsx`에 컴포넌트 로직 직접 작성 금지 (re-export만 허용)
+- 클래스 컴포넌트 사용 금지
+- `React.FC` 사용 금지
+- 배열 인덱스를 `key`로 사용 금지 (정적 리스트 제외)
+- `useEffect` 내에서 상태 동기화 로직 작성 금지 (파생값으로 처리)
+- Props drilling이 3단계 이상일 때 Context 또는 상태 관리 라이브러리 미사용 금지