@choblue/claude-code-toolkit 1.2.5 → 1.2.7

package/.claude/skills/NextJS/references/data-fetching.md

@@ -0,0 +1,96 @@
+# 데이터 페칭 & Route Handlers
+
+## 데이터 페칭
+
+### 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');
+}
+```
+
+---
+
+## 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 });
+}
+```

package/.claude/skills/NextJS/references/middleware-actions.md

@@ -0,0 +1,74 @@
+# Middleware & Server Actions
+
+## 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*'],
+};
+```
+
+---
+
+## 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>
+  );
+}
+```

package/.claude/skills/NextJS/references/optimization.md

@@ -0,0 +1,127 @@
+# Metadata, 디렉토리 구조 패턴 & Image/Font 최적화
+
+## 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}의 프로필 페이지입니다.`,
+  };
+}
+```
+
+---
+
+## 디렉토리 구조 패턴
+
+### 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            # 직접 접근 시 전체 페이지
+```
+
+---
+
+## 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>
+  );
+}
+```

package/.claude/skills/Planning/SKILL.md

@@ -32,6 +32,22 @@ L 티어는 채팅이 아닌 **파일 기반**으로 설계를 진행한다. 세
 - [기술적 제약, 호환성 이슈 등]
 ```
 
+### Step 1.5: Task Header 출력
+research 후, plan 작성 전에 Task Header를 출력한다:
+```
+📋 [작업명]
+⚡ L — [판단 근거 한 줄]
+📚 [사용할 스킬 목록]
+🔄 [에이전트 흐름]
+📁 [예상 파일 수와 대상]
+📌 Plan:
+  ○ Step 1: [작업 단위]
+  ○ Step 2: [작업 단위]
+  ...
+```
+각 Step 진행에 따라 상태를 갱신한다:
+- `○` 대기 → `▶ ⏳` 진행 중 → `✔` 완료
+
 ### Step 2: plan.md 작성
 research 기반으로 구현 계획을 작성한다.
 ```markdown
@@ -57,17 +73,24 @@ research 기반으로 구현 계획을 작성한다.
 3. **사용자가 승인할 때까지 구현하지 않는다**
 4. 승인 후 implementer 에이전트에 plan.md를 전달하여 구현한다
 
-## 3. M 티어 Planning: 채팅 기반
+## 3. M 티어 Planning: Task Header + 채팅 기반
 
-M 티어는 파일 없이 채팅에서 간단히 계획을 제시한다:
+M 티어는 Task Header를 출력한 후 바로 구현을 진행한다:
 ```
-**티어**: M
-**변경 범위**: [레이어 목록]
-**작업 목록**:
-1. [작업] → [담당 에이전트]
-2. [작업] → [담당 에이전트]
+📋 [작업명]
+⚡ M — [판단 근거 한 줄]
+📚 [사용할 스킬 목록]
+🔄 [에이전트 흐름]
+📁 [예상 파일 수와 대상]
 ```
 
+### Task Header 작성 규칙
+- **📋**: 사용자 요청을 한 줄로 요약
+- **⚡**: 티어 + 판단 근거 (예: `M — 단일 API 엔드포인트 추가`)
+- **📚**: 이 작업에서 참조할 스킬 (예: `Coding, TypeORM`)
+- **🔄**: 에이전트 실행 순서 (예: `code-writer-be → git-manager`)
+- **📁**: 변경 파일 수와 대상 (예: `3 files (service, controller, dto)`)
+
 ## 4. 작업 분해 원칙
 
 **"한 번에 하나, 완전하게"** — 전체를 한꺼번에 80%로 끝내지 말고, 단위별로 100% 완성한다.