npm - @choblue/claude-code-toolkit - Versions diffs - 1.2.6 → 1.2.7 - Mend

@choblue/claude-code-toolkit 1.2.6 → 1.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/.claude/.project-map-cache +1 -1
package/.claude/CLAUDE.md +58 -18
package/.claude/hooks/prompt-hook.sh +4 -4
package/.claude/skills/Coding/SKILL.md +5 -4
package/.claude/skills/{Coding/backend.md → NestJS/SKILL.md} +7 -2
package/.claude/skills/NextJS/SKILL.md +13 -303
package/.claude/skills/NextJS/references/data-fetching.md +96 -0
package/.claude/skills/NextJS/references/middleware-actions.md +74 -0
package/.claude/skills/NextJS/references/optimization.md +127 -0
package/.claude/skills/Planning/SKILL.md +30 -7
package/.claude/skills/React/SKILL.md +25 -287
package/.claude/skills/React/references/a11y-ux.md +134 -0
package/.claude/skills/React/references/rendering-patterns.md +62 -0
package/.claude/skills/React/references/state-hooks.md +73 -0
package/.claude/skills/ReactHookForm/SKILL.md +8 -196
package/.claude/skills/ReactHookForm/references/advanced-patterns.md +193 -0
package/.claude/skills/TDD/SKILL.md +2 -2
package/.claude/skills/TailwindCSS/SKILL.md +14 -240
package/.claude/skills/TailwindCSS/references/patterns-components.md +93 -0
package/.claude/skills/TailwindCSS/references/responsive-dark.md +102 -0
package/.claude/skills/TailwindCSS/references/transitions.md +33 -0
package/README.md +15 -10
package/package.json +1 -1
package/.claude/skills/Coding/frontend.md +0 -11
/package/.claude/skills/TDD/{backend.md → references/backend.md} +0 -0
/package/.claude/skills/TDD/{frontend.md → references/frontend.md} +0 -0

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

@@ -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 CHANGED Viewed

@@ -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% 완성한다.

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

@@ -16,8 +16,8 @@ React 컴포넌트 설계 및 개발에 적용되는 핵심 규칙이다.
 - 클래스 컴포넌트를 사용하지 않는다
 - `React.FC`를 사용하지 않는다 - Props를 직접 타이핑한다
-### Props interface 명시
-- 모든 컴포넌트는 Props 타입을 `interface`로 선언한다
+### Props 타입 명시
+- 모든 컴포넌트는 Props 타입을 `type`으로 선언한다
 - Props 네이밍은 `컴포넌트명 + Props`로 한다
 ### SRP (Single Responsibility Principle)
@@ -35,9 +35,9 @@ const UserPage = () => {
 };
 // Good
-interface UserPageProps {
+type UserPageProps = {
   userId: string;
-}
+};
 export function UserPage({ userId }: UserPageProps) {
   const { user, isLoading } = useUser(userId);
@@ -68,16 +68,16 @@ export function UserPage({ userId }: UserPageProps) {
 ```typescript
 // Bad
-interface ButtonProps {
+type ButtonProps = {
   clickHandler: () => void;
   deleteCallback: () => void;
-}
+};
 // Good
-interface ButtonProps {
+type ButtonProps = {
   onClick: () => void;
   onDelete: () => void;
-}
+};
 ```
 ### 객체 통째 전달 지양
@@ -86,157 +86,20 @@ interface ButtonProps {
 ```typescript
 // Bad - 불필요한 데이터까지 전달
-interface UserAvatarProps {
+type UserAvatarProps = {
   user: User; // user.name, user.avatar만 사용하는데 전체 객체 전달
-}
+};
 // Good - 필요한 값만 전달
-interface UserAvatarProps {
+type 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. 네이밍 컨벤션
+## 3. 네이밍 컨벤션
 | 대상 | 규칙 | 예시 |
 |------|------|------|
@@ -253,142 +116,7 @@ function UserContent({ isLoading, error, data }: UserContentProps) {
 ---
-## 8. 에러 처리
-### 원칙: 에러 처리를 각 함수/컴포넌트에 흩뿌리지 않는다
-- 각 함수마다 try-catch를 덕지덕지 붙이지 않는다
-- `useState`로 에러 상태를 직접 관리하지 않는다 (TanStack Query가 제공)
-- 에러 처리는 **경계(Boundary)**에서 한 번에 처리한다
-### API 에러: 서버 상태 라이브러리에 위임
-```typescript
-// Bad - useState + useEffect로 에러 직접 관리
-function UserList() {
-  const [error, setError] = useState<Error | null>(null);
-  const [data, setData] = useState(null);
-  const [loading, setLoading] = useState(false);
-  useEffect(() => {
-    setLoading(true);
-    fetchUsers()
-      .then(setData)
-      .catch(setError)
-      .finally(() => setLoading(false));
-  }, []);
-}
-// Good - 서버 상태 라이브러리가 에러를 관리
-function UserList() {
-  const { data: users, isLoading, error } = useUserList();
-  if (error) return <ErrorDisplay error={error} />;
-}
-```
-### 렌더링 에러: Error Boundary
-```typescript
-<ErrorBoundary fallback={<ErrorFallback />}>
-  <UserContent />
-</ErrorBoundary>
-```
-### 전역 API 에러: interceptor 또는 라이브러리 설정에서 일괄 처리
-- axios interceptor, QueryClient defaultOptions 등 프로젝트 설정에 따른다
-- 개별 컴포넌트가 아닌 앱 수준에서 에러 알림(toast 등)을 처리한다
-### 에러 UI 분기: early return 패턴
-```typescript
-function UserPage({ userId }: UserPageProps) {
-  const { data: user, isLoading, error } = useUser(userId);
-  if (isLoading) return <Skeleton />;
-  if (error) return <ErrorDisplay error={error} />;
-  if (!user) return <EmptyState />;
-  return <UserContent user={user} />;
-}
-```
----
-## 9. 접근성 (a11y)
-### 시맨틱 HTML 사용
-- 클릭 가능한 요소는 반드시 `<button>` 또는 `<a>`를 사용한다
-- `<div onClick>`, `<span onClick>`을 금지한다
-```typescript
-// Bad
-<div onClick={handleDelete} className="cursor-pointer">삭제</div>
-// Good
-<button type="button" onClick={handleDelete}>삭제</button>
-```
-### 아이콘 버튼에 aria-label 필수
-```typescript
-// Bad - 스크린 리더가 내용을 알 수 없음
-<button onClick={onClose}><XIcon /></button>
-// Good
-<button onClick={onClose} aria-label="닫기"><XIcon /></button>
-```
-### 이미지에 alt, width, height 필수
-```typescript
-// Bad
-<img src={user.avatar} />
-// Good
-<img src={user.avatar} alt={`${user.name} 프로필`} width={40} height={40} />
-```
-### focus-visible 보장
-- `outline: none`을 사용할 때 반드시 `focus-visible` 대체 스타일을 제공한다
-```typescript
-// Bad - 포커스 표시 완전 제거
-<button className="outline-none">
-// Good - 키보드 포커스 시 표시
-<button className="outline-none focus-visible:ring-2 focus-visible:ring-blue-500">
-```
-### 폼 접근성
-- 모든 입력 필드에 `<label>` 또는 `aria-label`을 연결한다
-- 적절한 `type`, `inputMode`, `autoComplete` 속성을 사용한다
-- 붙여넣기(`onPaste`)를 차단하지 않는다
----
-## 10. UX 패턴
-### 파괴적 액션에 확인 단계
-- 삭제, 초기화 등 되돌릴 수 없는 동작에는 확인 UI를 추가한다
-### URL 파라미터와 UI 상태 동기화
-- 탭, 필터, 페이지 등 공유 가능한 UI 상태는 URL 파라미터에 반영한다
-```typescript
-// Bad - 새로고침하면 상태 소실
-const [tab, setTab] = useState('overview');
-// Good - URL에 상태 반영 (deep-link 가능)
-const [searchParams, setSearchParams] = useSearchParams();
-const tab = searchParams.get('tab') ?? 'overview';
-```
-### 대규모 리스트 가상화
-- 50개 이상의 항목을 렌더링할 때는 가상화 라이브러리를 사용한다
-- `@tanstack/react-virtual`, `react-window` 등을 활용한다
----
-## 11. 금지 사항
+## 4. 금지 사항
 - `any` 타입 사용 금지
 - 인라인 스타일(`style={{}}`) 사용 금지 - 프로젝트 스타일링 방식을 따른다
@@ -404,4 +132,14 @@ const tab = searchParams.get('tab') ?? 'overview';
 - `<div onClick>`, `<span onClick>` 금지 (`<button>` 또는 `<a>` 사용)
 - 아이콘 버튼에 `aria-label` 누락 금지
 - `outline: none` 단독 사용 금지 (`focus-visible` 대체 필수)
-- 입력 필드에 `onPaste` 차단 금지
+- 입력 필드에 `onPaste` 차단 금지
+---
+## 심화 참조
+| 파일 | 설명 |
+|------|------|
+| `references/state-hooks.md` | 상태 관리 원칙 (배치, 파생값, 서버/클라이언트 분리) + 커스텀 훅 패턴 |
+| `references/rendering-patterns.md` | 렌더링 최적화 (useMemo/useCallback, key) + 조건부 렌더링 패턴 |
+| `references/a11y-ux.md` | 에러 처리 (Error Boundary, 서버 상태 위임) + 접근성 (시맨틱 HTML, aria-label, focus-visible) + UX 패턴 (파괴적 액션 확인, URL 동기화, 가상화) |

package/.claude/skills/React/references/a11y-ux.md ADDED Viewed

@@ -0,0 +1,134 @@
+# 에러 처리, 접근성 (a11y) 및 UX 패턴
+## 1. 에러 처리
+### 원칙: 에러 처리를 각 함수/컴포넌트에 흩뿌리지 않는다
+- 각 함수마다 try-catch를 덕지덕지 붙이지 않는다
+- `useState`로 에러 상태를 직접 관리하지 않는다 (TanStack Query가 제공)
+- 에러 처리는 **경계(Boundary)**에서 한 번에 처리한다
+### API 에러: 서버 상태 라이브러리에 위임
+```typescript
+// Bad - useState + useEffect로 에러 직접 관리
+function UserList() {
+  const [error, setError] = useState<Error | null>(null);
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(false);
+  useEffect(() => {
+    setLoading(true);
+    fetchUsers()
+      .then(setData)
+      .catch(setError)
+      .finally(() => setLoading(false));
+  }, []);
+}
+// Good - 서버 상태 라이브러리가 에러를 관리
+function UserList() {
+  const { data: users, isLoading, error } = useUserList();
+  if (error) return <ErrorDisplay error={error} />;
+}
+```
+### 렌더링 에러: Error Boundary
+```typescript
+<ErrorBoundary fallback={<ErrorFallback />}>
+  <UserContent />
+</ErrorBoundary>
+```
+### 전역 API 에러: interceptor 또는 라이브러리 설정에서 일괄 처리
+- axios interceptor, QueryClient defaultOptions 등 프로젝트 설정에 따른다
+- 개별 컴포넌트가 아닌 앱 수준에서 에러 알림(toast 등)을 처리한다
+### 에러 UI 분기: early return 패턴
+```typescript
+function UserPage({ userId }: UserPageProps) {
+  const { data: user, isLoading, error } = useUser(userId);
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorDisplay error={error} />;
+  if (!user) return <EmptyState />;
+  return <UserContent user={user} />;
+}
+```
+---
+## 2. 접근성 (a11y)
+### 시맨틱 HTML 사용
+- 클릭 가능한 요소는 반드시 `<button>` 또는 `<a>`를 사용한다
+- `<div onClick>`, `<span onClick>`을 금지한다
+```typescript
+// Bad
+<div onClick={handleDelete} className="cursor-pointer">삭제</div>
+// Good
+<button type="button" onClick={handleDelete}>삭제</button>
+```
+### 아이콘 버튼에 aria-label 필수
+```typescript
+// Bad - 스크린 리더가 내용을 알 수 없음
+<button onClick={onClose}><XIcon /></button>
+// Good
+<button onClick={onClose} aria-label="닫기"><XIcon /></button>
+```
+### 이미지에 alt, width, height 필수
+```typescript
+// Bad
+<img src={user.avatar} />
+// Good
+<img src={user.avatar} alt={`${user.name} 프로필`} width={40} height={40} />
+```
+### focus-visible 보장
+- `outline: none`을 사용할 때 반드시 `focus-visible` 대체 스타일을 제공한다
+```typescript
+// Bad - 포커스 표시 완전 제거
+<button className="outline-none">
+// Good - 키보드 포커스 시 표시
+<button className="outline-none focus-visible:ring-2 focus-visible:ring-blue-500">
+```
+### 폼 접근성
+- 모든 입력 필드에 `<label>` 또는 `aria-label`을 연결한다
+- 적절한 `type`, `inputMode`, `autoComplete` 속성을 사용한다
+- 붙여넣기(`onPaste`)를 차단하지 않는다
+---
+## 3. UX 패턴
+### 파괴적 액션에 확인 단계
+- 삭제, 초기화 등 되돌릴 수 없는 동작에는 확인 UI를 추가한다
+### URL 파라미터와 UI 상태 동기화
+- 탭, 필터, 페이지 등 공유 가능한 UI 상태는 URL 파라미터에 반영한다
+```typescript
+// Bad - 새로고침하면 상태 소실
+const [tab, setTab] = useState('overview');
+// Good - URL에 상태 반영 (deep-link 가능)
+const [searchParams, setSearchParams] = useSearchParams();
+const tab = searchParams.get('tab') ?? 'overview';
+```
+### 대규모 리스트 가상화
+- 50개 이상의 항목을 렌더링할 때는 가상화 라이브러리를 사용한다
+- `@tanstack/react-virtual`, `react-window` 등을 활용한다