@choblue/claude-code-toolkit 1.2.2 → 1.2.4

package/.claude/.project-map-cache

@@ -1 +1 @@
-af82e0967a0412bdcaa636fa0ab9e4f750d49608
+27c83ec4fadcaf1ee2f771651fa76d31262a831a

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

@@ -253,7 +253,142 @@ function UserContent({ isLoading, error, data }: UserContentProps) {
 
 ---
 
-## 8. 금지 사항
+## 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. 금지 사항
 
 - `any` 타입 사용 금지
 - 인라인 스타일(`style={{}}`) 사용 금지 - 프로젝트 스타일링 방식을 따른다
@@ -263,4 +398,10 @@ function UserContent({ isLoading, error, data }: UserContentProps) {
 - `React.FC` 사용 금지
 - 배열 인덱스를 `key`로 사용 금지 (정적 리스트 제외)
 - `useEffect` 내에서 상태 동기화 로직 작성 금지 (파생값으로 처리)
-- Props drilling이 3단계 이상일 때 Context 또는 상태 관리 라이브러리 미사용 금지
+- Props drilling이 3단계 이상일 때 Context 또는 상태 관리 라이브러리 미사용 금지
+- 서버 상태(API 데이터)를 `useState` + `useEffect`로 관리 금지 (서버 상태 라이브러리 사용)
+- 각 함수/컴포넌트마다 try-catch 남발 금지 (에러 경계에서 일괄 처리)
+- `<div onClick>`, `<span onClick>` 금지 (`<button>` 또는 `<a>` 사용)
+- 아이콘 버튼에 `aria-label` 누락 금지
+- `outline: none` 단독 사용 금지 (`focus-visible` 대체 필수)
+- 입력 필드에 `onPaste` 차단 금지

package/.claude/skills/TailwindCSS/SKILL.md

@@ -361,7 +361,43 @@ export function Button({ variant, size, className, ...props }: ButtonProps) {
 
 ---
 
-## 8. 금지 사항
+## 8. 트랜지션 & 모션
+
+### transition 속성 명시
+- `transition-all` 사용을 금지한다 - 변경되는 속성만 명시한다
+- 불필요한 속성까지 트랜지션되면 성능이 저하된다
+
+```typescript
+// Bad - 모든 속성에 트랜지션
+<button className="transition-all">
+
+// Good - 필요한 속성만
+<button className="transition-colors">
+<div className="transition-[transform,opacity]">
+```
+
+### prefers-reduced-motion 존중
+- 애니메이션/트랜지션이 있는 요소에는 `motion-reduce:` 변형을 고려한다
+
+```typescript
+// 모션 감소 선호 시 애니메이션 비활성화
+<div className="animate-bounce motion-reduce:animate-none">
+<div className="transition-transform motion-reduce:transition-none">
+```
+
+### 다크 모드 color-scheme
+- 다크 모드 지원 시 `color-scheme: dark`를 설정하여 네이티브 UI(스크롤바, 입력 필드 등)도 다크 테마에 맞춘다
+
+```css
+/* app.css */
+.dark {
+  color-scheme: dark;
+}
+```
+
+---
+
+## 9. 금지 사항
 
 - 인라인 `style={{}}` 사용 금지 - Tailwind 유틸리티 클래스를 사용한다
 - 임의값(arbitrary values) 남용 금지 - `w-[137px]` 같은 임의값은 최소화한다
@@ -373,6 +409,7 @@ export function Button({ variant, size, className, ...props }: ButtonProps) {
 - Tailwind 기본 테마 토큰 삭제 금지 - `@theme`에서 필요한 토큰만 추가한다
 - 사용하지 않는 커스텀 색상/간격 정의 금지 - 실제 사용하는 값만 정의한다
 - `tailwind.config.ts` 사용 금지 - v4에서는 CSS `@theme`으로 설정한다
+- `transition-all` 사용 금지 - 변경되는 속성만 명시한다 (`transition-colors`, `transition-opacity` 등)
 - 클래스 문자열 동적 생성 금지 - Tailwind의 JIT가 감지하지 못한다
 
 ```typescript

package/.claude/skills/TanStackQuery/SKILL.md

@@ -237,7 +237,56 @@ const queryClient = new QueryClient({
 
 ---
 
-## 9. 금지 사항
+## 9. 캐시 전략 가이드
+
+데이터 특성에 따라 `staleTime`을 다르게 설정한다.
+
+| 데이터 유형 | staleTime | 예시 |
+|------------|-----------|------|
+| 거의 안 바뀜 | `Infinity` | 코드 테이블, 카테고리 목록, 약관 |
+| 가끔 바뀜 | `10~30분` | 사용자 프로필, 설정 |
+| 자주 바뀜 | `1~5분` | 게시글 목록, 댓글 |
+| 실시간 필요 | `0` | 채팅, 알림, 재고 수량 |
+
+### 도메인별 staleTime 설정
+
+```typescript
+// queryKey 팩토리에서 기본 옵션을 함께 관리
+export const categoryKeys = {
+  all: ['categories'] as const,
+  list: () => [...categoryKeys.all, 'list'] as const,
+};
+
+// 거의 안 바뀌는 데이터
+useQuery({
+  queryKey: categoryKeys.list(),
+  queryFn: fetchCategories,
+  staleTime: Infinity,
+});
+
+// 자주 바뀌는 데이터
+useQuery({
+  queryKey: postKeys.list(filters),
+  queryFn: () => fetchPosts(filters),
+  staleTime: 1000 * 60,  // 1분
+});
+```
+
+### 실시간 데이터: refetchInterval 사용
+
+```typescript
+// 폴링 방식 (WebSocket이 없을 때)
+useQuery({
+  queryKey: ['notifications'],
+  queryFn: fetchNotifications,
+  staleTime: 0,
+  refetchInterval: 1000 * 30,  // 30초마다 재요청
+});
+```
+
+---
+
+## 10. 금지 사항
 
 - `useEffect`로 데이터 페칭 금지 - TanStack Query를 사용한다
 - queryKey 하드코딩 금지 - queryKey 팩토리 패턴을 사용한다

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@choblue/claude-code-toolkit",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Claude Code 서브에이전트 위임 툴킷 - npx로 바로 설치",
   "bin": {
     "claude-code-toolkit": "bin/cli.js"