@choblue/claude-code-toolkit 1.2.6 → 1.2.7

package/.claude/.project-map-cache

@@ -1 +1 @@
-661df17b80c1e5d15cac0feb533ca658c67a5155
+97eedbf98bcf7cd6a3c3c2e61afd04ae61af9b7c

package/.claude/CLAUDE.md

@@ -70,33 +70,74 @@ Step 4: 수정/삭제 → 확인
 
 ---
 
-## 3. 티어별 워크플로우
+## 3. Task Header (의사결정 가시화)
+
+모든 티어에서 작업 시작 시 Task Header를 출력하여 의사결정을 가시화한다.
+
+### S 티어 헤더
+```
+📋 [작업명]
+⚡ S — [판단 근거 한 줄]
+📁 [대상 파일]
+```
+
+### M 티어 헤더
+```
+📋 [작업명]
+⚡ M — [판단 근거 한 줄]
+📚 [사용할 스킬 목록]
+🔄 [에이전트 흐름]
+📁 [예상 파일 수와 대상]
+```
+
+### L 티어 헤더
+```
+📋 [작업명]
+⚡ L — [판단 근거 한 줄]
+📚 [사용할 스킬 목록]
+🔄 [에이전트 흐름]
+📁 [예상 파일 수와 대상]
+📌 Plan:
+  ○ Step 1: [작업 단위]
+  ○ Step 2: [작업 단위]
+  ...
+```
+
+L 티어에서는 각 Step 진행에 따라 상태를 갱신한다:
+- `○` 대기 → `▶ ⏳` 진행 중 → `✔` 완료
+
+---
+
+## 4. 티어별 워크플로우
 
 ### S 티어 (trivial)
 Main Agent가 직접 처리한다. 서브에이전트 위임 불필요.
-1. 파일 읽기 → 직접 수정 → 완료
-2. 필요 시 `git-manager`로 커밋
+1. **Task Header 출력**
+2. 파일 읽기 → 직접 수정 → 완료
+3. 필요 시 `git-manager`로 커밋
 
 ### M 티어 (moderate)
 TDD/Review를 생략하고 핵심 단계만 수행한다.
-1. **Planning**: 요구사항 정리, 필요 시 `explore`로 탐색
-2. **Implementation**: `code-writer` 에이전트에 구현 위임 (단위별로 나눠 호출)
-3. **Commit**: `git-manager`로 커밋/PR 생성
+1. **Task Header 출력**
+2. **Planning**: 요구사항 정리, 필요 시 `explore`로 탐색
+3. **Implementation**: `code-writer` 에이전트에 구현 위임 (단위별로 나눠 호출)
+4. **Commit**: `git-manager`로 커밋/PR 생성
 
 ### L 티어 (complex)
 파일 기반 설계 후 **단위별로** 구현한다.
-1. **Research**: `explore`로 탐색 → `research.md` 작성 (관련 코드 분석, 제약 조건)
-2. **Plan**: `plan.md` 작성 (접근 방식, 변경 파일, 트레이드 오프, **단위별 작업 순서**)
-3. **주석 사이클**: 사용자가 plan.md에 메모 → 반영 → **승인 전까지 구현 금지**
-4. **Implementation + Test**: plan.md의 각 단위를 순서대로 `implementer`에 위임 (단위당 1회 호출)
-5. **Review**: `code-reviewer`로 리뷰 → `git-manager`로 커밋/PR
+1. **Task Header 출력**
+2. **Research**: `explore`로 탐색 → `research.md` 작성 (관련 코드 분석, 제약 조건)
+3. **Plan**: `plan.md` 작성 (접근 방식, 변경 파일, 트레이드 오프, **단위별 작업 순서**)
+4. **주석 사이클**: 사용자가 plan.md에 메모 → 반영 → **승인 전까지 구현 금지**
+5. **Implementation + Test**: plan.md의 각 단위를 순서대로 `implementer`에 위임 (단위당 1회 호출)
+6. **Review**: `code-reviewer`로 리뷰 → `git-manager`로 커밋/PR
 
 ### 풀스택 작업 (FE + BE 동시 변경)
 티어는 영향도 기준으로 판단하되, 위임 순서는 BE 선행 → FE 후행을 따른다.
 
 ---
 
-## 4. 문서 참조 가이드
+## 5. 문서 참조 가이드
 
 ### Agents (서브에이전트 프롬프트)
 - `.claude/agents/explore.md` - 코드베이스 탐색 전문가
@@ -108,9 +149,8 @@ TDD/Review를 생략하고 핵심 단계만 수행한다.
 - `.claude/agents/git-manager.md` - Git 작업 전문가
 
 ### Skills (도메인 지식)
-- `.claude/skills/Coding/` - 코딩 원칙 및 패턴
-  - `SKILL.md` - 공통 원칙
-  - `backend.md` - NestJS 백엔드 규칙
+- `.claude/skills/Coding/SKILL.md` - 공통 코딩 원칙
+- `.claude/skills/NestJS/SKILL.md` - NestJS 백엔드 규칙 (레이어, DTO, DI, 에러 핸들링)
 - `.claude/skills/React/SKILL.md` - React 컴포넌트, 훅, 상태 관리
 - `.claude/skills/NextJS/SKILL.md` - Next.js App Router, SSR, Server Actions
 - `.claude/skills/TailwindCSS/SKILL.md` - Tailwind CSS 유틸리티 패턴
@@ -121,8 +161,8 @@ TDD/Review를 생략하고 핵심 단계만 수행한다.
 - `.claude/skills/TypeORM/SKILL.md` - TypeORM Entity, Repository, QueryBuilder
 - `.claude/skills/TDD/` - TDD 테스트 원칙 및 패턴
   - `SKILL.md` - 공통 TDD 원칙
-  - `frontend.md` - React 테스트 규칙
-  - `backend.md` - NestJS 테스트 규칙
+  - `references/frontend.md` - React 테스트 규칙
+  - `references/backend.md` - NestJS 테스트 규칙
 - `.claude/skills/DDD/SKILL.md` - DDD 전술적 패턴 (Entity, VO, Aggregate, Repository, Domain Event)
 - `.claude/skills/Planning/SKILL.md` - 작업 계획 (티어 판단, 작업 분해, 의존성 확인)
 - `.claude/skills/Git/SKILL.md` - Git 커밋/PR/브랜치 규칙
@@ -143,7 +183,7 @@ TDD/Review를 생략하고 핵심 단계만 수행한다.
 
 ---
 
-## 5. 프로젝트별 오버라이드
+## 6. 프로젝트별 오버라이드
 
 프로젝트 루트에 `CLAUDE.md`가 있으면 이 글로벌 규칙보다 우선한다.
 프로젝트별 규칙은 글로벌 규칙을 확장하되, 충돌 시 프로젝트 규칙을 따른다.

package/.claude/hooks/prompt-hook.sh

@@ -12,10 +12,10 @@ INPUT=$(cat)
 
 # ─── 1. Quality Gate ───
 cat << 'EOF'
-[Quality Gate] 티어를 판단하고 워크플로우를 따르라.
-- S (1-2파일, 단순수정): Main Agent 직접 처리
-- M (3-5파일, 명확한 기능): code-writer → git-manager
-- L (6+파일, 설계 필요): 풀 프로세스 (TDD → 구현 → 리뷰)
+[Quality Gate] 티어를 판단하고 Task Header를 출력한 후 워크플로우를 따르라.
+- S: 📋 ⚡ 📁
+- M: 📋 ⚡ 📚 🔄 📁
+- L: 📋 ⚡ 📚 🔄 📁 📌Plan
 EOF
 
 # ─── 2. Skill Detector ───

package/.claude/skills/Coding/SKILL.md

@@ -6,9 +6,9 @@ description: 공통 코딩 원칙과 패턴. 코드 작성 시 항상 참조하
 # Coding Skill - 공통 원칙
 
 이 문서는 모든 코드 작성 시 적용되는 공통 원칙을 정의한다.
-FE/BE별 상세 규칙은 각각의 파일을 참고한다.
-- `frontend.md` - React 프론트엔드 규칙
-- `backend.md` - NestJS 백엔드 규칙
+FE/BE 상세 규칙은 기술별 스킬에서 다룬다.
+- BE: `../NestJS/SKILL.md`, `../TypeORM/SKILL.md`
+- FE: `../React/SKILL.md`, `../NextJS/SKILL.md`, `../TailwindCSS/SKILL.md` 등
 
 ---
 
@@ -208,4 +208,5 @@ try {
 - [ ] 시스템 경계에서 에러 핸들링이 되어 있는가?
 - [ ] 불필요한 복잡도가 없는가?
 - [ ] `any` 타입을 사용하지 않았는가?
-- [ ] 기존 프로젝트 패턴과 일관성이 있는가?
+- [ ] 기존 프로젝트 패턴과 일관성이 있는가?
+

package/.claude/skills/{Coding/backend.md → NestJS/SKILL.md}

@@ -1,7 +1,12 @@
-# Coding Skill - Backend (NestJS)
+---
+name: nestjs
+description: NestJS 백엔드 개발 가이드. 레이어별 책임, DTO, 에러 핸들링, DI, 네이밍 컨벤션 등 NestJS 코드 작성 시 참조한다.
+---
+
+# NestJS Skill - 백엔드 핵심 규칙
 
 NestJS 백엔드 코드에 적용되는 규칙이다.
-공통 원칙은 `SKILL.md`를 함께 참고한다.
+공통 코딩 원칙은 `../Coding/SKILL.md`를 함께 참고한다.
 
 ---
 

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

@@ -98,307 +98,7 @@ export function UserTabs() {
 
 ---
 
-## 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. 네이밍 컨벤션
+## 3. 네이밍 컨벤션
 
 | 대상 | 규칙 | 예시 |
 |------|------|------|
@@ -416,7 +116,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 ---
 
-## 11. 금지 사항
+## 4. 금지 사항
 
 - Client Component에서 무거운 데이터 페칭 로직 작성 금지
 - 불필요한 `'use client'` 선언 금지 - 서버에서 가능하면 서버에서 처리
@@ -426,4 +126,14 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 - `<img>` 태그 직접 사용 금지 - `next/image` 사용
 - 외부 폰트를 `<link>` 태그로 로드 금지 - `next/font` 사용
 - `router.push()`를 Server Component에서 사용 금지 - `redirect()` 사용
-- API Route에서 비즈니스 로직 직접 구현 금지 - 별도 서비스 레이어로 분리
+- API Route에서 비즈니스 로직 직접 구현 금지 - 별도 서비스 레이어로 분리
+
+---
+
+## 심화 참조
+
+| 파일 | 내용 |
+|------|------|
+| `references/data-fetching.md` | 데이터 페칭 (Server Component fetch, Revalidation) + Route Handlers (CRUD, 동적 라우트) |
+| `references/middleware-actions.md` | Middleware (인증, 리다이렉트, matcher) + Server Actions (form action, revalidation) |
+| `references/optimization.md` | Metadata (정적/동적) + 디렉토리 구조 패턴 (Route Groups, Parallel/Intercepting Routes) + Image/Font 최적화 |

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>
+  );
+}
+```